feat(tess): persist durable session state

docs/scratchpads/tess-m2-002-durable-state.md

@@ -0,0 +1,63 @@
+# TESS-M2-002 — Durable Tess State
+
+- **Issue:** #708
+- **Task:** `TESS-M2-002` / `TESS-STA-001`, `TESS-SEC-007..008`
+- **Branch:** `feat/tess-durable-state`
+- **Base:** fresh `origin/main` at `e3b5113be21e51d015fa1ae54572929b2a4acd9f`
+- **Budget assumption:** 38K task estimate; no explicit cap. Use focused TDD plus workspace validation.
+
+## Objective
+
+Persist a Tess session's immutable identity, inbox/outbox idempotency state, checkpoints,
+handoffs, and approval bindings so a new service instance can recover it after a process
+restart or context compaction without replaying a completed message or applied side effect.
+
+## Plan
+
+1. Write recovery/idempotency tests first in `packages/agent/src/tess-durable-session.test.ts`.
+2. Add transport-neutral durable-state contracts/state machine in `packages/agent`.
+3. Add canonical PostgreSQL schema/migration and a gateway Drizzle repository adapter.
+4. Wire gateway service/module and reuse `tess:command-approval:*` durable approval semantics
+   for exact, actor/tenant/action-bound approval consumption.
+5. Test PGlite restart recovery with separate service instances sharing the same durable DB.
+6. Document the recovery/compaction operation and update Tess architecture evidence.
+7. Run focused, cold-cache, workspace, migration, review, commit, push, and open PR to `main`.
+
+## Required Evidence
+
+| Requirement | Primary evidence |
+| --- | --- |
+| Restart recovery | Test creates a second coordinator over unchanged durable store after simulated process death. |
+| No duplicate side effects | Duplicate ingress and post-restart dispatch assert one handler/effect invocation. |
+| Compaction survival | Checkpoint/handoff/reconstructed state preserve the same session identity and pending records. |
+| Durable approvals | Existing `tess:command-approval` record is consumed only once and survives a new authorization service instance. |
+| Handoff | Stored handoff is portable and reconstructed without live process state. |
+
+## Progress
+
+- Intake complete: PRD AC-TESS-06, threat TM-07/TM-08, and verification matrix reviewed.
+- Affected surfaces: `packages/agent`, `apps/gateway`, `packages/db`; auth/authorization and DB migration tests required.
+- TDD is required (security authorization and critical state mutation).
+
+## Risks
+
+- An external provider action cannot be atomically committed with the database. The outbox
+  gives the receiver a stable idempotency key; generic recovery never replays an ambiguous
+  `processing` effect, and completed effects are never redispatched.
+- PostgreSQL is canonical; PGlite is the local/restart test implementation.
+
+## Verification
+
+- TDD red: `pnpm --filter @mosaicstack/agent test src/tess-durable-session.test.ts`
+  initially failed because the durable-state module did not exist.
+- Focused green: 7 agent state-machine tests; 6 PGlite repository tests (including
+  close/reopen recovery and encrypted-at-rest redaction); 5 durable-approval tests; DB migration tests.
+- Full cold-cache green: `pnpm turbo run typecheck lint test --force` completed
+  88 tasks with zero cache hits; `pnpm format:check` and `git diff --check` passed.
+- Fresh worktree dependency install passed with
+  `pnpm install --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store`.
+  The default pnpm store path was inaccessible to this harness, so the explicit
+  user-owned store path was required.
+- Codex review identified plaintext durable payload risk; resolved by AES-256-GCM sealing
+  after redaction, with an at-rest ciphertext assertion in the PGlite suite.
+- Pending final clean review, commit, and PR.

docs/tess/ARCHITECTURE.md

@@ -41,7 +41,7 @@ Every call receives an immutable, server-derived actor/tenant/channel scope and
 
 `@mosaicstack/agent` owns the explicit `AgentRuntimeProviderRegistry`; duplicate provider IDs are rejected rather than replaced. Gateway owns `RuntimeProviderService`, which creates a frozen `RuntimeScope` from authenticated `ActorTenantScope` and trusted ingress channel/correlation metadata before every provider call. The service checks the declared provider capability before invoking a side effect and records metadata-only audit events (`providerId`, operation, outcome, actor/tenant/channel, correlation, and resource ID). It never records message bodies, idempotency keys, or approval references.
 
-Termination is fail-closed: a runtime approval verifier must consume a one-time, exact action binding for the provider, session, actor, tenant, channel, and correlation ID before `terminate` reaches a provider. Until the durable verifier is wired, the default verifier denies termination. This internal service introduces no HTTP endpoint; later Discord, CLI, MCP, and provider adapters consume the same gateway boundary.
+Termination is fail-closed: a runtime approval verifier consumes a one-time, exact action binding for the provider, session, actor, tenant, channel, and correlation ID before `terminate` reaches a provider. The verifier reuses the Redis-backed `tess:command-approval:*` store and its expiry/delete-on-consume semantics; it has no parallel approval store. This internal service introduces no HTTP endpoint; later Discord, CLI, MCP, and provider adapters consume the same gateway boundary.
 
 ## Authority Model
 
@@ -56,7 +56,30 @@ Termination is fail-closed: a runtime approval verifier must consume a one-time,
 
 A Tess session has stable `sessionId`, `tenantId`, `ownerId`, provider/runtime identity, ingress bindings, cursor, checkpoint, inbox/outbox, and idempotency records. Discord and CLI bind to the same authorized session. Ownership is verified server-side on every list/read/attach/send/terminate operation.
 
-Valkey may hold ephemeral coordination state; PostgreSQL is canonical for durable session bindings, approvals, audit, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.
+Valkey holds the existing short-lived, one-time command-approval records; PostgreSQL is canonical for durable session bindings, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.
+
+### M2 Durable Recovery
+
+`@mosaicstack/agent` owns a transport-neutral state machine and `apps/gateway` provides its
+PostgreSQL adapter. `tess_sessions` holds immutable identity; inbox/outbox records use a
+per-session unique idempotency key and transition `pending → processing → processed|delivered`.
+Checkpoints are immutable history scoped by session and checkpoint ID: the latest checkpoint
+supports compaction recovery, while a handoff always resolves the exact checkpoint it references.
+Recovery requeues only interrupted inbox work; an ambiguous `processing` outbox record is preserved
+until separately authorized reconciliation can establish its external delivery state.
+
+Provider sends travel through the existing `RuntimeProviderService` with the persisted outbox
+idempotency key. A normal dispatch claims exactly one outbox record and verifies its stored
+correlation and channel against the server-derived request scope; it never requeues or drains
+another live record. Inbox/outbox payloads and checkpoint cursor/summary pass through the existing
+secret/PII redactor and AES-256-GCM sealing before persistence; decryption occurs only in the
+scoped gateway repository path, and runtime audit remains metadata-only.
+
+An external effect cannot share a database transaction. If a process dies after an effect begins
+but before its terminal outbox transition, automatic recovery does not replay that ambiguous claim.
+It remains `processing` until separately authorized reconciliation can establish delivery state;
+completed effects are never redispatched. Operators can therefore restart the gateway/Pi service,
+reconstruct the session, and resume pending inbox work without relying on process-local state.
 
 ## Transport Strategy