stack/docs/scratchpads/tess-m4-001-mos-coordination.md

TESS-M4-001 — Mos Coordination

• Issue/task: #710 / TESS-M4-001
• Branch/base: feat/tess-mos-coordination rebased onto origin/main f1c6b37b
• Budget assumption: task estimate 25K; design-first and TDD, with package contract plus gateway boundary only.

Objective

Implement a transport-neutral coordination contract allowing a configured interaction agent to hand off Mos-owned work, observe activity, and receive results while preventing it from gaining coding/general orchestration authority.

Plan

1. Document the contract and enforcement-point sketch; request Mos's decision on the initial concrete transport.
2. Add @mosaicstack/coord typed handoff/observe/result contracts and denial errors.
3. Add a gateway service which derives actor/tenant/requester identity from trusted context/configuration and validates authority.
4. Add contract and gateway boundary tests for configurable identities, self-delegation, target drift, and cross-tenant read denial.
5. Run focused, cold-cache, baseline tests; independent review; PR lifecycle.

Design checkpoint — 2026-07-12

Created docs/tess/MOS-COORDINATION.md. Mos approved the design and selected the native in-process InMemoryInteractionCoordinationPort for M4. Fleet/tmux remains a documented M5 adapter seam; no Mos-side consumer is built in this task.

Progress checkpoint — 2026-07-13

• Implemented InteractionCoordinationPort with handoff/observe/result only, an authority-checking client, and deterministic native adapter in @mosaicstack/coord.
• Implemented the gateway InteractionCoordinationService, deriving requester identity from trusted configuration and actor/tenant/correlation from authenticated context.
• Added contract and gateway boundary tests for configurable identities, native round-trip, unconfigured requester, self-delegation, target drift, and cross-tenant observe/result denial before adapter invocation.
• Did not modify apps/gateway/src/commands/command-authorization.service.ts.

Verification

• pnpm --filter @mosaicstack/coord test — PASS (16 tests after authority/idempotency remediation).
• pnpm --filter @mosaicstack/coord build — PASS.
• pnpm --filter @mosaicstack/gateway test -- mos-coordination.service.test.ts — PASS (7 tests after authority/idempotency remediation).
• Standalone gateway typecheck initially reported missing built workspace packages after fresh worktree setup; root validation builds the workspace graph and passed.
• TURBO_FORCE=true pnpm typecheck — PASS (42 tasks, 0 cached).
• TURBO_FORCE=true pnpm lint — PASS (23 tasks, 0 cached after one import-type remediation).
• TURBO_FORCE=true pnpm format:check — PASS.
• TURBO_FORCE=true pnpm test — PASS (42 tasks, 0 cached; expected existing integration skips only).

Review checkpoint

• Codex code review found idempotency keys needed actor scope and concurrent retries needed an in-flight reservation; both were remediated with regression coverage.
• Codex security review found whitespace-equivalent self-delegation was accepted by the exported client; identities are now normalized before invariant checks, with regression coverage.
• Re-review added immutable payload comparison for idempotency reuse, runtime string/size validation, bounded TTL/capacity tracking for gateway and native adapter state, and fresh-correlation follow-up reads; targeted tests pass (16 coord / 7 gateway).
• Final Codex security review found no issues. PR #735 was opened from commit 7936e15d; Woodpecker pipeline #1752 is green.