@jeffober/thatch 0.2.5 → 0.2.7

package/docs/user/skills.md

@@ -43,16 +43,17 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
 | `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-clarity` | Prose clarity in comments, docstrings, error strings, and docs: made-up phrases, buzzwords, untranslated jargon, clause chains, buried leads, doc/code responsibility splits, checked against the project's clear-writing rules regardless of who wrote the text. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
 | `thatch-review-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, never blocking. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
-| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work, related PRs) before a review. Prevents false positives about intentionally deferred work and about pieces delivered by sibling PRs in a stack or release train. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
 | `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
-| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. |
+| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. Also the machinery behind the `/thatch/self-review` and `/thatch/peer-review` mode commands, which couch it with a weighting overlay and run the specialists inline on hosts where the coordinator is not installed. |
 
 ### Walkthrough skills
 
@@ -75,15 +76,15 @@ Skills are split into shared (all hosts) and opencode-only:
 | Skill | Purpose |
 |-------|---------|
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
-| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
+| `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). Plans with UI or session state must include a state-and-transition matrix; a revision self-check runs after each revision; extended runs rotate reviewer lenses and stop on a round with no build-changing findings. |
 
 ### Plan refinement skills
 
 | Skill | Purpose |
 |-------|---------|
-| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. Deep-mode triggers in the core skill are binding; type deltas relax round counts, never mode selection. |
 | `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
-| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. Relaxes round counts, never mode selection. |
 | `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
 | `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
 | `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
@@ -104,7 +105,9 @@ window.
   re-installs from its canonical source). Edit the canonical source
   in the thatch repo instead.
 - The opencode-only coordinator (`thatch-code-review`) requires
-  sub-agent support. It is not available on Claude Code or Cursor.
+  sub-agent support. It is not available on Claude Code or Cursor; the
+  `/thatch/self-review` and `/thatch/peer-review` commands run the
+  same specialists inline there instead.
 - Skill content is markdown read at runtime, not compiled into the
   binary. If the skill file is missing or corrupted, the skill will
   not load (silent failure).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/capabilities.ts

@@ -54,7 +54,13 @@ export interface HostCapabilities {
    * only the title carries over.
    */
   sessionCreate(input: { parentID: string; title: string }): Promise<{ id: string }>;
-  /** Delete a session (child-session cleanup). Degrades to a no-op resolve on v2. */
+  /**
+   * Delete a session (extraction-child cleanup, so the picker stays clean
+   * and `-c` resume does not land in a child). v1: client delete. v2:
+   * session.remove on the promise domain (upstream #52387), runtime-guarded
+   * because the pinned dev types predate the surface - an older host
+   * degrades to a no-op (best-effort by the caller's contract).
+   */
   sessionDelete(id: string): Promise<void>;
   /**
    * Prompt a session with text parts. `sync` mode blocks until the child
@@ -90,15 +96,23 @@ export interface HostCapabilities {
   /**
    * Trigger the host's compaction for a session (the wrap-up compact
    * action). v1 dispatches the TUI's session_compact command (the legacy
-   * alias route; the id is ignored). v2 has no compaction trigger reachable
-   * from the promise context and degrades to a logged no-op.
+   * alias route; the id is ignored). v2 calls session.compact on the
+   * promise domain (upstream #52385), runtime-guarded because the pinned
+   * dev types predate that surface; an older host degrades to a logged
+   * no-op.
    */
   compactSession(sessionID: string): Promise<void>;
   /**
-   * Exit the host application (the wrap-up exit action). v1 publishes the
-   * TUI's app.exit command; v2 has no TUI surface and degrades to a no-op.
+   * End the session's presence on the host (the wrap-up exit action). The
+   * runtime records the session's watcher deaths and unregisters it from
+   * chat BEFORE calling here, so implementations only close out the host
+   * side. v1 publishes the TUI's app.exit command - the id is unused
+   * because the whole app is leaving. 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 an app-wide exit would take down unrelated
+   * sessions too); a host with no bridge degrades to a logged no-op.
    */
-  exitHost(): Promise<void>;
+  exitHost(sessionID: string): Promise<void>;
 }
 
 /**

package/src/chat.ts

@@ -351,18 +351,28 @@ export function humanAge(iso: string, now = Date.now()): string {
   return `${Math.floor(minutes / (24 * 60))}d ago`;
 }
 
-/** The liveness verdict for one roster row, from heartbeat age alone:
- *  - "fresh"/"stale" for opencode rows (poller-driven heartbeat; stale means *    the hosting harness has missed two beats and is presumed gone)
- *  - "active"/"idle" for MCP rows (turn-driven; idle between prompts is the
- *    NORMAL state, so an idle MCP row is reachable, not dead)
- *  Heartbeat age is the only signal on purpose. A 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.
- *  One clock, one rule. */
-export function chatLiveness(row: ChatSessionRow, now = Date.now()): "fresh" | "stale" | "active" | "idle" {
+/** The liveness verdict for one roster row, from heartbeat age plus (for
+ *  opencode rows) the open-tab set:
+ *  - "open" - fresh heartbeat AND a tab is open now (session presence)
+ *  - "recent" - fresh heartbeat, no known tab: an instance that saw this
+ *    session is alive and beating it, but the session itself may or may
+ *    not be wakeable (a closed tab's wake can be swallowed; a daemon-
+ *    resident subordinate runs headless and may still pick up mail)
+ *  - "stale" - the hosting harness has missed two beats and is presumed
+ *    gone
+ *  - "active"/"idle" for MCP rows (turn-driven; idle between prompts is
+ *    the NORMAL state, so an idle MCP row is reachable, not dead)
+ *  Heartbeat age alone decides staleness - a 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.
+ *  The tab set is a READ-ONLY refinement (src/tab-state.ts) consumed at
+ *  render/broadcast time; omitting it degrades every fresh opencode row
+ *  to "recent" - honest, never a false "open". */
+export function chatLiveness(row: ChatSessionRow, now = Date.now(), openTabs?: ReadonlySet<string>): "open" | "recent" | "stale" | "active" | "idle" {
   const stale = isStale(row, now);
   if (row.host_kind === "mcp") return stale ? "idle" : "active";
-  return stale ? "stale" : "fresh";
+  if (stale) return "stale";
+  return openTabs?.has(row.session_id) ? "open" : "recent";
 }
 
 /** Orders roster rows for display: project first (so a shared-tree reader
@@ -379,31 +389,41 @@ export function sortChatRoster(rows: ChatSessionRow[]): ChatSessionRow[] {
   });
 }
 
-/** Splits the roster for the two-section display: Active (wake-able or
- *  reachable - fresh opencode rows and every MCP row, which read mail at
- *  their next prompt) and Stale (opencode rows whose harness has stopped
- *  reporting; mail to them waits until they resume).
+/** Splits the roster for the three-section display: Active (wakeable or
+ *  reachable - opencode rows with an open tab, plus every MCP row, which
+ *  read mail at their next prompt), Recent (fresh opencode rows with no
+ *  open tab: the harness is alive and beating, but a wake may not reach
+ *  the session until its tab reopens - headless subordinates may still
+ *  read mail on their own turns), and Stale (opencode rows whose harness
+ *  has stopped reporting; mail to them waits until they resume).
+ *  openTabs refines fresh opencode rows into open versus recent; when
+ *  omitted every fresh opencode row degrades to recent, never a false
+ *  open (chatLiveness's rule).
  *  staleCapMs bounds how old a stale row the roster displays, so
  *  long-dead sessions cannot bury the fresh signal; hidden rows come
  *  back only as the staleHidden count, so the CLI can say what it left
  *  out. null (the default) shows every stale row - the tool surface has
  *  no cap, only the CLI applies one. */
-export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null): { active: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
+export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null, openTabs?: ReadonlySet<string>): { active: ChatSessionRow[]; recent: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
   const active: ChatSessionRow[] = [];
+  const recent: ChatSessionRow[] = [];
   const stale: ChatSessionRow[] = [];
   let staleHidden = 0;
   for (const row of rows) {
-    if (chatLiveness(row, now) === "stale") {
+    const verdict = chatLiveness(row, now, openTabs);
+    if (verdict === "stale") {
       if (staleCapMs !== null && now - Date.parse(row.last_seen) > staleCapMs) {
         staleHidden++;
       } else {
         stale.push(row);
       }
+    } else if (verdict === "recent") {
+      recent.push(row);
     } else {
       active.push(row);
     }
   }
-  return { active, stale, staleHidden };
+  return { active, recent, stale, staleHidden };
 }
 
 /**
@@ -858,10 +878,16 @@ export class ChatStore {
   }
 
   /**
-   * Posts a message to every other registered session at once. Stale
-   * sessions are skipped, not messaged - a host process that has stopped
-   * heartbeat-ing will never read the mail, and a broadcast is for reaching
-   * live agents. Each recipient gets its own inbox row per part, so the
+   * Posts a message to every other registered session at once. Opencode
+   * rows are skipped unless they are OPEN - a fresh heartbeat AND a tab
+   * open right now. Both skip classes are honest: a STALE row's host
+   * process has stopped heartbeat-ing and will never read the mail, and a
+   * RECENT row (fresh heartbeat, no open tab) is not reliably wakeable -
+   * the wake can be swallowed without a tab to receive it, so the fan-out
+   * would spend a model turn on a delivery that likely never runs. MCP
+   * rows always receive (they read mail at their next prompt). Every skip
+   * is listed by name in `skipped` so the caller can see who was left
+   * out and why. Each recipient gets its own inbox row per part, so the
    * existing wake machinery (grouping, gating, rate cap) treats the
    * broadcast as ordinary per-recipient mail. An oversized body is
    * auto-split (splitChatBody) and every recipient gets every part inside
@@ -871,6 +897,7 @@ export class ChatStore {
   broadcast(
     fromSession: string,
     body: string,
+    openTabs?: ReadonlySet<string>,
   ): { ok: true; recipients: string[]; skipped: string[]; deduped: number; parts: number } | { ok: false; error: string } {
     const trimmed = body.trim();
     if (!trimmed) return { ok: false, error: `Message body cannot be empty (attempted ${body.length} characters).` };
@@ -885,6 +912,9 @@ export class ChatStore {
       };
     }
     const parts = splitChatBody(trimmed);
+    // No provider = no tab signal: every fresh opencode row degrades to
+    // RECENT (honest - an unknown tab state never reads as open).
+    const open = openTabs ?? new Set<string>();
     const recipients: string[] = [];
     const skipped: string[] = [];
     let deduped = 0;
@@ -894,10 +924,12 @@ export class ChatStore {
     this.#db.transaction(() => {
       for (const row of this.list()) {
         if (row.session_id === fromSession) continue;
-        // Staleness means "host process gone" only for opencode rows; an
-        // mcp row between turns reads its mail at the next prompt, so it
+        // Two honest skip classes for opencode rows: STALE (host process
+        // gone - never reads the mail) and RECENT (fresh heartbeat, no
+        // open tab - the wake is not guaranteed to run a turn). An mcp
+        // row between turns reads its mail at the next prompt, so it
         // always receives.
-        if (row.host_kind === "opencode" && isStale(row)) {
+        if (row.host_kind === "opencode" && (isStale(row) || !open.has(row.session_id))) {
           skipped.push(row.name);
           continue;
         }

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,26 @@ 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, Clarity, Technique, and Breadcrumbs findings outrank same-severity findings from the other lenses. AI-writing tells, unclear prose, 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",
@@ -154,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}
 
@@ -172,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}
 
@@ -181,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 {
@@ -221,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

@@ -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();
   }
 
@@ -1086,7 +1092,22 @@ export class ThatchDB {
   }
 
   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) {

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";
@@ -136,7 +137,7 @@ 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 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
@@ -173,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
@@ -478,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

@@ -20,7 +20,7 @@
 // peer).
 
 import { Plugin } from "@opencode/plugin/tui";
-import { isTabClosedEvent, isTabOpenedEvent, passesDirectoryGuard } from "../session-tab-shared";
+import { isExitTabClosedEvent, isTabClosedEvent, isTabOpenedEvent, isToastEvent, passesDirectoryGuard } from "../session-tab-shared";
 
 export default Plugin.define({
   id: "jeffober-thatch-tui",
@@ -28,16 +28,19 @@ export default Plugin.define({
     const off = context.data.listen(({ details }) => {
       const windowDirectory = context.location?.directory ?? context.data.location.default().directory;
       if (!passesDirectoryGuard(details.location?.directory, windowDirectory)) return;
-      if (isTabClosedEvent(details.type)) {
-        // A tool-initiated close request: 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.
+      // 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-closed event without a sessionID");
+          console.error("[thatch] tab-close event without a sessionID");
           return;
         }
         if (!context.ui.tabs.close(closeID)) {
@@ -45,6 +48,23 @@ export default Plugin.define({
         }
         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) {