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

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

- [x] Canonical PRD and Tess architecture are current for this internal provider; no HTTP/API endpoint changed.
- [x] `docs/tess/ARCHITECTURE.md` documents the internal fleet target/identity, read-only attach, and Mos authority boundary.
- [x] 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.