@jeffober/thatch 0.2.5 → 0.2.6

package/bin/thatch

@@ -13,11 +13,12 @@ import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscript
 import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, sortChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
 import { chatEnabled, loadConfig } from "../src/config";
 import { chatNotificationNudge } from "../src/prompts";
+import { chatOpenTabs as chatOpenTabsProvider } from "../src/tab-state";
 import { createDebugLog } from "../src/debug";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
-const db = new ThatchDB(dbPath);
+const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
 
 const [command, ...args] = process.argv.slice(2);
 
@@ -427,7 +428,9 @@ const CHAT_ROSTER_HEADER = ["NAME", "SESSION ID", "AGE", "STATUS", "PROJECT", "T
  * Renders the `chat list` roster as two sections - Active and Stale - each
  * an aligned-column table under a header row. Section headers are bold,
  * the stale explainer is muted italic; rows use green names, dim age,
- * green/red status, and a muted italic topic.
+ * green/red status, and a muted italic topic. The STATUS column carries
+ * the liveness verdict: open (tab open now), recent (host alive, no open
+ * tab), active/idle (MCP rows), stale (host presumed gone).
  * staleCapMs bounds how old a stale row is displayed (null = no bound);
  * rows past the cap collapse into a muted hidden-count note so the reader
  * knows rows exist that the window left out.
@@ -435,7 +438,7 @@ const CHAT_ROSTER_HEADER = ["NAME", "SESSION ID", "AGE", "STATUS", "PROJECT", "T
  * NO_COLOR is unset), so piped output - grep, redirect, QA runners - stays
  * clean plain text.
  */
-function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null): string {
+function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null, openTabs?: ReadonlySet<string>): string {
   const colored = process.stdout.isTTY === true && !process.env.NO_COLOR;
   const paint = (code: string, s: string) => (colored ? `\x1b[${code}m${s}\x1b[0m` : s);
   const { active, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), Date.now(), staleCapMs);
@@ -444,7 +447,7 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
       r.name,
       r.session_id,
       humanAge(r.last_seen),
-      chatLiveness(r),
+      chatLiveness(r, Date.now(), openTabs),
       r.project ?? "unknown",
       r.topic ?? "",
     ];
@@ -455,11 +458,14 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
     const header = align(CHAT_ROSTER_HEADER).map((h) => paint("1", h)).join("  ");
     const body = rows.map((r) => {
       const [name, sessionID, age, status, project, topic] = align(cells(r));
+      // Green = present or reachable (open/active), yellow = alive host
+      // without a tab (recent, wake not guaranteed), red = stale.
+      const statusColor = status === "stale" ? "31" : status === "recent" ? "33" : "32";
       return [
         paint("32", name),
         paint("2", sessionID),
         paint("2", age),
-        paint(status === "stale" ? "31" : "32", status),
+        paint(statusColor, status),
         project,
         topic ? paint("3;90", topic) : "",
       ].join("  ").trimEnd();
@@ -514,8 +520,11 @@ async function chatCommand(rest: string[]): Promise<void> {
           process.exit(1);
         } else staleCapMs = Number(staleNext) * 24 * 60 * 60 * 1000;
       }
+      // The open-tab set is read once per invocation at render time: rows
+      // with a tab render "open", fresh rows without one "recent".
+      const openTabs = chatOpenTabsProvider(() => db.chatTabClosures())();
       let sessions = db.listChatSessions();
-      if (!showStale) sessions = sessions.filter((r) => chatLiveness(r) === "fresh");
+      if (!showStale) sessions = sessions.filter((r) => chatLiveness(r, Date.now(), openTabs) !== "stale");
       if (sessions.length === 0) {
         console.log(
           showStale
@@ -524,7 +533,7 @@ async function chatCommand(rest: string[]): Promise<void> {
         );
         break;
       }
-      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null));
+      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null, openTabs));
       break;
     }
 
@@ -1050,7 +1059,7 @@ switch (command) {
       const sessionID = data.session_id ?? data.conversation_id;
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
-      const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge, behaviorNudge } = await import("../src/prompts");
+      const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge, behaviorNudge, mcpToolName } = await import("../src/prompts");
       const { detectSkew, readNpmCacheForUpdate } = await import("../src/version-check");
 
       let repo = "unknown";
@@ -1144,10 +1153,10 @@ switch (command) {
           parts.push(claudeRecallNudge(matches));
         }
         if (predictions && predictions.length > 0) {
-          parts.push(predictionNudge(predictions));
+          parts.push(predictionNudge(predictions, mcpToolName));
         }
         if (behaviors && behaviors.length > 0) {
-          parts.push(behaviorNudge(behaviors));
+          parts.push(behaviorNudge(behaviors, mcpToolName));
         }
 
         if (parts.length > 0) {
@@ -1296,13 +1305,13 @@ switch (command) {
       if (repo === "unknown") repo = "global";
 
       const { sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
-      const { predictionNudge } = await import("../src/prompts");
+      const { predictionNudge, mcpToolName } = await import("../src/prompts");
       const sockPath = sidebandSocketPath(dbPath);
       const threshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.60");
       const predictions = await sidebandPredictions(sockPath, promptText, [repo, "global"], threshold, 5);
 
       if (predictions && predictions.length > 0) {
-        const output = predictionNudge(predictions);
+        const output = predictionNudge(predictions, mcpToolName);
         if (isJson) console.log(JSON.stringify({ additional_context: output }));
         else console.log(output);
       } else {

package/docs/dev/README.md

@@ -27,7 +27,7 @@ Shared core
   ├── git.ts          → detect repo identity (store name) + worktree-deletion recovery (repo_paths cache)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
   ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
-  ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
+  ├── commands.ts     → /thatch slash-command registry: actions (prompt cores + self-contained skill couchings) + wrap-ups, per-host sync
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
   ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
@@ -91,7 +91,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `index.ts` | Dual-shape OpenCode plugin entry: the merged default export (`{ id, setup, server }`) loads on opencode v1 (reads `default.server`) and v2 (reads `default.setup`, strips excess keys). Lazy-imports the host adapter so each host's SDK resolves only under its own runtime. |
 | `opencode/v1.ts` + `opencode/v2.ts` | Host adapters. v1 builds HostCapabilities from the PluginInput client and returns the hooks object; v2 registers through the promise-context domains (ToolEditor, session.hook, event.subscribe) and degrades the surfaces v2 lacks. v2 also wires the session-tab host flow (create -> move -> chat-register -> rpc emit -> prompt) through the `CoreContext.sessionTabHost` seam. |
 | `opencode/tui-plugin.ts` | The v2 TUI CLI plugin (the package's `./tui` entrypoint): listens for `rpc.thatch-tabs.tab-opened` and `rpc.thatch-tabs.tab-closed` events and opens/closes the subordinate session's tab via `ui.tabs.open`/`ui.tabs.close`. See [features/session-tabs.md](features/session-tabs.md). |
-| `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, compaction trigger, app exit). `capabilitiesFromClient` bridges the v1 SDK client. |
+| `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, compaction trigger, session close-out - app exit on v1, the session's own tab on v2). `capabilitiesFromClient` bridges the v1 SDK client. |
 | `runtime.ts` | Shared plugin runtime: wires DB, model, extraction; the nudge tiers, system prompt injection, session event handling, child-session bookkeeping, wrap-up resolution. Host-agnostic: consumed by both adapters. |
 | `os-args.ts` | Pure argv / OS-command-line helpers for startup session resolution (`-s`/`-c`). SDK-free. |
 | `setup.ts` | `thatch setup --claude` / `--cursor` installer. Writes MCP config (`.mcp.json` / `.cursor/mcp.json`), appends to CLAUDE.md / AGENTS.md (idempotent), installs hooks in settings.json / hooks.json, installs skills. |
@@ -108,10 +108,11 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Three sources: GitHub PRs and branches via `gh api` (injected `GhRunner`), and local shell commands via `bash -c` (injected `CommandRunner`) run as condition variables - only the exit code is read, never the command's output. Diffs against last-seen state, queues events (pointer data plus machine status like check conclusions and exit codes, never external content) per session, and delivers them through a plugin-supplied callback when the session is idle. The `pollSeconds` getter surfaces the poll cadence to tool output and notifications. Process-lifetime state by design - no SQLite. |
 | `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
 | `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. The pool is the fallback base for registrations with no usable session title. |
+| `tab-state.ts` | Read-only open-tab reader for the chat roster: globs every opencode channel's `tabs.json` (global + cwd scopes), subtracts fresh confirmed tab closes, and composes the provider the roster surfaces and broadcast targeting consume. Degrades to an empty set - never a false OPEN. See [features/cross-session-chat.md](features/cross-session-chat.md). |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
-| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, plan-refinement, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions: the nudge-backed ones (defrag, extract, hygiene, reflect) from the prompt cores, and the self-contained ones (refine, whois, and the review-mode couchings peer-review, self-review) inline in the registry; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (everything that works on all three hosts: the memory workflows, the review specialists — whose roster comes from `REVIEW_SPECIALISTS` in prompts.ts — plus the synthesizer, context, followup, and response skills, the walkthrough and archaeology skills, the refinement family, the writing skills, and verification/export) and `OPENCODE_ONLY_SKILLS` (the code-review coordinator and thatch-coordination — they need sub-agent support, so they are not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |
@@ -129,7 +130,7 @@ methods. The v1 hook shapes:
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
-| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
+| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the host action (compact: v1 `session_compact` via `executeCommand`, v2 `session.compact` on the promise domain; exit: record the session's watcher deaths, unregister it from chat, then v1 `app.exit` via `publish` or v2 the exit-tab-closed rpc event closing the session's own tab). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
 | `chat.message` | Recall nudge: embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges fire independently in separate try/catch blocks with separate synthetic parts. There is deliberately NO extraction nudge here - extraction is plugin-driven at session idle (see the extraction feature doc); the old model-driven handshake raced its own state machine and was removed. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
@@ -268,14 +269,16 @@ extraction cycle
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks
 
-toast notifications (opencode-only, TUI-rendered)
+toast notifications (opencode-only, TUI-rendered; the bridge's toast
+  event -> the TUI plugin's ui.toast.show on v2)
   → client.tui.showToast — best-effort, silently ignored if TUI not
     connected (headless mode); model-invisible (goes to the user only,
     not the conversation history — the inverse of synthetic nudge parts,
     which are model-visible but TUI-hidden)
   → extraction metrics: `[thatch] new: N, updated: M, deleted: K` (success
-    variant, 4s) — fires when an extraction child goes idle; no-save runs
-    show `[thatch] extraction complete — nothing to save` (info variant)
+    variant, 4s) — fires when an extraction child goes idle, but ONLY when
+    memories were actually written; no-save runs show nothing (no
+    notification fatigue)
   → recall matches: `[thatch] recalled N memories` (info variant, 3s) —
     fires when chat.message matches stored memories
   → prediction matches: `[thatch] N predictions surfaced` (info variant,

package/docs/dev/features/README.md

@@ -23,7 +23,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
 | [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
-| [commands.md](commands.md) | Slash commands (on-demand actions from shared prompt cores, wrap-ups, host sync) |
+| [commands.md](commands.md) | Slash commands (on-demand actions: prompt cores and skill couchings, wrap-ups, host sync) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |

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

@@ -113,6 +113,8 @@ Parameters: `behavior` (statement, semantic match at cosine >= 0.85),
 - Injects `behaviorNudge(items)` as a separate synthetic text part with a
   `[thatch] Situational behaviors` header.
 - 0-evidence behaviors use "consider"; behaviors with evidence use "do".
+- The block ends with a snapshot footer (same as the prediction nudge): the
+  labels are a submission-time snapshot, not a live view.
 - Independent try/catch — a behavior failure does not block recall or
   prediction.
 - Toast: `[thatch] N behaviors surfaced`.
@@ -250,6 +252,14 @@ behavior_provenance(
 )
 ```
 
+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
+(atomically with the insert), and deleting an item bumps the matchers whose
+edges cascade away (atomically with the delete). The matcher's own text may
+legitimately be older than its links (a corrected behavior re-links the
+existing matcher without touching its text). A behavior's `updated_at` is
+written at creation and then moved by the last confidence change.
+
 ## Key invariants
 
 1. **The firewall principle does NOT apply.** The LLM grading its own

package/docs/dev/features/cli.md

@@ -51,7 +51,8 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
   (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
   text). Rows are split into Active and Stale sections by
   `splitChatRoster()`; the status column is `chatLiveness()`'s verdict
-  (`fresh`/`stale` for opencode rows, `active`/`idle` for MCP rows).
+  (`open`/`recent`/`stale` for opencode rows - the open-tab reader feeds
+  the open/recent split - `active`/`idle` for MCP rows).
 - `chat tail` follows the message stream as JSONL: one `ChatTailEvent`
   per line via `formatChatTailJsonl()` (a bare `JSON.stringify`; no ANSI,
   no markdown rendering, no local-time conversion - the tail is a log for

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, 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,12 +286,43 @@ 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`
+(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 and Stale sections - the stale section's
-explainer says what stale means - and `chat_send` states the recipient's
+explainer says what stale means, 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
+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): project first,
 alphabetical, with no-project rows last; most recently seen first within
 a project. The CLI roster bounds
@@ -312,6 +349,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 +528,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 +544,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