# 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.
