stack/docs/scratchpads/f4-matrix-connector.md

F4 — Orchestrator chat connector + Matrix (#616)

• Issue: #616 · Branch: feat/f4-matrix-connector (off main; independent of #615) · Doctrine: north-star #613.

Phase 1 (this PR) — abstraction + scaffold

• src/fleet/connectors/types.ts: OrchestratorConnector (send/subscribe/health) + message/config types; thread-aware via optional threadId; DEFAULT_CONNECTOR_KIND=tmux.
• src/fleet/connectors/registry.ts: extensible factory registry; resolveConnectorKind (defaults tmux, back-compat); createConnector throws ConnectorNotImplementedError until Phase 2 registers factories.
• roster.schema.json: optional connector block (tmux|discord|matrix; matrix homeserver/user/room; secrets via env, never roster).
• Design doc docs/fleet/f4-matrix-connector.md: interface, config, Matrix CS-API mapping, Conduit-default infra, phasing.
• No fleet.ts changes → self-contained, zero conflict with stacked #615.

Verification

• 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON.

Phase 2+ (follow-ups, in the doc)

Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.

Phase 2a (feat/f4-matrix-client, stacked on #617) — Matrix CS-API client

• src/fleet/connectors/matrix.ts: MatrixConnector implements OrchestratorConnector over the Matrix client-server API (injectable fetch, no SDK). send → PUT m.room.message (thread-aware); subscribe → /sync long-poll loop using the pure parseSyncResponse; health → /versions + /whoami. registerMatrixConnector(env) registers the factory (token from MATRIX_ACCESS_TOKEN, never roster).
• Pure helpers buildMessageBody + parseSyncResponse make send/receive unit-testable.
• 13 Matrix tests + 7 registry = 20 connector tests green; tsc/eslint/prettier clean.
• Remaining Phase 2: init/configure connector-selection UX + roster-parse wiring (touches fleet.ts — after #615); systemd launch wiring; Conduit deploy guide.