stack/docs/scratchpads/tess-20260712.md

Scratchpad — Tess Interaction Agent

2026-07-12 — Mission intake

Objective: Build a Pi-native GPT-5.6 Sol high-reasoning Mosaic interaction agent, named Tess, as Jason's primary Discord/CLI access point for Mosaic fleet and transitional Hermes capabilities. Tess complements Mos and must not become a competing orchestrator.

Issue: #706

Budget: No explicit cap provided. Original working estimate was 290K implementation/review tokens. That estimate is superseded after six security prerequisite tasks were added; revised arithmetic total is pending because the calculation tool was blocked by runtime consent. Run at most two workers; prefer one implementation lane plus one independent review/discovery lane. Re-estimate after planning approval and each milestone.

Evidence gathered:

• Mosaic already provides Pi lifecycle hooks, fleet/tmux sessions, Matrix connector/controller pieces, typed chat events, Discord/Telegram channel plugins, and command/plugin registries.
• Current IProviderAdapter is an LLM model/completion abstraction, not an external agent/session provider.
• Required new seam is AgentRuntimeProvider: sessions, stream, message, terminate, hierarchy, attach, health, capabilities.
• Recurring cross-runtime needs: unified memory/retrieval, Discord routing/approvals, agent state/inbox/compaction recovery, runtime bootstrap, fleet/incident controls, and GitOps workflow.
• Project truth must remain in canonical project/Mosaic stores; semantic memory is retrieval/mirror.

Decisions:

1. Name: Tess (tessera). Stable machine key tess; display name configurable.
2. Mos owns orchestration; Tess delegates Mos-owned work through an explicit coordination contract.
3. Gateway owns ingress/auth/routing; Discord and CLI remain thin clients.
4. tmux/fleet ships first behind an adapter; Matrix/native Mosaic is the forward transport.
5. Hermes integration is transitional and capability-negotiated; unsupported operations fail closed.
6. No unrestricted Discord shell. Privileged/destructive/customer-visible actions require authorization and approval.

Plan:

1. Land requirements/architecture/task graph.
2. Deliver runtime contracts and security model.
3. Deliver durable Pi service/state.
4. Deliver Discord and CLI.
5. Deliver fleet/Mos/Hermes/memory/tool plugins.
6. Deliver Matrix/native transport, migration matrix, recovery, docs, and qualification.

Progress: Issue #706 created. PRD/manifest/tasks initialized on clean branch feat/tess-interaction-agent from origin/main.

Risks: 14 GB root filesystem headroom; active fleet lanes; broad migration scope; Discord privilege boundary; possible duplicate orchestration authority.

2026-07-12 — Independent planning and threat review

Verdict received: BLOCK TESS-PLAN-001. Coding remains stopped.

Blocking findings: formal threat model absent; verification matrix absent; migration inventory implied but absent; non-existent task paths; AC-TESS-03 lacked a crisp test. Security review also identified command scope bypass, cross-tenant session attachment, MCP actor impersonation, unsafe Discord service ingress, pre-persistence/egress secret leakage, non-durable replay, and globally scoped GC.

Remediation applied:

• Added docs/tess/ARCHITECTURE.md.
• Added docs/tess/THREAT-MODEL.md with TM-01..12.
• Added docs/tess/VERIFICATION-MATRIX.md mapping AC-TESS-01..11.
• Added docs/tess/MIGRATION-INVENTORY.md.
• Added hard requirements TESS-SEC-002..009.
• Added six prerequisite security tasks before provider/ingress implementation.
• Corrected task paths to existing package surfaces.
• Added explicit GPT-5.6 Sol/high/tool-policy status verification for AC-TESS-03.

Re-review 1: BLOCK only on composite repo values that looked like nonexistent paths. Remediated by declaring comma-separated roots and validating every root.

Final focused review: PASS. Deterministic audit validated all task repository roots with zero missing paths; no planning placeholders remained; security prerequisites still gate Tess exposure; observability traceability is explicit.

Current gate: planning PR must merge to main with terminal-green CI before any source-code worker starts.

2026-07-13 — M3 cross-surface delivery

Branch: feat/tess-m3-integration from main at 84d884b9.

Delivered: Stable Discord conversationId enrollment after a visible provider/runtime session is known; idempotent provider-session rebinding that preserves agent/tenant/owner scope; Discord approval/stop target resolution through the durable snapshot; SSE runtime streaming after CLI attach; denial/audit parity including provider authorization denials and HTTP 403 approval-denial mapping.

Evidence: Gateway targeted suite: 37 tests passed; Mosaic CLI interaction test passed; agent durable-session test passed; gateway and CLI typechecks passed; changed-file format and whitespace checks passed. Codex security review found no confident vulnerability. Code review identified a Fastify exception-response mismatch and two UX/acknowledgement issues; all were corrected before the final validation run.