# 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 `InMemoryMosCoordinationPort` 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 `MosCoordinationPort` 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.