@jeffober/thatch 0.2.5 → 0.2.7

package/docs/dev/features/commands.md

@@ -2,8 +2,11 @@
 
 Thatch's `/thatch/*` commands come in two families:
 
-- **Actions** (`defrag`, `extract`, `hygiene`, `reflect`) — user-invoked
-  wrappers around behaviors the nudges otherwise run on their own schedule.
+- **Actions** (`defrag`, `extract`, `hygiene`, `peer-review`, `refine`,
+  `reflect`, `self-review`, `whois`) — user-invoked commands. The
+  nudge-backed ones (`defrag`, `extract`, `hygiene`, `reflect`) wrap
+  behaviors the nudges otherwise run on their own schedule; the rest
+  are self-contained, with no nudge counterpart.
 - **Wrap-ups** (`compact`, `exit`) — greenlight-gated pre-compaction and
   pre-exit checklists. opencode only: the greenlight check needs the
   plugin's `command.execute.before` arming and TUI control routes.
@@ -12,11 +15,12 @@ User-facing guide: [../../user/commands.md](../../user/commands.md).
 
 ## Prompt cores
 
-Action bodies are **prompt cores**: constants in `src/prompts.ts`
-(`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) that hold the
-host-agnostic instruction text for one behavior. The nudge envelopes wrap
-the same cores with escalation tiers and the stop-and-wait ending; command
-and prompt renderers wrap them with frontmatter and a user-message section.
+The nudge-backed action bodies are **prompt cores**: constants in
+`src/prompts.ts` (`defragCore`, `hygieneCore`, `reflectCore`,
+`extractionCore`) that hold the host-agnostic instruction text for one
+behavior. The nudge envelopes wrap the same cores with escalation tiers
+and the stop-and-wait ending; command and prompt renderers wrap them with
+frontmatter and a user-message section.
 The point is drift-proofing: a wording change lands in the nudge and the
 command at once, and a test asserts each rendered file contains its core
 verbatim.
@@ -30,13 +34,40 @@ per host: `thatch_find_duplicates` on opencode, `mcp__thatch__find_duplicates`
 on MCP hosts. Each host's renderer passes its own namer
 (`opencodeToolName` / `mcpToolName`).
 
+## Skill-couching actions
+
+A command body can **couch** a skill: wrap the skill's procedure with the
+additional instructions the command needs. `refine`, `peer-review`,
+`self-review`, and `whois` are not prompt cores: they have no nudge
+counterpart to stay in sync with, so their bodies live directly in
+`actionDefs` (src/commands.ts). `refine` triggers the `thatch-refine`
+router skill and `whois` prints the chat identity; neither applies an
+overlay.
+
+`peer-review` and `self-review` share one pipeline couching
+(`reviewPipelineCouching` in src/commands.ts): run the code review
+machinery — the `thatch-code-review` coordinator where that skill is
+installed (opencode), the inline specialist sequence where it is not
+(Claude Code, Cursor) — and apply a mode overlay that reweights the
+findings for whose work is under review. The roster and count for the
+inline sequence come from `REVIEW_SPECIALISTS` in src/prompts.ts, the
+same source as the install list in src/skills.ts and both host
+instruction skill lists. `peer-review` weights org
+velocity and walks the project's persistent memory (the one tool it
+names, spelled through the `ToolNamer` so MCP renderings stay correct);
+`self-review` weights the reputation lenses (no-slop, clarity,
+technique, breadcrumbs) and iterates rounds until a round produces no meaningful
+findings. The couching also names the MCP `Focus:` line as a target
+source, because MCP prompts replace the file commands' `$ARGUMENTS`
+section with a `Focus:` line.
+
 ## Rendering and sync
 
 `src/commands.ts` is the single registry:
 
 - `actionDefs(tool)` returns the action set with bodies rendered for one
   host. Actions needing plugin-only capabilities are marked `opencodeOnly`
-  (`extract`: needs session identity via `get_session_info`).
+  (`extract` and `whois`: they need the invoking session's identity).
 - `opencodeCommandDefs()` = wrap-up templates + all actions. Synced by the
   plugin at init into `$XDG_CONFIG_HOME/opencode/command/thatch/`
   (`installOpencodeCommands`), content-compare, self-healing.
@@ -52,7 +83,7 @@ on MCP hosts. Each host's renderer passes its own namer
 
 A parity-guard test asserts the three sets are the same actions minus the
 documented exclusions: opencode = Claude Code set + `compact`, `exit`,
-`extract`; MCP prompts = Claude Code's set.
+`extract`, `whois`; MCP prompts = Claude Code's set.
 
 ## The extract action and session IDs
 

package/docs/dev/features/cross-session-chat.md

@@ -146,10 +146,10 @@ mechanical barrier, a documented trust posture.
 ### Leave tombstones
 
 Every exit path - `chat_unregister`, `session.deleted`, and a greenlit
-`/thatch/exit` (the plugin unregisters the exiting session before
-publishing `app.exit`, so the roster stops advertising a host that is
-about to vanish; the exit template's checklist step asks the model to do
-the same earlier) - writes a
+`/thatch/exit` (the plugin unregisters the exiting session before the
+host close-out - v1 publishes `app.exit`, v2 closes the session's own
+tab - so the roster stops advertising a host that is about to vanish)
+- writes a
 `chat_leave_tombstones` row in the same transaction that deletes the
 directory row. The tombstone is what makes a leave stick: all
 registration paths consult it (the plugin's idle and prompt auto-registerers are
@@ -235,12 +235,17 @@ the top of the result teaches the paging call, and ids make it exact.
 
 `chat_broadcast` posts one message to every other registered session at
 once, one inbox row per recipient per part - the existing wake machinery
-(grouping, gating, rate cap) treats each as ordinary mail. Stale sessions
-are skipped and reported rather than messaged: a host that has stopped
-heartbeat-ing will never read the mail, and dead mail to a dead process is
-just clutter. The sender is excluded. It is a separate tool rather than a
+(grouping, gating, rate cap) treats each as ordinary mail. Opencode rows
+are skipped and reported unless they are OPEN (fresh heartbeat AND a tab
+open now, per the open-tab reader below): a host that has stopped
+heartbeat-ing will never read the mail, and a fresh-but-tab-less session's
+wake can be swallowed without running a turn, so messaging it would spend
+a model turn on a delivery that likely never fires. MCP sessions always
+receive (they read mail at their next prompt). Every skip is listed by
+name in the result's `skipped` field. The sender is excluded. It is a
+separate tool rather than a
 magic `chat_send` recipient because "send to all" changes the behavior
-(fan-out, stale skipping, no address resolution), and a function that
+(fan-out, skip classes, no address resolution), and a function that
 changes behavior drastically on a parameter value is two functions.
 
 Retries are idempotent by READ STATE within a short window: a send (or
@@ -269,7 +274,8 @@ fires no `session.deleted`, so its rows would linger - staleness catches
 them: a row that has missed two consecutive beats (`CHAT_STALE_MS`, 60s
 at the default interval) is stale, meaning its harness stopped. Two beats
 rather than one so a single late poll cycle does not flap the roster.
-Heartbeat age is the ONLY liveness signal, by design. A host process id
+Heartbeat age is the only WRITTEN liveness signal, by design (the tab
+reader below is read-only). A host process id
 cannot serve: the same session is re-hosted by a new process on every
 `-s` resume, so a pid stamped on the row lies as soon as a different
 harness beats it (it says dead while the heartbeat proves alive). RESTART
@@ -280,18 +286,57 @@ into, so without the grace they would read stale while alive-idle and
 mail to them would not wake the tab. Sessions that emit activity
 graduate to permanent hosting; still-silent ones (closed tabs) age out
 at the grace and go stale. `isStale`
-(src/chat.ts) is the single rule; `chatLiveness`, the `chat_send` note,
-and the broadcast skip all call it, so they cannot disagree. `chat_list`
-groups the result into Active and Stale sections - the stale section's
-explainer says what stale means - and `chat_send` states the recipient's
+(src/chat.ts) is the single staleness rule; `chatLiveness`, the `chat_send`
+note, and the broadcast skip all call it, so they cannot disagree.
+
+### The open-tab reader: OPEN vs RECENT
+
+Heartbeat age alone conflates presence with recency: a finished
+conversation stays fresh until its directory's instance stops beating it
+(days), and a closed tab leaves a fresh row. The refinement is a READ-ONLY
+second signal, `src/tab-state.ts`: at roster render and broadcast time,
+glob `<XDG_STATE_HOME>/opencode/*/tui/tabs.json` (one file per release
+channel - "latest" today, hence the glob), parse BOTH scope modes
+(`global.tabs` and per-path `cwd.*.tabs`; the scope depends on opencode's
+`tabs.scope` config), and build the set of sessionIDs carrying a tab.
+Missing files, bad JSON, and absent state trees degrade to an empty set -
+an unknown tab state never reads as OPEN. `chatLiveness` takes the set and
+returns `open` (fresh + tab), `recent` (fresh + no tab), `stale`;
+MCP rows keep `active`/`idle`. Callers compose the raw set with confirmed
+tab closes via `effectiveOpenTabs` (`chatOpenTabs` is the wired provider):
+the `session.tab_closed` bridge event (the session_tab tool's confirmed
+close) writes a `chat_tab_closed` runtime_state marker, and a FRESH marker
+(inside `CHAT_TAB_CLOSED_OVERRIDE_MS`, 2 staleness windows) subtracts the
+session from the set - so a residue tabs.json row cannot read OPEN right
+after a confirmed close. The marker self-expires (the death path stops the
+heartbeat, so the row goes stale on heartbeat age regardless) and is
+superseded by any later beat.
+
+Known limits, accepted: a killed window leaves tab rows behind (the file
+is restart persistence by design), so dead-window residue reads OPEN until
+its heartbeat ages out; tabs disabled degrades everything to RECENT.
+
+`chat_list`
+groups the result into Active, Recent, and Stale sections - the Recent
+and Stale sections' explainers say what those states mean, and each row
+renders its verdict -
+and `chat_send` states the recipient's
 liveness at send time, so a sender mailing a ghost learns it immediately
-instead of waiting on a wake that will never fire. Both roster surfaces
-order rows with `sortChatRoster` (also src/chat.ts): project first,
+instead of waiting on a wake that will never fire, and a sender mailing a
+tab-less session is told the wake is not guaranteed. Both roster surfaces
+order rows with `sortChatRoster` (also src/chat.ts) and split fresh
+opencode rows along the same open/recent boundary (`splitChatRoster`
+takes the open-tab set): project first,
 alphabetical, with no-project rows last; most recently seen first within
-a project. The CLI roster bounds
-the stale display to one day by default (`--stale N` in days, `--stale all`
-unbounded), collapsing older rows into a hidden-count note; the tool
-surface stays unbounded so an agent always sees the full directory.
+a project. The CLI roster guards the Recent and Stale sections behind
+flags, and the two guards hide differently: without `--recent` the
+tab-less rows collapse into a muted hidden-count note (revealed by the
+flag), while without `--stale` stale rows are dropped entirely; with
+`--stale [N|all]` they show under a one-day display cap that collapses
+older rows into a
+hidden-count note. The tool
+surface shows all three sections unbounded so an agent always sees the
+full directory.
 `session.deleted` is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap
@@ -312,6 +357,22 @@ and a count, pointer-only like watcher notifications, with the model calling
 `chat_read` for content. On success the poller stamps `delivered_at`
 (re-stamping on re-nudges resets the re-nudge timer).
 
+Before any wake attempt runs, the delivery guard (`guardDelivery` in
+`src/runtime.ts`) checks that the runtime instance's own directory - the
+bound directory of every session it hosts - still exists. A deleted
+worktree (merged branch) would otherwise error every attempt, and opencode
+surfaces that error to the user as a toast. The guard skips the attempt
+with a `runtime:delivery` debug line instead, leaving the mail queued; the
+check is per attempt, so a worktree recreated at the same path resumes
+delivery. The existence check cannot say why a path is absent (deleted
+tree, broken symlink, parent permission), so any miss classifies as gone -
+deliberate, because surfacing non-ENOENT errors through the attempt would
+buy the toast back for no recovery the pending-and-retry cycle does not
+already provide. The guard wraps `promptSession` in
+`createRuntime`, which covers chat nudges, watcher notifications and death
+notices, rehydrate pings, chat echoes, and extraction dispatch at once;
+MCP hosts never build a runtime, so they are unaffected.
+
 The hard brake: at most a fixed number of wake prompts per recipient per
 hour (default 6, in-memory on purpose - it is a loop guard, not accounting).
 Without it, two agents politely acknowledging each other would ping-pong
@@ -475,7 +536,9 @@ caller's identity and mailbox, and is absent entirely when chat is
 disabled - absence is silent by construction.
 Staleness semantics differ by kind: an opencode row's stale age means its
 harness stopped beating (broadcast skips it), while an mcp row's age only means
-"between turns" (broadcast always delivers).
+"between turns" (broadcast always delivers). Broadcast also skips fresh
+opencode rows with no open tab (see the open-tab reader) - the skip
+classes are reported by name either way.
 
 The `/thatch/whois` command (opencode-only action, src/commands.ts) is the
 user-facing identity report: it relays `chat_status` for the invoking
@@ -489,18 +552,27 @@ mutates anything.
 
 Timing constants live in `src/chat.ts`: poll interval 30s, staleness
 threshold two missed beats (60s), re-nudge window 15 minutes, nudge cap 6 per recipient
-per hour, auto-row TTL 7 days. Environment overrides: `THATCH_CHAT_SPLIT_PART_LEN`
-(auto-split part budget, default 2000, clamped 500..9000) and
-`THATCH_CHAT_MAX_BODY_CHARS` (whole-body acceptance ceiling, default 20000);
-both are resolved once at module load and sanitized to positive integers
+per hour, auto-row TTL 7 days, confirmed-close override window two
+staleness windows (`CHAT_TAB_CLOSED_OVERRIDE_MS` in `src/tab-state.ts`).
+Environment overrides: `THATCH_CHAT_SPLIT_PART_LEN`
+(auto-split part budget, default 2000, clamped 500..9000),
+`THATCH_CHAT_MAX_BODY_CHARS` (whole-body acceptance ceiling, default 20000), and
+`THATCH_OPENCODE_STATE_ROOT` (the open-tab reader's state root, tests and
+QA sandboxes only);
+the split constants are resolved once at module load and sanitized to positive integers
 within their clamps - invalid values silently fall back to the default.
 
 ## Source files
 
 - `src/chat.ts` - ChatStore (directory + inbox SQL, assigned-name draw:
-  pool pick, slugify, counter bump, insert, prune, topic refresh), ChatPoller
+  pool pick, slugify, counter bump, insert, prune, topic refresh, broadcast
+  targeting), ChatPoller
   (heartbeat, gated delivery, re-nudge, rate cap, hourly prune sweep),
-  staleness helper
+  staleness helper, chatLiveness (the open/recent/active/idle/stale
+  verdicts)
+- `src/tab-state.ts` - the read-only open-tab reader: per-channel
+  tabs.json glob (global + cwd scopes), confirmed-close override window,
+  the composed open-tabs provider
 - `src/chat-names.ts` - the static display-name pool (nomenclater style),
   the base for every assigned name
 - `src/db.ts` - the chat tables in schema init (including

package/docs/dev/features/database.md

@@ -96,7 +96,7 @@ prediction_matchers(
   embedding BLOB,
   model TEXT,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- last change to the matcher row or its edge set
 )
 ```
 
@@ -116,7 +116,7 @@ predictions(
   confirm_count REAL NOT NULL DEFAULT 0,
   disconfirm_count REAL NOT NULL DEFAULT 0,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- written at creation, then last confidence change
 )
 ```
 
@@ -167,7 +167,7 @@ behavior_matchers(
   embedding BLOB,
   model TEXT,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- last change to the matcher row or its edge set
 )
 ```
 
@@ -185,7 +185,7 @@ behaviors(
   confirm_count REAL NOT NULL DEFAULT 0,
   disconfirm_count REAL NOT NULL DEFAULT 0,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- written at creation, then last confidence change
 )
 ```
 

package/docs/dev/features/nudge-pipeline.md

@@ -131,6 +131,20 @@ Tiers 2, 3, and 4 all fire independently. Any subset may inject. All share
 one embedding computation, reused across three cosine scans against
 different tables.
 
+#### Snapshot semantics
+
+A nudge block is computed once, when the message is submitted, and stays
+attached to that message for the whole turn - including every model round
+trip after mid-turn tool calls. Predictions, behaviors, or memories the
+conversation mutates mid-turn do NOT refresh an already-injected block
+(v1: the synthetic part lives on the stored message; v2:
+`pendingInjections` re-injects the prompt-time text into every outbound
+request of the turn, bound to the message it was computed for - see
+[opencode-plugin.md](opencode-plugin.md)). The prediction and behavior
+blocks therefore end with a snapshot footer naming the store state they
+reflect and the live tool to re-check. The recall nudge carries no footer:
+it lists memory labels without confidence claims.
+
 ### MCP path (`bin/thatch`, `flush-tools` subcommand)
 
 The `flush-tools` subcommand fires on `UserPromptSubmit` (Claude Code) or

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,14 @@ 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; the `./tui` companion entrypoint now EXISTS for the session-tab feature - extending it to publish toasts is the remaining lift) |
-| 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` entrypoint's `ui.tabs.close` is the known lift candidate and the session-tab rpc bridge is the transport) |
-| session tabs | n/a | rpc event bridge | NEW: `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). The deferred `thatch_session_tab_close` will emit `rpc.thatch-tabs.tab-closed {sessionID, chatName?}` - the shape is reserved and consumed by the generalized-session-heartbeat plan |
+| 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 |
@@ -90,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
 

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

@@ -141,6 +141,8 @@ later — land below that floor and accumulate. The dedup pass finds them:
   `[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`.
@@ -159,11 +161,27 @@ later — land below that floor and accumulate. The dedup pass finds them:
 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.
 
@@ -280,6 +298,14 @@ prediction_dedup_pairs(
 )
 ```
 
+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

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

@@ -82,11 +82,17 @@ Key properties:
 ## 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` - the latter emitted by the close tool (below) and consumed
-by the generalized-session-heartbeat plan), the subordinate prompt builder,
-and the validators. The TUI entrypoint may import only
-`@opencode/plugin/tui` and this module.
+`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
 

package/docs/dev/gotchas.md

@@ -160,6 +160,12 @@ here first. These are the things that have already cost time.
 - **`bun test` does not typecheck**, and `tsconfig.json` excludes `tests`. Test
   type errors are editor-only noise unless you run `tsc` on the test files
   directly. Keep test files type-clean anyway so the editor stays quiet.
+- **`mise run test` (bare `bun test`) also executes the QA barrels**
+  (`tests/qa/*/index.test.ts`), which spawn REAL opencode sessions and spend
+  model tokens, one use case at a time - a full run can hang for many minutes.
+  The unit gate is `mise run check` (`bun test tests/*.test.ts`); QA runs
+  belong to the `mise run qa-auto` / `qa-live` tasks, which select a UC
+  subset by name.
 
 ## Config and notifications
 
@@ -361,3 +367,18 @@ instead of throwing "Cannot use a closed database". Two rules keep this intact:
   chat canary). Local plugin specs handed to a loader explicitly
   (`"plugin": ["./path"]`) can point at a directory on v1 - it is only the
   AUTO-discovery scan that is files-only.
+
+## A promptSession wrapper must stay synchronous or fire-and-forget delivery assertions misfire
+
+- **Symptom**: tests that assert on wake delivery immediately after a hook
+  invocation see zero calls; deliveries land one microtask late.
+- **Cause**: the delivery guard (`guardDelivery`, src/runtime.ts) sits on
+  every wake path, and its directory-existence check was first written as
+  `await stat(...)`. Fire-and-forget callers (`void caps.promptSession(...)`)
+  and the repo's mock contract (calls recorded "synchronously inside the
+  mock", asserted with no intervening await) observe the wrapped call
+  before an extra microtask resolves.
+- **Fix**: the existence check is synchronous (`existsSync`), so the guard
+  adds no microtask between the gate and the wrapped call. If you ever
+  replace it with an async check, the callers' fire-and-forget timing -
+  and the tests that pin it - break again. (2026-10-12, wake-delivery-guard)