@jeffober/thatch 0.2.4 → 0.2.6

package/docs/dev/features/opencode-plugin.md

@@ -58,7 +58,7 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
 | Capability | v1 source | v2 source | v2 strategy |
 |---|---|---|---|
 | bus events | `event` hook | `event.subscribe` (raw SSE) | client-side location filter; location-less events resolve via `session.get` (`{sessionID}` input) and drop unresolvable (mirrors v1's server-side filter); events for plugin-created extraction children pass by ID (they live in the project directory, which differs from the instance directory on below-root launches) |
-| incoming message | `chat.message` hook | `session.hook("prompt")` | the hook awaits the runtime; nudge injections append to the OUTBOUND request's last user message in the generate hook (v2 wire `Message` carries parts in `content`, not `parts`) |
+| incoming message | `chat.message` hook | `session.hook("prompt")` | the hook awaits the runtime; nudge injections append to the OUTBOUND request's user message whose text matches the entry's stored prompt, in the context hook (v2 wire `Message` carries parts in `content`, not `parts`). Entries form a per-session set (cap 3, oldest evicted) so a prompt queued mid-turn keeps its own entry instead of evicting the running turn's; a prompt whose nudge computation comes up empty clears the session's whole set, so the running turn's remaining rounds lose their block in that one case (smaller than the staleness it prevents: an entry left behind would match its own prompt text in later requests' session history and replay a stale block there) |
 | system prompt | `experimental.chat.system.transform` | `session.hook("context")` | mutates the request's system array; the runtime's plain strings convert to `{type: "text", text}` SystemPart objects at the boundary |
 | compaction | `experimental.session.compacting` + `.autocontinue` + `session.compacted` | `session.hook("compaction")` | flag lands; context-injection surface unverified |
 | wrap-up commands | `command.execute.before` + command files | `command.transform` + `CommandEditor.add` | registered in code: `execute` arms the greenlight check (`onCommandExecuteBefore`) and delivers the same prompt body the v1 file carries, substituting the invocation's prompt text for `$ARGUMENTS` (v2's `session.prompt` does no template expansion); the runtime installs only ACTION command files on v2 and REMOVES stale wrap-up files from earlier v1 runs (a file and a registered command with the same name would collide) |
@@ -66,14 +66,15 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
 | tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts); the title is derived from the tool name and args (`deriveTitle`), since v2's `Tool.Result.output` is a typed output value, not a title |
 | noReply deliveries | `promptAsync` with `noReply` | none | gated off via `HostCapabilities.noReplyDelivery` -- chat echoes and the session-start reminder are skipped on v2 (delivering them would start real model turns: a feedback loop) |
 | synthetic wake deliveries | `promptAsync` with `synthetic` parts | `session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
-| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete degrades (extraction children are not cleaned up on v2 -- the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
+| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete rides `session.remove` (upstream #52387, in v2.0.22), runtime-guarded like compact -- an older host keeps the documented gap (the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
 | session status | `client.session.status` | none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
 | session messages | `client.session.messages` | `session.context` | mapped into the v1 `{info: {role}, parts}` shape, so the wrap-up greenlight check works (the promise domain has no `message` accessor) |
 | session list | `client.session.list` | none | degrade (`-c` resume listing loses its data source) |
-| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
-| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context; a `tui` companion plugin entrypoint is the known lift candidate) |
-| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984). On v2 the right target closes THIS session's tab (tab-scoped), not `app.exit`: the daemon hosts every tab; the `tui` companion entrypoint's `ui.tabs.close` is the known lift candidate) |
-| tab close | n/a | no session.deleted on v2 tab close | known gap: a closed tab's watchers keep polling until their TTL (deliveries fail their idle gate and stay pending); restart dormancy covers the daemon-restart case, not tab close |
+| compaction trigger | `client.tui.executeCommand("session_compact")` | `session.compact({sessionID})` | wired behind a runtime guard: upstream [#52385](https://github.com/anomalyco/opencode/pull/52385) exposed `session.compact` on the promise domain (in the installed v2.0.25), newer than the pinned dev types - an older host degrades to a logged no-op (the wrap-up checklist and flush still run, the automatic compaction is skipped) |
+| toasts | `client.tui.showToast` | toast rpc event | wired: every runtime toast call site (alerts, extraction metrics, chat registration, blocked wrap-ups, watcher rearm notices) emits the bridge's `toast` event, which the `./tui` plugin shows via `ui.toast.show`; the pump never translates it (TUI-only by nature). Best-effort by contract: a TUI-less environment or an rpc-less SDK floor shows nothing, silently |
+| wrap-up exit | `client.tui.publish` | exit-tab-closed rpc event | the wrap-up exit records the session's watcher deaths synchronously (the runtime, before the chat unregister - `sessionDied` places the death row by the chat row, so the order is load-bearing) and then emits `rpc.thatch-tabs.exit-tab-closed`, a TUI-ONLY close of the session's OWN tab (the `./tui` plugin's `ui.tabs.close`): the tab-scoped semantic upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984) asks for, since the daemon hosts every tab and `app.exit` would take down unrelated sessions. The pump deliberately never translates this event (a second death pass would erase the durable death row the first one wrote; the session_tab_close tool's `tab-closed` is the only death-translating event). Degrades to a logged no-op without the rpc surface; a TUI with no tab for the session (headless run, tabs off) never acts - the event is ephemeral |
+| session tabs | n/a | rpc event bridge | `thatch_session_tab` (v2Only) spawns a detached subordinate session (create -> move -> chat-register -> emit `rpc.thatch-tabs.tab-opened` -> prompt); the `./tui` CLI plugin consumes the event and calls `ui.tabs.open` (open-without-focus, idempotent). `thatch_session_tab_close` emits `rpc.thatch-tabs.tab-closed {sessionID, chatName}` - the pump translates it into the runtime's confirmed-death path. The registration's third event, `exit-tab-closed` (the wrap-up exit's), is TUI-only - see the wrap-up exit row |
+| tab close | n/a | no session.deleted on v2 tab close | bounded 2026-10-07: watcher death detection cancels a closed tab's watchers once its pending events age past `THATCH_WATCH_DEATH_MINUTES` (default 120) while deliveries throw 404-class errors, and announces the death to live same-project sessions; the roster row itself still lingers until the reaper. NOTE: an earlier version of this row claimed deliveries "fail their idle gate" - wrong: the v2 gate opens (the status stub reads as idle) and the PROMPT fails; same leak, different link |
 | wake gate after reload | `session.status` event map | map rehydrates empty | known gap: v2's fetchStatuses stub is structural (the promise context has no session.status), so in the reload window - until the session's next status event - the proactive-prompt gate is fully open |
 | dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; child rows carry a kind marker (extraction vs task-dispatched sub-agent, defaulting to extraction for pre-marker rows) so only extraction children restore the `extracting`/`extractionChildren` sets; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
 
@@ -89,20 +90,46 @@ suite runs green against a v2 serve.
 Still unverified against the live binary (static analysis only):
 
 - Whether `session.hook("prompt")` fires for `session.synthetic` inbox
-  items. If it does not, `pendingInjections` from the prior real turn gets
-  appended to the synthetic turn's outbound request.
+  items. If it does not, `pendingInjections` from the prior real turn would
+  be appended to the synthetic turn's outbound request. Structurally
+  bounded 2026-10-12: each `pendingInjections` entry is bound to the prompt
+  text it was computed from, and the context hook injects it only into a
+  request user message whose joined text equals that prompt - a replay onto
+  any other message (synthetic turn, missed prompt hook, failed
+  `onChatMessage`) is skipped. Text equality is the tightest binding
+  available, not an airtight one: an identical prompt re-submitted after a
+  missed prompt hook still matches and replays; the next prompt-hook run
+  that fires is the recovery. The prompt-time block still re-fires on every
+  round of its OWN turn (v1's persistent-synthetic-part semantics), and the
+  block carries a snapshot footer stating the labels are a submission-time
+  snapshot and pointing at the live re-check tool.
 - Whether `SessionGenerate.messages` are fresh objects per model call within
-  a turn. If not, the generate hook pushes duplicate nudges on every tool
-  round trip.
+  a turn. The context hook appends injections to the matched message's
+  content, which changes the text the binding check compares. With fresh
+  objects per call (what the tests assume), the prompt-time block re-fires
+  on every round of its own turn. With reused objects, round 1's
+  injections would change the matched message's text, so the binding check
+  would skip rounds 2 and on - within-turn replay would break after round
+  1 instead of duplicating.
+- Entries outliving their session: `pendingInjections` is keyed by session
+  id and never swept on session end. Bounded - a per-session set capped at
+  3 entries, and the map itself dies with the adapter activation - but a
+  session's entries do persist after the session is gone, pre-existing.
+- Cross-directory hook dispatch scope: the event pump filters events by
+  directory, but the session hooks (`prompt`, `context`, `compaction`)
+  have no such filter - whether a hook can fire for another directory's
+  session is unverified, pre-existing.
 - An npm-installed copy (not the dev checkout, which has devDependencies
   present) loading under v2 - the isolation rule's real-world proof.
 
-The app-exit gap (no server-side publish surface for `tui.command.execute`)
-is upstream:
-[anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984).
+The wrap-up exit closes the session's own tab over the session-tab rpc
+bridge - the tab-scoped close upstream
+[anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984)
+asks for. Known degrade: a TUI with no tab for the session (headless run,
+tabs off) never acts - the event is ephemeral, nobody is listening.
 Install opencode-v2 (brew formula `anomalyco/tap/opencode-v2`; conflicts
-with the v1 formula's binary name, so it cannot coexist) and re-run the QA
-live suite against it.
+with the v1 formula's binary name, so it cannot coexist) and re-run the
+QA live suite against it.
 
 ## User setup compatibility
 
@@ -112,15 +139,29 @@ key (`plugin` vs `plugins`) is auto-migrated by v2. The only user-owned file
 with a content change is the dev-session shim, and its new dual-shape content
 loads under both hosts.
 
+The session-tab feature adds a second user-owned artifact: the TUI-side
+plugin entry. A local FILE plugin shim carries a `server` entrypoint only
+(v2's `plugin/module.ts`), and the TUI's plugin discovery loads directories
+and symlinks, never plain files - so the dev-checkout install must be a
+DIRECTORY shim: `thatch/index.ts` (the dual-shape re-export, unchanged) plus
+`thatch/tui.ts` (re-exporting the TUI plugin). DELETE the old `thatch.ts`
+file in the same step - a file and a directory shim coexisting dies with
+`duplicate instance plugin ids: thatch` before any plugin code runs (the
+duplicate check is in activation, so nothing inside the plugin can
+self-heal it).
+
 ## Source files
 
 - `src/index.ts` -- dual entry, merged default export, lazy wrappers
 - `src/opencode/v1.ts` -- v1 hooks adapter
 - `src/opencode/v2.ts` -- v2 promise-context adapter + capability impl
+- `src/opencode/tui-plugin.ts` -- v2 TUI CLI plugin (the `./tui` entrypoint: consumes the session-tab rpc events, drives `ui.tabs`)
+- `src/session-tab-shared.ts` -- the cross-entry session-tab contract (rpc definition, prompt builder, validators)
 - `src/capabilities.ts` -- `HostCapabilities`, `capabilitiesFromClient`
 - `src/runtime.ts` -- the shared runtime (all behavioral logic)
 - `src/os-args.ts` -- pure argv helpers
 - `tests/opencode-v2.test.ts` -- v2 adapter contract tests (mocked context)
+- `tests/session-tab-shared.test.ts` -- session-tab validators, rpc definition shape, TUI guard logic
 - `tests/plugin.test.ts` -- v1 adapter contract tests (mocked client)
 
 ## Interactions with other features

package/docs/dev/features/prediction-engine.md

@@ -6,8 +6,9 @@ calls and updates it based on user feedback.
 
 ## What it does
 
-- Four tools: `prediction_query`, `prediction_update`, `prediction_list`,
-  `prediction_delete`. All defined in `src/tool-defs.ts`.
+- Tools: `prediction_query`, `prediction_update`, `prediction_list`,
+  `prediction_delete`, `prediction_mark_checked`. All defined in
+  `src/tool-defs.ts`.
 - Auto-fires at every user message: embeds the prompt, cosine-matches against
   matchers, injects scored predictions as a synthetic nudge part.
 - Bayesian confidence model — a graded score that is reinforced or weakened
@@ -101,6 +102,33 @@ Runs in a single DB transaction:
 Returns a status line with final confidence and confirm/disconfirm counts.
 Embeds both the matcher and prediction text.
 
+### Dedup pass (corpus-level consolidation)
+
+Write-time dedup (0.85, both stores) catches near-identical statements at
+creation. Wording-different duplicates — the same preference restated weeks
+later — land below that floor and accumulate. The dedup pass finds them:
+
+- `findPredictionDuplicates(store, threshold = 0.70)` in `src/prediction.ts`:
+  pairwise cosine over the store's predictions, skipping pairs already
+  adjudicated in `prediction_dedup_pairs`. The threshold is band placement:
+  [0.85, 1] is write-time territory, below 0.70 short-statement embeddings
+  are too noisy to call duplicates.
+- Pairs are keyed on the canonical SORTED id pair — (A,B) and (B,A) are one
+  row, the same contract as the memory side's `dedup_pairs`.
+- `prediction_mark_checked(id_a, id_b, status)` records the verdict:
+  `duplicate` (merged or treat as one) or `distinct` (both legitimate).
+  Distinct verdicts are the load-bearing case — a destroyed duplicate is
+  gone, but a judged-distinct pair re-surfaces every session start unless
+  recorded.
+- The hygiene report surfaces `N prediction duplicate pairs pending review`;
+  the agent merges (fold the loser's matchers with `prediction_update`, then
+  `prediction_delete` the loser) or judges distinct, and marks the pair
+  either way. Scans are per-store: cross-store writes are edge-linked at
+  write time instead of duplicated.
+- The co-fire refinement (behavioral evidence layered onto this method once
+  fire tracking exists) is designed in
+  [../../plans/prediction-consolidation.md](../../plans/prediction-consolidation.md).
+
 ### Auto-fire (opencode: `chat.message` hook)
 
 - Reuses the prompt embedding already computed for the recall nudge — no extra
@@ -113,6 +141,8 @@ Embeds both the matcher and prediction text.
   `[thatch] User decision model` header.
 - 0-evidence predictions use "you may prefer"; predictions with evidence use
   "you tend to".
+- The block ends with a snapshot footer (see the block example below): the
+  labels are a submission-time snapshot, not a live view.
 - Independent try/catch — a prediction failure does not block recall or
   behavior.
 - Toast: `[thatch] N predictions surfaced`.
@@ -131,11 +161,27 @@ Embeds both the matcher and prediction text.
 The auto-fire block looks like:
 
 ```text
-## User decision model
+[thatch] User decision model
 - [0.72 conf, 4 tests] When {matcher}: you tend to {prediction}
 - [0.61 conf, 2 tests] When {matcher2}: you may prefer {prediction2}
+Snapshot: these labels reflect the prediction store as of this message's
+submission. Predictions updated after submission (including during this
+turn) do not refresh it; re-check with thatch_prediction_query before
+relying on them.
 ```
 
+The footer's tool name follows the host: opencode sees
+`thatch_prediction_query`; MCP hosts (Claude Code, Cursor) see
+`mcp__thatch__prediction_query`. The renderer resolves the spelling
+through the caller's `ToolNamer`.
+
+The snapshot footer exists because the block is computed once when the
+message is submitted and stays attached to it for the whole turn (v1:
+synthetic part on the stored message; v2: `pendingInjections` re-injected
+into every outbound request of the turn). Predictions the conversation
+mutates mid-turn do not refresh the block; the footer tells the consumer
+the labels are a submission-time snapshot and points at the live tool.
+
 Prompt instructions: follow strong predictions silently, surface weak or
 competing predictions to the user, update the model when the user responds.
 
@@ -190,11 +236,11 @@ that user preferences are stable, not time-sensitive.
 
 | File | Role |
 |------|------|
-| `src/prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names |
+| `src/prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names, plus the corpus dedup pass (`findPredictionDuplicates`, pair verdicts) |
 | `src/scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence (shared base for prediction and behavior) |
 | `src/db.ts` | Prediction tables, `scorePredictionNudge` |
-| `src/tool-defs.ts` | Four prediction tools (`query`, `update`, `list`, `delete`) |
-| `src/prompts.ts` | `predictionNudge` formatting, verb selection |
+| `src/tool-defs.ts` | Five prediction tools (`query`, `update`, `list`, `delete`, `mark_checked`) |
+| `src/prompts.ts` | `predictionNudge` formatting, verb selection, dedup-merge guidance |
 | `src/sideband.ts` | `predictions` method for the MCP path |
 
 ## Database tables
@@ -241,8 +287,25 @@ prediction_provenance(
     created_at   TEXT,
     FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
 )
+
+prediction_dedup_pairs(
+    store      TEXT,
+    id_a       TEXT,
+    id_b       TEXT,
+    status     TEXT,
+    checked_at TEXT,
+    PRIMARY KEY (store, id_a, id_b)
+)
 ```
 
+Timestamp semantics: a matcher's `updated_at` is the last change to the
+matcher row OR its edge set — `createEdge` bumps it when a new edge lands,
+and deleting an item bumps the matchers whose edges cascade away. The
+matcher's own text may legitimately be older than its links (a corrected
+prediction re-links the existing matcher without touching its text).
+An item's `updated_at` is written at creation and then moved by the last
+confidence change.
+
 ## Key invariants
 
 1. **The firewall principle.** The model that uses predictions cannot grade
@@ -254,3 +317,5 @@ prediction_provenance(
    `chat.message` hook and MCP sideband) prevents scoring drift.
 5. **Matcher text is embedded raw.** No header prepend — unlike
    `memory_remember`, which prepends `# label\n\n` before embedding.
+6. **Adjudicated dedup pairs never re-surface.** Verdict rows are keyed on
+   the canonical sorted id pair; `findPredictionDuplicates` skips them.

package/docs/dev/features/qa-system.md

@@ -70,9 +70,11 @@ execution directly via bun assertions. These are fast and run in parallel.
 Spawn real opencode sessions. Test the full pipeline with a real model. These
 cost model tokens and have a 20-minute per-use-case timeout. Live use cases
 check for `opencode` on PATH at runtime: if it is present they run; if not,
-they skip with `[MANUAL]`. Three (UC-006, UC-010, UC-013) are
+they skip with `[MANUAL]`. Six (UC-006, UC-010, UC-013, UC-083, UC-084,
+and UC-085) are
 `manualOnly: true` for infrastructure reasons (Cursor hook lifecycle, nested
-opencode session timeout, compaction trigger). Run them locally with
+opencode session timeout, compaction trigger, sub-agent support, skill
+loading, and a PR with prior review comments). Run them locally with
 `mise run qa-live`.
 
 | UC | Name | What it tests |
@@ -86,6 +88,20 @@ opencode session timeout, compaction trigger). Run them locally with
 | UC-013 | compaction-context | compaction hook injects context |
 | UC-019 | archived-memory-lifecycle | archive -> search excludes -> unarchive -> search includes |
 | UC-020 | extraction-escalation | polite -> insistent -> ALL-CAPS over missed nudges |
+| UC-038 | no-save-run | an extraction child that finds nothing worth saving (no toast) |
+| UC-043 | compaction-suppression | extraction nudges suppressed while an extraction child runs |
+| UC-077 | child-session-drain | direct extraction: the child drains the parent's queue |
+| UC-078 | child-session-error | direct extraction: the child errors, held entries requeue |
+| UC-079 | child-session-deletion | direct extraction: the child is deleted, entries requeue |
+| UC-080 | parent-session-deletion | parent deleted mid-extraction, cleanup completes |
+| UC-083 | review-coordinator | the multi-agent review coordinator pipeline |
+| UC-084 | review-walkthrough | the change-walkthrough skill on a real diff |
+| UC-085 | review-followup | follow-up round verification against prior review comments |
+| UC-086 | review-response | author-side response to incoming review comments |
+| UC-087 | review-no-subagents | the solo review path on hosts without sub-agents |
+| UC-098 | chat-cross-session | two real opencode sessions exchange chat messages |
+| UC-119 | session-tab-spawn | the session_tab spawn flow end to end |
+| UC-122 | review-mode-commands | /thatch/self-review and /thatch/peer-review overlay efficacy (seeded fixture) |
 
 ### mise tasks
 
@@ -235,7 +251,7 @@ No separate QA docs directory exists. QA use cases live in `tests/qa/` as execut
 1. **Automatable use cases never spawn an LLM.** They test CLI, hooks, DB, and
    tool execution directly.
 2. **Live use cases spawn real opencode sessions and cost model tokens.** They
-   skip with `[MANUAL]` when `opencode` is not on PATH; three are
+   skip with `[MANUAL]` when `opencode` is not on PATH; six are
    `manualOnly: true` for infrastructure reasons.
 3. **`QA_DRY_RUN=1` lists use cases without executing.** Use this for CI and
    coverage review.

package/docs/dev/features/session-lifecycle.md

@@ -73,12 +73,12 @@ When a parent session (no parentID) goes idle:
 
 User-invoked slash commands, shipped as command markdown synced by the plugin (see `src/commands.ts`). The template instructs the model to flush pending fact extraction (`thatch_get_extraction_payload` + `thatch_extraction_done`), finish promised memory writes, and surface unaddressed todos -- then end its response with a greenlight token (`THATCH_COMPACT_READY` / `THATCH_EXIT_READY`) only when safe to proceed. Text typed after the command is forwarded into a labeled `# User Message` section ahead of the `# Pre-*-wrap-up` checklist section (opencode's `$ARGUMENTS` substitution): the headers give the user's words provenance, so they cannot be misread as part of the wrap-up instructions. opencode's substitution is purely mechanical with no default-value form (verified against v1.18.30), so the template cannot switch on emptiness; instead the section always carries a fallback line telling the model to treat an empty section as n/a (bare command, no user text).
 
-1. `command.execute.before` arms the session in `pendingWrapUp` when the command runs
-2. On the session's next idle, the plugin fetches the session's messages via the SDK client and checks the final assistant message's trailing text for the token (trimmed, exact match)
-3. Token present: trigger the TUI action and return early -- compaction is starting (the checklist drained the buffer) or the process is exiting
-   - compact: `client.tui.executeCommand({ body: { command: "session_compact" } })`. The execute-command route only accepts legacy alias names; `session_compact` maps to the TUI's `session.compact` action, the same thing the built-in `/compact` runs
-   - exit: unregister the session from the chat directory first (a greenlit exit's host is about to vanish; other sessions must stop addressing mail to it), then `client.tui.publish({ body: { type: "tui.command.execute", properties: { command: "app.exit" } } })`. No exit alias exists, so the TUI keymap command is published directly. The exit template's checklist also asks the model to call `thatch_chat_unregister` as its last persistence step; the plugin-side unregister is the deterministic backstop. Compaction deliberately does NOT unregister - the session continues
-4. Token absent: warning toast pointing at the blockers in the response, then fall through -- the model may have buffered tool interactions that still need extraction
+1. `command.execute.before` arms the session in `pendingWrapUp` when the command runs (on v2 the registered command's `execute` runs the same arming through `onCommandExecuteBefore`)
+2. On the session's next idle, the plugin fetches the session's messages (v1: SDK client; v2: `session.context`, mapped into the v1 shape) and checks the final assistant message's trailing text for the token (trimmed, exact match)
+3. Token present: trigger the host action and return early -- compaction is starting (the checklist drained the buffer) or the session is closing
+   - compact: v1 dispatches the TUI's `session_compact` command (`client.tui.executeCommand` -- the execute-command route only accepts legacy alias names; `session_compact` maps to the TUI's `session.compact` action, the same thing the built-in `/compact` runs). v2 calls `session.compact({sessionID})` on the promise domain directly (upstream #52385), runtime-guarded because the pinned dev types predate the surface -- an older host degrades to a logged no-op
+   - exit: record the session's watcher deaths first (`watchers.sessionDied` -- BEFORE the unregister below, because the death row is placed by the session's chat row and the unregister deletes it; the runtime also captures the project there, so the async death-notice delivery still places after the row is gone), unregister the session from the chat directory (a greenlit exit's host is about to vanish; other sessions must stop addressing mail to it), then close the session out on the host. v1 publishes the `app.exit` TUI keymap command directly (`client.tui.publish` -- no exit alias exists). v2 emits the session-tab bridge's `exit-tab-closed` event, a TUI-ONLY close of the session's OWN tab: the daemon hosts every tab, so `app.exit` would take down unrelated sessions, and the pump deliberately never translates this event (the deaths were already recorded; a second pass would erase the durable death row). The unregister is plugin-side only, after the death recording: the template deliberately does NOT ask the model to call `thatch_chat_unregister`, because a mid-turn unregister would delete the chat row before the death placement could use it. Compaction deliberately does NOT unregister - the session continues
+4. Token absent: warning toast pointing at the blockers in the response, then fall through -- the model may have buffered tool interactions that still need extraction (on v2 the toast rides the bridge's toast event; a TUI-less environment shows nothing - the blockers themselves are in the model's response)
 
 ### Command file install
 

package/docs/dev/features/session-tabs.md

@@ -0,0 +1,161 @@
+# Session tabs (coordinated subordinates)
+
+## What it does
+
+`thatch_session_tab` (opencode v2 only) lets a coordinating LLM spawn a
+detached subordinate LLM session in a new TUI tab. The subordinate is a full
+peer session: it runs its own agent loop across many turns, in a directory
+of the coordinator's choosing, while the coordinator keeps working. The user
+sees the subordinate's tab appear beside the coordinator's, unfocused.
+
+This is NOT the `task` tool: task subagents run inside the dispatcher's turn
+and return their result inline. A tab subordinate outlives the dispatching
+turn and is supervised over cross-session chat.
+
+## How it works
+
+```text
+coordinator session (LLM)
+  |  tool call: thatch_session_tab {prompt, title, worktree|directory}
+  v
+v2 adapter (src/opencode/v2.ts, buildSessionTabHost via CoreContext.sessionTabHost)
+  |  validate (tool-defs: title, exactly-one location arg, fs existence,
+  |            worktree same-main-checkout identity)
+  |  1. session.create({title, metadata: {thatch: {...}}, location})
+  |  2. worktree flow: session.move({directory: worktree})  (idle -> steer = immediate)
+  |  3. db.registerChatSession(subordinate)   (participant, never machinery-marked)
+  |  4. rpc emit rpc.thatch-tabs.tab-opened {sessionID, directory}
+  |  5. session.prompt({text: preamble + task})
+  v
+SSE event feed (isOpenCodeEvent passes rpc.*; fans out across all locations)
+  v
+TUI CLI plugin (src/opencode/tui-plugin.ts, loaded from package exports "./tui")
+  |  data.listen -> type filter -> directory guard (mirrors the built-in
+  |  tui.* handlers: the event routes by the coordinator instance's
+  |  directory) -> data.session.sync -> ui.tabs.open(sessionID)
+  v
+Tab strip: subordinate tab appears, unfocused
+```
+
+Key properties:
+
+- **v2-only by construction.** The ToolDef carries `v2Only: true`; the v1
+  adapter (`src/tools.ts`) and the MCP server (`src/mcp.ts`) filter it. The
+  system prompt lists the tool only when the runtime is built with
+  `v2Tools: true` - a prompt listing a nonexistent tool is the
+  first-call-mistake class.
+- **The event routes by the coordinator's location**, so the tab opens in
+  the coordinator's window under any `tabs.scope` - even when the session
+  lives in a worktree or temp dir. Tab ownership is by window, not by
+  session location.
+- **The move precedes the emit**: a failed move leaves no stranded open tab
+  (placement is identical either way because routing is by coordinator
+  location).
+- **No ack**: a headless run, a connecting TUI, or `tabs.mode: off` means
+  the event lands nowhere (harmlessly). The tool response says "tab
+  requested"; the session exists and is findable in the sessions list
+  regardless.
+- **The subordinate is a chat participant**, deliberately never marked
+  machinery: pre-registration (idempotent, like an explicit chat_register)
+  gives the coordinator its chat name in the tool response, and the
+  auto-register converges on the same name. Gated on the chat-enabled
+  config like every other registration path: with chat off the
+  subordinate still spawns, but no roster row is written and the tool
+  response reports no chat name. `validateTitle` rejects the
+  machinery title so `isMachinerySessionTitle` can never misfire. A
+  mid-flow failure (create, move, emit, prompt) throws with the created
+  session id and the completed steps in the message - v2 has no session
+  delete, so the stranded session can at least be named and reported.
+- **The worktree flow boots a second per-location thatch instance** (shared
+  db): the subordinate's pollers, nudges, extraction, wrap-up, and alerts
+  run in the worktree location's instance, and chat wake for the idle
+  subordinate depends on that instance being alive. The watcher poller
+  handoff is per location (`WatcherRegistry.#live` is keyed by directory):
+  the subordinate's instance booting never stops the coordinator's
+  poller - each location's instance polls only its own directory's
+  watchers. The pump caches the subordinate's location from the
+  tab-opened payload's directory field (its final, post-move directory),
+  never from the rpc envelope's location stamp (that is the publisher's
+  directory), so the subordinate's location-less execution events route
+  to the instance that owns it.
+
+## The cross-entry contract
+
+`src/session-tab-shared.ts` (SDK-free, per the isolation rule in
+`src/index.ts`) holds the rpc definition (`thatch-tabs`: `tab-opened`;
+`tab-closed` - emitted by the close tool (below) and translated by the v2
+pump into the runtime's confirmed-death path, which also records a
+`chat_tab_closed` marker the chat roster's open-tab reader uses to demote
+the row instantly ([cross-session-chat.md](cross-session-chat.md));
+`exit-tab-closed` - the
+wrap-up exit's TUI-only close, which the runtime records the exit's deaths
+itself before emitting, so the pump deliberately never translates that
+one; and `toast` - every runtime toast's TUI-only feedback channel), the
+subordinate prompt builder, and the validators. The TUI entrypoint may
+import only `@opencode/plugin/tui` and this module.
+
+## Interactions
+
+- **Chat**: the subordinate registers in its final directory's repo slug (a
+  worktree resolves to the main checkout's slug), so coordinator and
+  subordinate share a chat scope across the move.
+- **Extraction/wrap-up/alerts**: the subordinate is a normal session owned
+  by its location's instance; the coordinator observes it via chat, not the
+  event pump (its post-move events fail the pump's directory filter
+  deliberately - the `childSessions` forwarding set is for extraction
+  children, and adding moved sessions would double-process their events).
+- **Session metadata**: the created session carries
+  `metadata.thatch.{coordinatedBy, coordinatorSessionID, worktree?}`. The
+  host inherits parent metadata onto children - the subordinate's own
+  extraction children carry the marker too; treat inherited markers as
+  inherited, not first-party.
+
+## Closing a subordinate's tab
+
+`thatch_session_tab_close {session}` (the target: the subordinate's chat
+name or session id, resolved name-first through the chat roster) emits
+`rpc.thatch-tabs.tab-closed {sessionID, chatName?}` over the same rpc
+bridge. The TUI plugin consumes it symmetrically with open: the directory
+guard applies, and `ui.tabs.close(sessionID)` closes the tab in every
+window showing one (windows not showing it no-op). Close is TAB-LEVEL: the
+session survives, the strip's reopen stack can restore it, and chat history
+is untouched.
+
+Two consumers ride the event: the death-detection machinery
+(generalized-session-heartbeat) treats a tool-initiated close as a
+CONFIRMED close - the closed session's watchers cancel immediately instead
+of waiting on the 2h delivery-failure heuristic - and the coordinator's own
+workflow closes dispatched subordinates once their work is verified. The
+pump routes the close by the CLOSED session's own directory (resolved from
+the pump's session-location cache, or live through the session API), not
+by the event's location stamp: the stamp names the publishing coordinator
+instance, while the watchers and status bookkeeping live in the instance
+that owns the session - its post-move location.
+
+## Install requirement (the `./tui` entrypoint)
+
+A local FILE plugin shim gets a `server` entrypoint only
+(`packages/core/src/plugin/module.ts` at v2), and the TUI's plugin discovery
+loads directories and symlinks, never plain files. The dev-checkout install
+must therefore be a directory shim (`thatch/index.ts` + `thatch/tui.ts`),
+and the old file shim must be DELETED in the same step - coexisting shims
+die with `duplicate instance plugin ids: thatch` before any plugin code can
+run. npm installs need the `exports` map to include `.` (the bare-specifier
+path) alongside `./tui`, and `@opencode/plugin` is an optional peer
+dependency for the TUI entry's runtime resolution.
+
+## Testing
+
+- Unit: `tests/session-tab-shared.test.ts` (validators, definition shape,
+  guard logic), `tests/opencode-v2.test.ts` (the execute flows' ordering via
+  the `makeContext` double with `session.move` + the `rpc` domain).
+- QA: uc-059 (tool list + MCP leak check), uc-014/uc-060 (skill counts),
+  uc-119 (the live spawn flow through the docker sandbox).
+- Live smoke (recorded 2026-10-08, ALL SCENARIOS PASSED): headless legs -
+  directory variant, worktree variant (the move persisted in the session
+  row + metadata), headless no-tab; TUI-visual legs (a real container
+  attach) - the subordinate's tab appeared unfocused, the title rendered,
+  the subordinate responded, and the persisted strip state matched; kill +
+  re-attach restored both tabs (restart persistence). Sandbox note: mkdir
+  the /qa host dir BEFORE `docker run -v` - a missing host path is created
+  inside the Docker VM, invisible to the mac.

package/docs/dev/features/setup.md

@@ -115,6 +115,11 @@ Cursor takes priority because Cursor also sets `CLAUDE_PROJECT_DIR` as an
 alias. Without the priority check, Cursor sessions would be misidentified as
 Claude Code.
 
+Separately, the project directory for store/chat identity resolution
+follows `THATCH_PROJECT_DIR ?? CURSOR_PROJECT_DIR ?? CLAUDE_PROJECT_DIR
+?? cwd` in the MCP server; project-local setups pin `THATCH_PROJECT_DIR`
+into the written MCP config.
+
 `checkSetup` looks for start and end markers in the host's instructions file
 --- `CLAUDE.md` for Claude Code, `AGENTS.md` for Cursor. It checks local first,
 then global. Local takes priority.

package/docs/dev/features/watchers.md

@@ -88,9 +88,15 @@ A `setInterval` loop (unref'd - it never keeps the process alive)
 runs `poll()` every 60 seconds (configurable). Each cycle:
 fetch the current state, run `diffPrState()` against the watcher's
 last-seen state, filter events to the watched types, queue them, and
-attempt delivery. Poll errors are per-watcher; one bad PR never
-blocks the others. The diff is a pure function, so it is unit-tested
-without any network access.
+attempt delivery. When the fetched snapshot differs from the last-seen
+state, the cycle also rewrites the session's journal row: registry
+rebuilds (v2 reload rehydration, the watch tools' journal reconcile)
+hydrate the journaled state verbatim, so a journal that lags the
+poller would make the next diff re-fire already-delivered events -
+observed live in October 2026 as a watch re-delivering the same CI
+completion on every reload. Poll errors are per-watcher; one bad PR
+never blocks the others. The diff is a pure function, so it is
+unit-tested without any network access.
 
 The interval is surfaced to the model through the registry's
 `pollSeconds` getter: watch-creation output states when the first
@@ -126,6 +132,41 @@ when this run finishes" request from leaving a standing watch polling
 a target nobody is waiting on. `watch_list` marks one-shot watchers
 with a `[once]` tag, and the registration output states the mode.
 
+### Expiry
+
+A watch whose TTL passes is dropped at the next poll cycle, and the
+owning session is told: a `watch_expired` event queues through the
+normal pending path, naming the target and the watch's lifetime in
+minutes. The nudge framing for an all-expiry delivery states that the
+watched condition never occurred - deliberately without the
+greenlit-gating carve-out, because "the watch ran out of clock" must
+never read as "the wait is over". Watches that expire while a session
+is away are a separate path: they are not re-armed, and the re-arm
+notice reports the expired count.
+
+### Death detection (closed v2 tabs)
+
+A closed opencode v2 tab fires no `session.deleted`, so its watchers
+would poll until the TTL with deliveries queued forever. The registry
+declares death when ALL of: the session's pending queue has been
+non-empty longer than the threshold (`THATCH_WATCH_DEATH_MINUTES`,
+default 120), its delivery attempts have THROWN consecutively (a skip -
+busy or compacting - resets the chain; skips are never death evidence),
+the throw is 404-class (verified live 2026-10-07: prompt_async to a
+closed v2 tab returns 404 while the session row persists; a 5xx loop is
+a wedged server, never death), and the session is hosted by this
+process (sibling v1 processes and MCP sessions are never touched).
+MCP-owner watches keep TTL-only death: their turn-driven heartbeat
+cannot distinguish a closed Cursor tab from a parked one. On death:
+watchers and pending drop, and live same-project sessions get a
+`watcherDeathNotice` carrying the dead session's chat name and session
+id (the thatch-coordination loop's respawn key); a durable
+`watcher_death` runtime_state row covers sessions that were busy at
+death time, surfaced and cleared at other sessions' next prompt. The
+notice says the watches were CANCELLED and points at `watch_create` -
+the re-arm-on-resume promise belongs only to the restart-dormant path,
+where the definitions survive and resuming the session re-arms them.
+
 ### Command watches
 
 The command source stretches the fetch/diff recipe in two ways:
@@ -180,6 +221,11 @@ Events queue in an in-memory pending map keyed by session. Delivery
 is gated by a `canDeliver` predicate the plugin supplies: the session
 must be idle (tracked from `session.status` events) and not
 compacting. Proactive prompts are never injected into a running turn.
+The queue is visible to the session itself: `watch_list` appends an
+"N events detected, waiting for idle to deliver" line with a
+per-target breakdown while events sit undelivered, so a busy session
+with queued events is distinguishable from a watcher that fired
+nothing.
 
 When the gate is open, the plugin calls `client.session.promptAsync`
 on the session with a synthetic text part built by
@@ -206,9 +252,11 @@ cycle or when the session next goes idle (the event hook calls
 `pr_review_resolved`, `pr_commit`, `pr_status`, `pr_description`,
 `pr_ci`. The tool's `events` argument selects a subset; the default is
 all eight. Branch watchers add `branch_commit`, `branch_ci`, and
-`branch_workflow` (the full vocabulary is `WATCHER_EVENT_TYPES` in
-src/watchers.ts, test-enforced); command watchers register the single
-`command_success` type.
+`branch_workflow`; command watchers register the single
+`command_success` type. The registry itself emits one lifecycle type
+across all sources, `watch_expired`, which is not selectable via the
+`events` argument (the full vocabulary is `WATCHER_EVENT_TYPES` in
+src/watchers.ts, test-enforced).
 
 ## Interactions with other features
 
@@ -229,6 +277,8 @@ src/watchers.ts, test-enforced); command watchers register the single
 - `THATCH_WATCH_TTL_MINUTES` - watcher time-to-live (default 480)
 - `THATCH_WATCH_MAX_PER_SESSION` - active watchers per session
   (default 5; all sources share the budget)
+- `THATCH_WATCH_DEATH_MINUTES` - pending-age threshold before a dead
+  session's watchers are cancelled and announced (default 120)
 - `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` - per-run kill timeout for
   watched commands (default 30)
 
@@ -248,6 +298,12 @@ src/watchers.ts, test-enforced); command watchers register the single
   mocked gh runner
 - `tests/qa/auto/uc-101-command-watchers.ts` - command-watch lifecycle
   against a mocked command runner
+- `tests/qa/auto/uc-114-watcher-expiry-replay.ts` - expiry notification
+  and the no-replay guarantee across journal rehydration
+- `tests/qa/auto/uc-118-watcher-death-detection.ts` - closed-tab death
+  detection (404-class delivery persistence) and the once-only notice
+- `tests/qa/auto/uc-115-watch-list-pending-events.ts` - pending-event
+  visibility in watch_list while the session is busy
 
 ## Adding a new source type