@jeffober/thatch 0.2.4 → 0.2.6

package/src/commands.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  REVIEW_SPECIALISTS,
   defragCore,
   extractionCore,
   hygieneCore,
@@ -24,12 +25,17 @@ import {
  *
  * Two command families live here:
  *
- * - Actions (/thatch/defrag, extract, hygiene, reflect): user-invoked
- *   wrappers around a behavior that the nudges otherwise only run on their
- *   own schedule. Each action body is a prompt core from src/prompts.ts, so
- *   nudge and command wording cannot drift.
+ * - Actions (/thatch/defrag, extract, hygiene, peer-review, refine,
+ *   reflect, self-review, whois): user-invoked commands. The nudge-backed
+ *   ones (defrag, extract, hygiene, reflect) render prompt cores from
+ *   src/prompts.ts, so nudge and command wording cannot drift. The rest
+ *   (peer-review, refine, self-review, whois) are self-contained here:
+ *   they have no nudge counterpart. peer-review and self-review couch the
+ *   code review pipeline with a mode overlay: the same machinery, with
+ *   findings weighted for whose work is under review.
  * - Wrap-ups (/thatch/compact, exit): greenlight-token commands that need
- *   the opencode plugin's TUI control routes, so they are opencode-only.
+ *   the opencode plugin's host action routes (the compact trigger and the
+ *   session close-out), so they are opencode-only.
  */
 
 /** Greenlight token ending /thatch/compact's assistant response when compaction is safe. */
@@ -39,11 +45,13 @@ export const COMPACT_READY_TOKEN = "THATCH_COMPACT_READY";
 export const EXIT_READY_TOKEN = "THATCH_EXIT_READY";
 
 /**
- * The plugin triggers compaction by running the TUI's compact action. The
- * execute-command route only accepts legacy alias names, and "session_compact"
- * maps to the same session.compact action the built-in /compact command runs.
- * There is no exit alias, so the exit path publishes the TUI keymap command
- * ("app.exit") directly via /tui/publish.
+ * The greenlight token's host action, per host: v1 drives the TUI
+ * (compaction via the "session_compact" legacy alias through
+ * executeCommand, the exit via the "app.exit" keymap command through
+ * /tui/publish). v2 calls session.compact on the plugin's promise domain
+ * and emits the session-tab bridge's TUI-only exit-tab-closed event; the
+ * runtime records the exiting session's watcher deaths before either host
+ * action runs (src/runtime.ts).
  */
 
 const sharedChecklist = `1. Flush pending persistence. Call thatch_get_extraction_payload; if it returns buffered tool interactions, process them now (write any memories worth keeping), then call thatch_extraction_done to mark them complete. Complete any memory writes you promised earlier but have not made.
@@ -55,10 +63,42 @@ $ARGUMENTS
 
 (That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
 
+/**
+ * How the review-mode commands (peer-review, self-review) run the code
+ * review machinery on the host at hand. opencode has the
+ * thatch-code-review coordinator skill and sub-agent dispatch; Claude Code
+ * and Cursor have neither, so the same procedure runs inline through the
+ * shared specialist skills. The mode overlay that differentiates the two
+ * commands lives in each command's own body and applies in both paths:
+ * sub-agent briefings on opencode, specialist passes inline elsewhere.
+ *
+ * Both couchings below are shared consts interpolated into the two bodies
+ * so the commands' procedure and target resolution cannot drift; each body
+ * keeps only its mode rules. The specialist roster and count come from
+ * REVIEW_SPECIALISTS in src/prompts.ts, the same source as the install
+ * list in src/skills.ts.
+ */
+const reviewPipelineCouching = `If the thatch-code-review skill is available, load it and follow its steps, with one addition: apply the mode rules below throughout - to context gathering, every specialist briefing, and the synthesis.
+
+If that skill is not available on this host, run the same procedure yourself, in order:
+- Resolve the review range. Compute the merge-base against the base branch's remote tracking ref (for example origin/main), not the working branch's own upstream, and cite every file:line against the range's head SHA with git show, never the working tree. A PR or MR number resolves through the host's CLI (gh pr view, glab mr view) plus fetching the head ref (git fetch origin refs/pull/N/head on GitHub, refs/merge-requests/N/head on GitLab, or the source branch). A repository with no remote reviews the working tree's recent commits instead.
+- Build the context brief with the thatch-review-context skill.
+- Partition large diffs into review units.
+- Run the ${REVIEW_SPECIALISTS.length} specialist skills (${REVIEW_SPECIALISTS.join(", ")}) on each unit.
+- Synthesize with thatch-review-synthesizer.
+The mode rules below apply in every specialist pass and in the synthesis, on every host. If the specialist skills are not installed on this host, tell the user to run thatch setup for it.`;
+
+/**
+ * How the review-mode commands resolve what to review. Shared so the two
+ * commands accept the same target syntax and default identically.
+ */
+const reviewTargetCouching = `The user message may name the review target: a branch, a PR or MR number, or a git range. On MCP hosts the Focus: line carries that text instead. If no target is given, review the current branch against its base.`;
+
 /**
  * One on-demand action: the command name (minus the thatch/ prefix), the
  * description shown in the command menu, and the instruction body (a prompt
- * core). opencodeOnly marks actions that need a session identity or other
+ * core for the nudge-backed actions, self-contained text for the rest).
+ * opencodeOnly marks actions that need a session identity or other
  * plugin-only capability; those are excluded from Claude Code command files
  * and MCP prompts.
  */
@@ -71,8 +111,11 @@ export interface ActionDef {
 
 /**
  * The on-demand action set, shared by every host that renders actions. The
- * bodies come from prompt cores so a wording change lands in the nudge and
- * the command at once. `tool` renders tool names in the host's spelling.
+ * nudge-backed bodies (defrag, extract, hygiene, reflect) come from prompt
+ * cores in src/prompts.ts so a wording change lands in the nudge and the
+ * command at once; the rest (peer-review, refine, self-review, whois) are
+ * self-contained here because they have no nudge counterpart. `tool`
+ * renders tool names in the host's spelling.
  */
 export function actionDefs(tool: ToolNamer): ActionDef[] {
   return [
@@ -100,6 +143,25 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
       description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
       body: hygieneCore(),
     },
+    {
+      name: "peer-review",
+      description: "Review another author's change (PR, MR, branch, or git range) through the full review pipeline",
+      // Skill-couching action (refine precedent): no nudge counterpart, so
+      // the body lives here. The memory-walk tool name is spelled through
+      // the namer so MCP renderings carry the mcp__thatch__ form.
+      body: `Review a change authored by someone else: a PR, MR, or branch on origin. The review runs the full thatch review pipeline with findings weighted for org velocity.
+
+${reviewTargetCouching}
+
+${reviewPipelineCouching}
+
+## Peer review mode rules
+
+- Weight for org velocity. Findings that speed up or unblock the whole team outrank findings about individual lines. The highest-value findings: a simpler method that achieves the same outcome; an existing function or helper that already does what this change reimplements; documentation that is accurate and extremely clearly written; unintended consequences for callers, sibling features, or contracts the author could not see.
+- Walk the project's memory. The author does not have this project's persistent memory; you do. During context gathering, call ${tool("memory_recall")} with several phrasings about the touched area: past incidents, design constraints, rejected approaches, known footguns. Check each recalled item against the change and report the ones that apply. Frame these findings as sharing knowledge the author could not have had, not as catching mistakes.
+- Do not re-litigate settled designs. When the context brief or memory shows a design decision was agreed (in a ticket discussion, a prior review acceptance, recorded docs, or a memory of the agreement), treat the decision as settled. Findings may address how the change implements that decision. Findings that argue the decision itself was wrong are out of scope for this review.
+- Never report findings of the form "if someone changes this in the future, it will silently break." This review does not solve for engineers who change code without reading it. It solves for engineers and LLMs who WILL read the code. For them, verify the change leaves a breadcrumb trail to wherever this organization records how a feature works (a context module, a feature doc, a README). Flag a missing trail. Do not flag hypothetical future misuse.`,
+    },
     {
       name: "refine",
       description: "Refine a plan under the project type's requirements (classifies the project first)",
@@ -115,6 +177,40 @@ The user message may name a project type (team-app, personal, shared-lib, spike,
       description: "Persist what this session learned as memories",
       body: reflectCore(tool),
     },
+    {
+      name: "self-review",
+      description: "Review the user's own completed work before submitting it",
+      // Skill-couching action (see peer-review). Names no tools, so the
+      // MCP spelling test exempt list covers it.
+      body: `Review the user's own completed work before submitting it: as a PR or MR on a shared project, or as a direct commit on a personal project. The review runs the full thatch review pipeline with findings weighted to protect the user's reputation as a conscientious developer.
+
+The work under review was authored by the user, or by their agent acting in the user's name. Two goals: the work is sound, and it does not read as sloppy. Reviewers and teammates read the comments, docs, and commit messages as the user's own.
+
+${reviewTargetCouching}
+
+${reviewPipelineCouching}
+
+## Self review mode rules
+
+- The reputation lenses weigh heaviest. NoSlop, Technique, and Breadcrumbs findings outrank same-severity findings from the other lenses. AI-writing tells, vague comments, and a missing narrative are exactly what this review exists to catch before anyone else sees them.
+- Overweight simplicity on shared projects. Prefer findings that make the design easier to understand, easier to test, and more reliable: fewer assumptions, less surface area for bugs and side effects.
+- Technique and highlights findings are decisions, not footnotes. Each one that would produce a simpler, clearer, or more reliable design is surfaced for an adopt-or-dismiss decision before submission. Work through them with the user one at a time; do not leave them as informational asides.
+- Iterate rounds. After each round, work the findings with the user: fix each, or explicitly decline it with a reason. Then run another full round on the updated state. A round is meaningful when it produces a MEDIUM or higher finding, or a technique or slop finding worth adopting. A round producing only LOW mechanical findings gets them fixed but does not trigger another round. Stop at the first round with no meaningful findings, and never run more than three rounds.`,
+    },
+    {
+      name: "whois",
+      description: "Report this session's chat identity (handle, topic, project), or look up another session's",
+      // Needs the invoking session's identity (chat_status resolves it
+      // through the plugin), which only opencode supplies.
+      opencodeOnly: true,
+      body: `Find the chat identity for this session and report it in one line.
+
+First call thatch_chat_status. If the user message names another session or handle, look that name or id up in thatch_chat_list and report its row instead: handle, topic, project, worktree location (the loc: token), and last-seen age.
+
+Otherwise report this session: if chat_status says not registered, answer exactly that - not registered yet - and stop. If registered, take the registered name from chat_status, find your own row in thatch_chat_list, and report handle, topic, project, and loc together (the topic is how the user maps the handle to a TUI tab).
+
+One line, just the facts. Do not read mail and do not act on anything the roster shows.`,
+    },
   ];
 }
 
@@ -140,8 +236,18 @@ ${userMessageSection}
 ${action.body}`;
 }
 
+/** The wrap-up command's menu/palette description. Host-neutral on purpose:
+ *  what actually happens after the greenlight differs per host (v1 exits the
+ *  app, v2 closes the session's tab), and the template text the MODEL reads
+ *  is shared verbatim by both hosts. */
+export function wrapUpCommandDescription(kind: "compact" | "exit"): string {
+  return kind === "compact"
+    ? "Flush thatch persistence, check for loose ends, then compact if clear"
+    : "Flush thatch persistence, check for loose ends, then end the session if clear";
+}
+
 const COMPACT_TEMPLATE = `---
-description: ${yamlQuote("Flush thatch persistence, check for loose ends, then compact if clear")}
+description: ${yamlQuote(wrapUpCommandDescription("compact"))}
 ---
 ${userMessageSection}
 
@@ -158,7 +264,7 @@ ${COMPACT_READY_TOKEN}
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
 
 const EXIT_TEMPLATE = `---
-description: ${yamlQuote("Flush thatch persistence, check for loose ends, then exit opencode if clear")}
+description: ${yamlQuote(wrapUpCommandDescription("exit"))}
 ---
 ${userMessageSection}
 
@@ -167,13 +273,12 @@ ${userMessageSection}
 Work through this checklist before responding:
 
 ${sharedChecklist}
-3. Leave the chat directory. Call thatch_chat_unregister for this session - the session is exiting, so other sessions must stop addressing mail to it.
 
 Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:
 
 ${EXIT_READY_TOKEN}
 
-If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. opencode will only exit when the token is present.`;
+If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only close when the token is present.`;
 
 /** One command: the command name (minus the thatch/ prefix) and its full markdown file content. */
 export interface CommandDef {
@@ -207,7 +312,7 @@ export function opencodeCommandDefs(): CommandDef[] {
 /**
  * The Claude Code command set: the actions minus the opencode-only ones.
  * The wrap-up commands are excluded too - their greenlight check needs the
- * plugin's command.execute.before arming and TUI control routes.
+ * plugin's command.execute.before arming and host action routes.
  */
 export function claudeCommandDefs(): CommandDef[] {
   return actionDefs(mcpToolName)

package/src/db.ts

@@ -11,7 +11,7 @@ import { PREDICTION_K, PREDICTION_P0, PREDICTION_W_SOFT } from "./scoring-engine
 import type { RepoPathCache, RepoPathRow } from "./git";
 
 export { cosineSimilarity } from "./vector-math";
-export type { PredictionNudgeItem, MatcherRow, PredictionRow, ScoredPrediction } from "./prediction";
+export type { PredictionNudgeItem, MatcherRow, PredictionRow, ScoredPrediction, PredictionDedupCandidate } from "./prediction";
 export type { BehaviorNudgeItem, BehaviorRow, ScoredBehavior } from "./behavior";
 export type { ChatSessionRow, ChatInboxItem, ChatNotificationRow, ChatWorktreeKind } from "./chat";
 
@@ -60,9 +60,15 @@ export class ThatchDB {
   #predictionsStore!: PredictionEngine;
   #behaviorsStore!: BehaviorEngine;
   #chatStore!: ChatStore;
+  // The open-tab provider for broadcast targeting (roster OPEN-vs-RECENT).
+  // Optional: unwired (tests, callers with no tab reader) means no tab
+  // signal, so every fresh opencode row degrades to RECENT - honest, never
+  // a false OPEN. Production callers wire chatOpenTabs(src/tab-state.ts).
+  #chatOpenTabs?: () => ReadonlySet<string>;
 
-  constructor(path: string) {
+  constructor(path: string, opts: { chatOpenTabs?: () => ReadonlySet<string> } = {}) {
     this.#path = path;
+    this.#chatOpenTabs = opts.chatOpenTabs;
     this.#open();
   }
 
@@ -249,6 +255,22 @@ export class ThatchDB {
       )
     `);
 
+    // Pairwise dedup verdicts for predictions (the prediction-side analog of
+    // dedup_pairs). findPredictionDuplicates skips pairs recorded here;
+    // prediction_mark_checked writes them. The id pair is stored in canonical
+    // sorted order so (A,B) and (B,A) are the same row - readers must sort
+    // identically.
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS prediction_dedup_pairs (
+        store      TEXT NOT NULL,
+        id_a       TEXT NOT NULL,
+        id_b       TEXT NOT NULL,
+        status     TEXT NOT NULL,
+        checked_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        PRIMARY KEY (store, id_a, id_b)
+      )
+    `);
+
     // Behavior engine: the LLM's codified self-discipline rules. Same
     // shape as the prediction engine (matchers, behaviors, edges,
     // provenance) but separate tables because the semantics differ.
@@ -380,6 +402,20 @@ export class ThatchDB {
       )
     `);
 
+    // Sessions the plugin itself created as machinery (direct-extraction
+    // children). The in-memory child maps that keep these sessions out of
+    // the chat directory are lost on plugin reloads and daemon restarts;
+    // a marker here is durable, so the auto-registration paths refuse the
+    // session even when the maps were lost. Markers age out with the
+    // auto-row TTL (session ids are never reused).
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS chat_machinery (
+        session_id TEXT PRIMARY KEY,
+        reason     TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    `);
+
     // Hook-parent-process -> session mapping (Claude Code identity anchor):
     // hooks learn the true session id from the host's hook payload and run
     // as children of the same process that spawned the MCP server, so the
@@ -907,6 +943,14 @@ export class ThatchDB {
     return this.#predictions.scorePredictionNudge(stores, embedding, threshold, limit);
   }
 
+  findPredictionDuplicates(store: string, threshold = 0.70) {
+    return this.#predictions.findPredictionDuplicates(store, threshold);
+  }
+
+  markPredictionPairChecked(store: string, idA: string, idB: string, status: string): void {
+    this.#predictions.markPairChecked(store, idA, idB, status);
+  }
+
   findNearestMatcher(store: string, embedding: Float32Array, threshold: number) {
     return this.#predictions.findNearestMatcher(store, embedding, threshold);
   }
@@ -1035,12 +1079,35 @@ export class ThatchDB {
     return this.#chat.clearLeaveTombstone(sessionID);
   }
 
+  markChatMachinery(sessionID: string, reason: string) {
+    return this.#chat.markMachinery(sessionID, reason);
+  }
+
+  isChatMachinery(sessionID: string) {
+    return this.#chat.isMachinery(sessionID);
+  }
+
   chatLeaveSuperseded(sessionID: string, project: string | null) {
     return this.#chat.leaveSuperseded(sessionID, project);
   }
 
   broadcastChatMessage(fromSession: string, body: string) {
-    return this.#chat.broadcast(fromSession, body);
+    return this.#chat.broadcast(fromSession, body, this.#chatOpenTabs?.());
+  }
+
+  /**
+   * Confirmed tab closes recorded by the roster (the session_tab tool's
+   * bridge event). Readers subtract the fresh ones from the open-tab set
+   * (effectiveOpenTabs) so a residue tabs.json row cannot read OPEN right
+   * after a confirmed close.
+   */
+  chatTabClosures(): { sessionID: string; at: string }[] {
+    return this.runtimeStateAll()
+      .filter((r) => r.kind === "chat_tab_closed")
+      .flatMap((r) => {
+        const at = (r.value as { at?: string } | null)?.at;
+        return typeof at === "string" ? [{ sessionID: r.sessionID, at }] : [];
+      });
   }
 
   chatMessageStatus(sessionID: string) {
@@ -1120,6 +1187,10 @@ export class ThatchDB {
     return this.#chat.read(sessionID);
   }
 
+  chatMessageById(sessionID: string, id: number) {
+    return this.#chat.messageById(sessionID, id);
+  }
+
   unreadChatCount(sessionID: string) {
     return this.#chat.unreadCount(sessionID);
   }

package/src/git.ts

@@ -102,7 +102,9 @@ function canonicalWorktreeKeys(dir: string): string[] {
   return [...new Set(keys)];
 }
 
-function pathExists(dir: string): boolean {
+/** Existence check shared by git helpers and tool arg validation (the
+ *  session-tab tool validates its directory/worktree args with it). */
+export function pathExists(dir: string): boolean {
   try {
     statSync(dir);
     return true;

package/src/hygiene.ts

@@ -24,6 +24,11 @@ export async function hygieneReport(
     parts.push(`${dupes} duplicate-candidate pair${dupes === 1 ? "" : "s"} pending review`);
   }
 
+  const predDupes = db.findPredictionDuplicates(repo).length;
+  if (predDupes > 0) {
+    parts.push(`${predDupes} prediction duplicate pair${predDupes === 1 ? "" : "s"} pending review`);
+  }
+
   const cutoff = new Date(Date.now() - STALE_DAYS * 86_400_000).toISOString();
   const stale = db.staleEntryCount(repo, cutoff);
   if (stale > 0) {

package/src/mcp.ts

@@ -6,6 +6,7 @@ import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
 import { checkSetup, setupClaudeCode, setupCursor } from "./setup";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
+import { chatOpenTabs as chatOpenTabsProvider } from "./tab-state";
 import { actionDefs, type ActionDef } from "./commands";
 import { mcpToolName } from "./prompts";
 import { SidebandServer, sidebandSocketPath } from "./sideband";
@@ -70,7 +71,9 @@ export function compileTools(): Map<string, CompiledTool> {
   for (const def of TOOL_DEFS) {
     // opencode-only tools depend on host capabilities MCP servers don't
     // have (e.g. session identity via HostToolContext) - never expose them.
-    if (def.opencodeOnly) continue;
+    // v2-only tools ride v2 plugin surfaces (session move, rpc emit) with
+    // no MCP equivalent - same rule.
+    if (def.opencodeOnly || def.v2Only) continue;
     const schema = z.object(def.args);
     map.set(def.name, {
       def,
@@ -120,7 +123,12 @@ export function compilePrompts(): Map<string, ActionDef> {
  * prompt and search for matches without loading the model themselves.
  */
 export async function runMcpServer(): Promise<void> {
-  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  // Deliberate superset of detectRepo's own chain (src/git.ts): the pinned
+  // THATCH_PROJECT_DIR (written into project-local MCP configs by setup)
+  // beats ambient host vars, which beat the spawn cwd - the server's spawn
+  // cwd is the one input no in-repo test can pin.
+  const projectDir =
+    process.env.THATCH_PROJECT_DIR ?? process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
 
   const home = process.env.HOME ?? "/tmp";
   const configHome = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
@@ -129,8 +137,14 @@ export async function runMcpServer(): Promise<void> {
 
   // The DB must exist before identity detection: detectRepo consults the
   // repo_paths cache when the project directory is gone (deleted worktree).
-  const db = new ThatchDB(dbPath);
-  const repo = await detectRepo(projectDir, repoPathCache(db));
+  const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
+  const detected = await detectRepo(projectDir, repoPathCache(db));
+  // unknown-to-global, matching the hook's mapping (bin/thatch): chat
+  // registration must follow the same store the tools would read, and
+  // resolveStore degrades both spellings to the global store anyway. The
+  // alignment keeps hook-registered and server-registered rows comparable
+  // by project - which the `as` identity binding depends on.
+  const repo = detected === "unknown" ? "global" : detected;
   const model = new BgeEmbeddingModel(modelName);
 
   await seedDefaultBehaviors(db, model);
@@ -160,6 +174,9 @@ export async function runMcpServer(): Promise<void> {
     defaultStore: repo,
     extractionPayloadProvider,
     drainExtractionQueue,
+    // Same-machine tab reader: the MCP server can read the local opencode
+    // state tree, so its roster renders the same open/recent split.
+    openTabs: chatOpenTabsProvider(() => db.chatTabClosures()),
     // Claude Code identity anchor, two model-proof layers:
     //  1. The hooks record (parent pid -> session) from payloads the model
     //     cannot influence, and this server is a child of the same Claude
@@ -251,6 +268,27 @@ export async function runMcpServer(): Promise<void> {
   // requests. Never blocks tool calls.
   startVersionChecker(dbPath);
 
+  // Idempotent teardown, shared by the stdin-end path (the host closed the
+  // pipe - the normal shutdown) and the signal handlers (SIGINT/SIGTERM/
+  // SIGHUP kill the process mid-loop, and without handlers they skipped
+  // every teardown step). Order matters: the sideband goes first (nothing
+  // may reach the model after disposal), the model's ONNX sessions release
+  // before the db closes, and the db close runs in a finally so a disposal
+  // failure cannot leak the connection.
+  const teardown = createMcpTeardown({
+    sideband,
+    model,
+    db,
+    dbPath,
+    stopVersionChecker,
+    removeVersionFile,
+  });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.on(signal, () => {
+      void teardown(signal).then(() => process.exit(0));
+    });
+  }
+
   // Read stdin line by line. Each line is a complete JSON-RPC message.
   const decoder = new TextDecoder();
   let buf = "";
@@ -303,10 +341,64 @@ export async function runMcpServer(): Promise<void> {
     }
   }
 
-  sideband.stop();
-  stopVersionChecker();
-  removeVersionFile(dbPath);
-  db.close();
+  await teardown("stdin-end");
+}
+
+/**
+ * Builds the idempotent MCP-server teardown. Injected deps so tests can
+ * spy on the close order without spawning anything: sideband first
+ * (nothing may reach the model after disposal), version checker + file
+ * next, the model's native ONNX sessions in a catch (a disposal failure
+ * must not skip the db close), and the db in a finally.
+ */
+export function createMcpTeardown(deps: {
+  sideband: { stop(): void };
+  model: { dispose(): Promise<void> };
+  db: { close(): void };
+  dbPath: string;
+  stopVersionChecker: () => void;
+  removeVersionFile: (dbPath: string) => void;
+}): (reason: string) => Promise<void> {
+  let inFlight: Promise<void> | undefined;
+  return (reason: string): Promise<void> => {
+    // Idempotent ACROSS awaits: a second call while the first teardown is
+    // still running returns the IN-FLIGHT promise, so an early
+    // process.exit(0) waits out the model disposal and the db close
+    // instead of cutting them (a fresh resolve() skipped them). `torn`
+    // tracking is subsumed: inFlight is set synchronously before any await.
+    if (inFlight) return inFlight;
+    void reason;
+    // Every step is isolated: a teardown step's own failure must not
+    // block the remaining ones (the sideband throwing on an
+    // already-unlinked socket used to skip the model disposal and the
+    // db close entirely).
+    try {
+      deps.sideband.stop();
+    } catch (err) {
+      console.error(`[thatch] MCP sideband stop failed: ${err}`);
+    }
+    try {
+      deps.stopVersionChecker();
+    } catch (err) {
+      console.error(`[thatch] MCP version-checker stop failed: ${err}`);
+    }
+    try {
+      deps.removeVersionFile(deps.dbPath);
+    } catch (err) {
+      console.error(`[thatch] MCP version-file removal failed: ${err}`);
+    }
+    inFlight = deps.model
+      .dispose()
+      .catch((err: unknown) => console.error(`[thatch] MCP model disposal failed: ${err}`))
+      .finally(() => {
+        try {
+          deps.db.close();
+        } catch (err) {
+          console.error(`[thatch] MCP db close failed: ${err}`);
+        }
+      });
+    return inFlight;
+  };
 }
 
 /**
@@ -390,7 +482,7 @@ async function dispatch(
             arguments: [
               {
                 name: "focus",
-                description: "Optional scope for the action, e.g. which store to work on",
+                description: "Optional text for the action: a scope (for example, which store to work on), a review target (branch, PR, MR, or git range), or other context",
                 required: false,
               },
             ],

package/src/opencode/tui-plugin.ts

@@ -0,0 +1,90 @@
+// The session-tab TUI CLI plugin: the TUI-side half of the session-tab
+// feature (docs/dev/features/session-tabs.md). Loaded by the opencode v2 TUI
+// from the package's ./tui entrypoint; runs once per TUI window, next to the
+// tab primitives it drives.
+//
+// The server-side adapter cannot reach the tab strip - the v2 plugin event
+// domain is subscribe-only and the HTTP surface has no publish route - so
+// the flow crosses processes over an rpc event: the adapter emits
+// rpc.thatch-tabs.tab-opened (sessionID + the coordinator instance's
+// directory), the SSE feed fans it to every window, and THIS plugin acts on
+// it with ui.tabs.open. The guard mirrors the built-in tui.* handlers
+// (packages/tui/src/app.tsx): an event only acts on the window whose
+// directory matches the event's location. ui.tabs.open is idempotent and
+// never steals focus, so no dedupe state is kept - a hot reload re-runs
+// setup from fresh state and double events are no-ops.
+//
+// ISOLATION: this module must only be imported by the TUI process - tests
+// import the pure filter/guard logic from src/session-tab-shared.ts, never
+// this file (the tui entrypoint imports solid-js, an uninstalled optional
+// peer).
+
+import { Plugin } from "@opencode/plugin/tui";
+import { isExitTabClosedEvent, isTabClosedEvent, isTabOpenedEvent, isToastEvent, passesDirectoryGuard } from "../session-tab-shared";
+
+export default Plugin.define({
+  id: "jeffober-thatch-tui",
+  setup(context) {
+    const off = context.data.listen(({ details }) => {
+      const windowDirectory = context.location?.directory ?? context.data.location.default().directory;
+      if (!passesDirectoryGuard(details.location?.directory, windowDirectory)) return;
+      // Two close events, one TUI action: tab-closed (the session_tab_close
+      // tool's confirmed close - the pump also runs its death bookkeeping)
+      // and exit-tab-closed (the wrap-up exit's close - the runtime records
+      // the deaths itself before emitting, so the pump ignores that one).
+      if (isTabClosedEvent(details.type) || isExitTabClosedEvent(details.type)) {
+        // Close the tab if THIS window has one for the session. Windows that
+        // never opened it (and windows at other directories, filtered above)
+        // return false - that is the correct no-op, not an error. The close
+        // is reopenable by the user (the strip's reopen stack), so this is
+        // tab-level, not session deletion.
+        const closeID = (details.data as { sessionID?: string }).sessionID;
+        if (!closeID) {
+          console.error("[thatch] tab-close event without a sessionID");
+          return;
+        }
+        if (!context.ui.tabs.close(closeID)) {
+          console.error("[thatch] tab-close requested but no tab matched (or tabs are disabled)");
+        }
+        return;
+      }
+      // The toast request: the server-side runtime's only TUI feedback
+      // channel (alerts, extraction metrics, chat registration, blocked
+      // wrap-ups). Best-effort like every toast - the event is ephemeral,
+      // so a TUI that is absent simply never shows it.
+      if (isToastEvent(details.type)) {
+        const toast = details.data as { message?: string; variant?: string; duration?: number };
+        if (typeof toast.message !== "string") {
+          console.error("[thatch] toast event without a message");
+          return;
+        }
+        context.ui.toast.show({
+          message: toast.message,
+          variant: (toast.variant as "info" | "success" | "warning" | "error") ?? "info",
+          duration: typeof toast.duration === "number" ? toast.duration : undefined,
+        });
+        return;
+      }
+      if (!isTabOpenedEvent(details.type)) return;
+      const sessionID = (details.data as { sessionID?: string }).sessionID;
+      if (!sessionID) {
+        console.error("[thatch] tab-opened event without a sessionID");
+        return;
+      }
+      // Sync the session into the TUI's cache before opening: the strip
+      // renders the session's real title instead of the new-session
+      // fallback.
+      void context.data.session
+        .sync(sessionID)
+        .catch(() => {})
+        .then(() => {
+          if (!context.ui.tabs.open(sessionID)) {
+            console.error("[thatch] tab-open requested but session tabs are disabled in this window");
+          }
+        });
+    });
+    // The unsubscribe IS the cleanup: without it every plugin hot reload
+    // leaks another listener.
+    return off;
+  },
+});