stack/docs/scratchpads/tess-m1-003-fleet-provider.md

TESS-M1-003 — Fleet/tmux Runtime Provider

• Task: TESS-M1-003
• Issue: #707
• Branch: feat/tess-fleet-provider
• PR target: main
• Budget: 30K estimate from docs/tess/TASKS.md; work remains scoped to packages/mosaic, packages/agent, and Tess architecture/scratchpad documentation.

Objective

Implement TESS-FLT-001 as a tmux/fleet AgentRuntimeProvider on the M1 registry contract. Operations must use roster-bound, exact tmux targets; fail closed on missing or mismatched peer identity; allow read-only attach only; use exact-target message delivery and termination; and expose no arbitrary shell, socket, or fuzzy session targeting.

Requirements and Security Invariants

• TESS-FLT-001: fleet roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, controlled termination/recovery.
• TESS-ARP-001 / TESS-TRN-001: conform to the runtime provider contract and advertise only implemented capabilities.
• TM-10: exact target/socket binding and peer identity verification; wrong socket, target, or identity must refuse delivery/attach.
• Gateway supplies immutable actor/tenant/channel/correlation scope and consumes durable termination approvals before provider invocation.
• control attach is denied. A provider attach is a scoped read-only logical handle; it never opens a server-side interactive terminal or exposes a raw tmux target.
• M2 will make durable attachment/session state available. This M1 provider does not claim durable attachment handles or durable message idempotency.

Plan

1. Add security TDD cases first for fuzzy/unrostered targets, incorrect socket/identity, control attach, attachment scope replay, and termination exact targeting.
2. Add Mosaic fleet primitives for exact target validation and identity probing from the roster/socket.
3. Implement and export the fleet/tmux provider in @mosaicstack/agent, using only those primitives and a command-runner seam.
4. Update Tess architecture docs and this evidence log.
5. Run focused tests, independent code/security reviews, cold-cache forced gates, then create a PR with Refs #707.

Branch/Base Note

The orchestrator corrected the initial brief: feat/tess-interaction-agent is a stale planning branch. This branch was correctly created from origin/main at e92186d7 (including M1-002) and will open a clean PR to main with Refs #707.

Progress

• Read PRD, Tess architecture, threat model, runtime contract, registry, fleet command primitives, task record, and issue #707.
• Created clean worktree from origin/main at e92186d7.
• Security TDD tests written before implementation; initially failed because the transport/provider modules did not exist.
• Fleet transport and capability-limited provider implemented; read/list/attach and direct Tess write/control default to deny pending scope-aware authority adapters.
• Focused typecheck, lint, formatting, and abuse tests passed (transport: 7; provider: 14).
• Cold-cache forced workspace gates passed after reinstall; final workspace gates also passed.
• Independent Codex code and security reviews passed with no findings.

Verification Evidence

• pnpm --filter @mosaicstack/mosaic typecheck — pass.
• pnpm --filter @mosaicstack/agent typecheck — pass.
• pnpm --filter @mosaicstack/mosaic lint — pass.
• pnpm --filter @mosaicstack/agent lint — pass.
• pnpm --filter @mosaicstack/mosaic test -- src/fleet/tmux-runtime-transport.test.ts — 7 passed.
• pnpm --filter @mosaicstack/agent test -- src/tmux-fleet-runtime-provider.test.ts — 14 passed.
• The worktree dependency install must use --store-dir /home/jarvis/.local/share/pnpm/store because machine pnpm config points to an unreadable root-owned store. This is a local tool configuration issue, not an application workaround.

Documentation Checklist

• Canonical PRD and Tess architecture are current for this internal provider; no HTTP/API endpoint changed.
• docs/tess/ARCHITECTURE.md documents the internal fleet target/identity, read-only attach, and Mos authority boundary.
• No user/admin/API sitemap updates are applicable because no user-facing or HTTP API surface was introduced.

Acceptance Criteria to Evidence

Acceptance criterion	Evidence target
Only roster-bound exact targets are operated	Provider abuse tests prove unknown/prefix targets yield typed denial and runner is untouched.
Socket and peer runtime identity are exact	Provider abuse tests prove wrong socket/no pane/runtime drift deny before send/attach/terminate.
Message sends are capability-safe and exact	Tests assert the maintained sender receives only the configured socket and exact roster session.
Fleet reads cannot cross an authority boundary	Tests prove list and read attach default-deny without a scope-aware read authority; per-target authority filtering is enforced.
Attach cannot grant control or replay across scope	Tests deny control; attachment handles are random, scoped, short-lived, single-use for detach, and pruned after expiry.
Termination is exact and caller cannot select arbitrary target	Tests assert roster/identity validation precedes exact tmux kill-session -t =<agent>. Gateway tests from M1-002 cover approval consumption.
Documentation describes the boundary	docs/tess/ARCHITECTURE.md documents fleet capability, scope, and non-goals.

Risks / Decisions

• Runtime process identity can only be verified from the declared fleet roster and exact tmux pane command in M1. The tmux server itself is a trusted local transport boundary; stronger authenticated peer attestations are deferred to the Matrix/native provider.
• The current roster schema does not encode per-agent tenant/owner. Scope-aware read/write authority adapters remain the integration point for gateway/Mos ownership policy; provider scope is bound to logical attachment handles to prevent replay.