@jeffober/thatch 0.2.5 → 0.2.7

package/artifacts/skills/thatch-review-context.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-review-context
-description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, linked docs/tickets, docs, and memory to build a context brief that prevents false positives about intentionally deferred work. Use before dispatching review specialists or running a solo review.
+description: Gather project and feature context before a code review. Investigates PR descriptions, git history, ticket references, linked docs/tickets, docs, memory, and related PRs (stack members, release trains) to build a context brief that prevents false positives about intentionally deferred work and about pieces delivered by sibling PRs. Use before dispatching review specialists or running a solo review.
 ---
 
 You are a review context builder. Your job is to gather project context that gives reviewers the background they need to avoid false positives about intentionally deferred work, incomplete features, and multi-ticket dependencies.
@@ -85,7 +85,7 @@ If the matching CLI tool (`gh`, `glab`, etc.) is not on PATH and you cannot call
 #### Detect the connected PR/MR
 
 Use the current branch name (without remote or merge-base prefix) to look up an open PR/MR:
-- **GitHub**: `gh pr view --head <branch> --json number,title,state,headRefName,baseRefName,headRefOid,baseRefOid`. Fallback: `gh api repos/{owner}/{repo}/pulls --jq ".[] | select(.head.ref==\"<branch>\")"`.
+- **GitHub**: `gh pr view <branch> --json number,title,state,headRefName,baseRefName,headRefOid,baseRefOid`. Fallback: `gh api repos/{owner}/{repo}/pulls --jq ".[] | select(.head.ref==\"<branch>\")"`.
 - **GitLab**: `glab mr list --source-branch <branch>`.
 - **Bitbucket Cloud**: REST `https://api.bitbucket.org/2.0/repositories/<owner>/<slug>/pullrequests?q=source.branch.name="<branch>"` (no widely-adopted CLI; call via available HTTP tool).
 - **Azure DevOps**: `az repos pr list --source-branch <branch> --org <org-url> -r <project>`.
@@ -132,6 +132,46 @@ Directory structure conventions are often undocumented. They live in the repo's
 
 This gives the pedantic specialist the structural context without having to discover the pattern independently.
 
+### 11. Related PRs: stacks and release trains
+
+A change is often one piece of a coordinated set of PRs. The other pieces are outside this diff, so specialists cannot see them. Two false-positive patterns result: a comment references work that a sibling PR delivers, or the change consumes a contract that a sibling PR defines. Discover the set and record what each piece does.
+
+Two shapes to look for:
+- **Stack**: PRs that merge into each other. This PR's base branch is another PR's head branch.
+- **Release train**: PRs that all target the main branch but must merge or deploy in a specific order. The order lives in tracker relations or ticket DEPENDENCIES sections (the ticket section that names the change's blocking links; the links carry the ordering, the bullets carry only the rationale), not in the branch structure.
+
+#### Discovery
+
+- **Stack chaining**: if the connected PR's base branch is not the main branch, another PR probably owns that branch as its head. Find it (`gh pr view <base-branch>` on GitHub, `glab mr list --source-branch <base-branch>` on GitLab), then repeat from that PR until the chain reaches the main branch. Walk at most 5 links in each direction; record deeper stack members as `unexplored` register entries. Also look downward: `gh pr list --base <this-branch>` (GitHub) or `glab mr list --target-branch <this-branch>` (GitLab) finds PRs stacked on top of this one.
+- **Tracker relations**: tickets surfaced by the earlier sources carry blockedBy/blocks relations, parent epics, and DEPENDENCIES sections that name the ordered set. Stack chaining cannot find a release train, because every PR in a train targets main; this route is the primary way trains surface. Map each ticket in the set to its PR/MR (`gh pr list --search "TICKET-ID"` on GitHub, or the tracker's attached-PR link); a ticket with no open PR stays a dependency recorded in the brief's Dependencies section, not a register entry.
+- **Linked PRs** from sources 1 and 8. Deduplicate against the two methods above.
+
+A sibling that already merged to main is also covered by the staleness check (source 3). Record it in the register anyway, for context.
+
+#### Build the sibling register
+
+For each sibling PR/MR:
+- PR/MR number, title, state (open/merged/closed/draft)
+- Its base branch, and for stacks its position in the chain
+- One line: what it implements, from its description and diff stat
+
+This field list is canonical: the brief section below and the synthesizer's Cross-PR notes appendix render the register as built here. An `unexplored` entry (a stack member beyond the walk cap) carries the number, title, state, base branch, and chain position, but no what-it-implements line and no consistency verdicts; the sibling's description and diff were not read.
+
+#### Targeted consistency verification
+
+Read every sibling's description in full. Open a sibling's diff only to verify the specific contracts, symbols, and references this change consumes or mentions. Never run a full second review of a sibling. Checks:
+
+1. **Contract check**: an API, type, schema, config key, or flag this change consumes from a sibling matches the sibling's actual implementation at its head SHA.
+2. **Reference check**: a comment or doc in this change references a thing X. X exists in this change or in a sibling. If neither delivers X, the reference is dangling.
+3. **Ordering check**: the change or its ticket claims a merge or release order for the set. Verify the claim is stated and consistent with the stack chain or the tracker relations.
+4. **Overlap check**: two PRs in the set implement the same thing differently.
+
+Tag each check that applied: `consistent`, `inconsistent` (with the evidence), or `unclear`.
+
+#### Early-out
+
+If the discovery routes above surfaced no related PR/MR and no coordinated ticket set, state `Standalone change — no sibling register` and skip this source. A coordinated ticket set with no open PRs is not standalone: record it under Dependencies. Most personal projects land here; the source costs one look.
+
 ## Context brief format
 
 Produce a structured brief:
@@ -154,6 +194,7 @@ List each deferred piece:
 - What other tickets or PRs this depends on (must merge first)
 - What tickets or PRs depend on this (are blocked by it)
 - Whether base branches have landed (for stacked PRs)
+- **Release order**: when a ticket or the PR description claims a merge or deploy order for a set of changes, record the claimed order and where it is claimed (which ticket's DEPENDENCIES section, which tracker relation, or which PR description)
 - **Staleness**: whether main has moved past the merge-base since the branch point. When the staleness check (source 3) found commits touching this change's paths, list them here — the synthesizer re-verifies behavioral findings against current main before classifying them
 
 ### Relevant constraints
@@ -175,6 +216,18 @@ If context gathering found a connected PR/MR but no prior reviews by other users
 
 If context gathering found no connected PR/MR (local-branch review), state `Local-branch review — no prior-comment fetch`. This is not a gap; the existing review procedure applies.
 
+### Sibling PR context (only when related PRs were detected)
+
+List the sibling register as built above (one entry per sibling):
+- PR/MR number, title, state, base branch, and for stacks the chain position
+- What it implements (one line)
+- Consistency verdicts from the targeted checks (`consistent` / `inconsistent` with evidence / `unclear`), only for the checks that applied
+- An `unexplored` entry renders its fields only; the missing what-it-implements line and verdicts record the walk cap, not a gap
+
+Whether base branches have landed is recorded under Dependencies above, not here.
+
+If discovery found no related PRs and no coordinated ticket set, state `Standalone change — no sibling register`. This is not a gap; the change is not part of a coordinated set. A coordinated ticket set with no open PRs is not standalone: its claimed order is recorded under Dependencies.
+
 ## If context is sparse
 
 Not every PR will have rich context. If you find minimal context:

package/artifacts/skills/thatch-review-followup.md

@@ -30,7 +30,7 @@ Run `git fetch origin` (NOT `git pull`). Inspect `git remote -v` to recognize th
 - `dev.azure.com` → Azure DevOps
 
 Probe for an open PR/MR on the current branch:
-- **GitHub**: `gh pr view --head <branch> --json number,title,headRefOid,baseRefOid`
+- **GitHub**: `gh pr view <branch> --json number,title,headRefOid,baseRefOid,baseRefName`
 - **GitLab**: `glab mr list --source-branch <branch>`
 
 If no PR/MR is found or no VCS CLI is available, you cannot re-check. Report this and stop.
@@ -79,7 +79,7 @@ Compare `LAST_ROUND_SHA` to `CURRENT_SHA`:
 
 **Force-push check**: run `git merge-base --is-ancestor <LAST_ROUND_SHA> <CURRENT_SHA>`. If it fails, the author rewrote history (force-pushed). Line numbers may have drifted. You will need to locate each finding's equivalent location in the new HEAD by matching surrounding context, not by line number.
 
-**Merge-from-main check**: if the author merged main into the branch between rounds, plain `git log <LAST_ROUND_SHA>..<CURRENT_SHA>` and `git diff <LAST_ROUND_SHA> <CURRENT_SHA>` both pull in every main commit, burying the author's actual response commits. To see only the author's commits, run `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/main` after `git fetch origin`. Then read each remaining commit's diff with `git show <sha>`. Do not assume a large diff stat means the author rewrote the PR. Check for a merge commit first.
+**Merge-from-base check**: if the author merged the default branch into the branch between rounds — or, on a stacked PR, merged or rebased onto the PR's base branch — plain `git log <LAST_ROUND_SHA>..<CURRENT_SHA>` and `git diff <LAST_ROUND_SHA> <CURRENT_SHA>` both pull in every base commit, burying the author's actual response commits. To see only the author's commits, run `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/<default-branch>` after `git fetch origin` (usually main or master). On a stacked PR (Step 1's probe returned a base branch that is not the default branch — `baseRefName` on GitHub, the MR's target branch on GitLab), also fetch the base branch and exclude it too: `git fetch origin <base-branch>`, then `git log <LAST_ROUND_SHA>..<CURRENT_SHA> --not origin/<default-branch> origin/<base-branch>`. Then read each remaining commit's diff with `git show <sha>`. Do not assume a large diff stat means the author rewrote the PR. Check for a merge commit first.
 
 ### Read author responses
 
@@ -152,7 +152,7 @@ Produce a structured report for the user:
 - PR/MR number, title
 - Last-reviewed SHA, current SHA
 - Whether the author pushed changes, responded to comments, or both
-- Force-push or merge-from-main detected (if applicable)
+- Force-push or merge-from-base detected (if applicable)
 
 ### Finding verification
 
@@ -275,7 +275,7 @@ After all findings have been dealt with (adequately addressed and replied to, or
 ### How to offer
 
 Present the offer as a choice:
-1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all eight specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
+1. **Re-run the full structured review**: load `thatch-code-review` on the current HEAD. It will dispatch all ten specialists on the merge-base..HEAD range. The existing follow-up detection will cross-reference your prior comments. On Claude Code or Cursor (no sub-agent support), run each specialist skill in sequence, then run `thatch-review-synthesizer` to aggregate.
 2. **End the re-review here**: the user confirmed their concerns were addressed (or decided how to handle the unaddressed ones) and does not want another full round.
 
 The offer is just an offer. The user may decline. They may have only wanted to confirm their concerns were addressed.

package/artifacts/skills/thatch-review-response.md

@@ -80,7 +80,7 @@ Identify the PR and VCS host:
   recognize the VCS host: `github.com` -> GitHub (`gh`), `gitlab.*` ->
   GitLab (`glab`), `bitbucket.org` -> Bitbucket Cloud, `dev.azure.com` ->
   Azure DevOps.
-- Probe for an open PR on the current branch: `gh pr view --head <branch>
+- Probe for an open PR on the current branch: `gh pr view <branch>
   --json number,title,headRefOid` (GitHub) or equivalent.
 
 Fetch ALL review comments:

package/artifacts/skills/thatch-review-synthesizer.md

@@ -1,9 +1,9 @@
 ---
 name: thatch-review-synthesizer
-description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
+description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Cross-references prior review comments and sibling PR registers when provided. Use after running one or more thatch-review-* specialist skills.
 ---
 
-You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, economy, no-slop, clarity, breadcrumbs, mark-and-sweep, highlights, technique). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
 
 ## Static analysis only
 You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
@@ -95,6 +95,14 @@ New findings that match a prior comment tagged `addressed` (preliminary) are sti
 
 When the VCS resolve flag (GitLab `resolved`, GitHub `isResolved`) disagrees with the code-state verdict (e.g., thread marked resolved in the UI but the bug persists), trust the code state and call out the disagreement in the appendix entry.
 
+## Cross-reference against the sibling PR register
+
+If your input includes a **sibling register** (built via `thatch-review-context` source #11 — related PRs detected as stack members or release-train siblings), apply it during classification, before finalizing any finding whose claim crosses PR boundaries.
+
+- A finding claiming a referenced thing is **missing** ("comments reference X but nothing implements X", "flagged as unused or undefined") is REJECTED — or moved to the Cross-PR notes appendix as a stack note — when the register shows a sibling PR delivers it. Cite the sibling PR and its register entry as the reason.
+- A finding that this change **consumes a contract a sibling does not actually provide** (shape mismatch, renamed symbol, different semantics at the sibling's head) is CONFIRMED, with the `Provenance` field citing the sibling PR.
+- A problem discovered **in the sibling itself** is not a finding of this review by default. Record it in the Cross-PR notes appendix so it can be raised in the sibling's own review. Escalate it to a finding of THIS review only when the inconsistency affects this change's safety or correctness, or when flagging it now heads off a bug the author will hit in imminent follow-up work in the same project.
+
 ## Severity calibration
 
 Assign final severity based on YOUR verification:
@@ -323,6 +331,18 @@ List every entry from the prior-comments register here. For each entry, produce
 
 If no prior-comments register was provided (local-branch review or first round on the PR/MR), state `None — no prior review comments to cross-reference` and move on.
 
+### Cross-PR notes (appendix — only when a sibling register was provided)
+
+List every sibling in the register here. For each sibling, produce a one-block record:
+1. **PR/MR number, title, state, base branch**, and for stacks its position in the chain
+2. **What it implements** (one line from the register)
+3. **Consistency verdicts**: `consistent` / `inconsistent` (with the evidence) / `unclear`, per targeted check that applied
+4. **Notes for the sibling's own review**: problems discovered in the sibling that belong in its review, not this one
+
+An `unexplored` entry renders item 1's fields and states `unexplored — not read` for items 2 and 3.
+
+Omit this section entirely when no sibling register was provided (standalone change or local-branch review).
+
 ### Coverage gaps
 
 Note which files or areas were NOT covered by any specialist.

package/bin/thatch

@@ -13,17 +13,30 @@ 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 [command, ...args] = process.argv.slice(2);
+const argv = process.argv.slice(2);
 
-function usage(): never {
+// Help is checked before the DB is opened or any subcommand runs, and
+// against the WHOLE argument list - not just the leading flags - so
+// `thatch chat list -h` and `thatch -h chat list` print usage instead of
+// executing. Asking for help is not an error: exit 0, where a bad
+// command still exits 1.
+if (argv.includes("-h") || argv.includes("--help")) usage(0);
+
+const [command, ...args] = argv;
+
+const db: ThatchDB = new ThatchDB(dbPath, { chatOpenTabs: chatOpenTabsProvider(() => db.chatTabClosures()) });
+
+function usage(exitCode = 1): never {
   console.error(`USAGE
   thatch --version, -v             Print version and exit
+  thatch -h, --help                Print this usage and exit (the flag
+                                    works anywhere in the command line)
   thatch stores                    List all stores
   thatch list   [store]            List memory labels in a store  
   thatch show   <label> [store]    Display a memory by label
@@ -51,13 +64,16 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
-  thatch chat list [--stale N|all]  Registered chat sessions. Default shows
-                                    only active (fresh-heartbeat) sessions:
-                                    name, session id, age, status, project,
-                                    topic. --stale adds the stale section:
-                                    N bounds it to sessions seen in the
-                                    last N days (default 1); all shows
-                                    every stale session.
+  thatch chat list [--recent] [--stale N|all]
+                                    Registered chat sessions. Default shows
+                                    only open sessions (plus MCP rows, which
+                                    read mail at their next prompt): name,
+                                    session id, age, status, project, topic.
+                                    Tab-less fresh sessions collapse into a
+                                    hidden-count note; --recent shows them.
+                                    --stale adds the stale section: N bounds
+                                    it to sessions seen in the last N days
+                                    (default 1); all shows every stale one.
   thatch chat tail [--once] [--limit N|all] [--match RE]
                    [--from NAME] [--to NAME] [--since DT] [--until DT]
                                    Follow cross-session chat as a JSONL
@@ -74,7 +90,7 @@ function usage(): never {
 
 Stores default to the repo detected from git remote. Use "global" for the
 global store. Use "all" with search to search project + global together.`);
-  process.exit(1);
+  process.exit(exitCode);
 }
 
 async function defaultStore(): Promise<string> {
@@ -424,27 +440,42 @@ async function sessionCommand(rest: string[]): Promise<void> {
 const CHAT_ROSTER_HEADER = ["NAME", "SESSION ID", "AGE", "STATUS", "PROJECT", "TOPIC"];
 
 /**
- * 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.
+ * Renders the `chat list` roster as three sections - Active, Recent, and
+ * Stale - each an aligned-column table under a header row. Section headers
+ * are bold, the Recent and Stale explainers are muted italic; rows use
+ * green names, dim age, green/yellow/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).
+ * showRecent = false (the CLI default without `--recent`) collapses the
+ * Recent section into a muted hidden-count note pointing at the flag.
+ * Unlike the Stale hide - which the caller does by pre-filtering rows
+ * before this function, dropping them silently - the recent hide needs
+ * the rows in hand to count them, so it happens here as a note. An
+ * all-recent roster therefore renders the note alone, with no section
+ * header: there is no Recent section on the page to head, while the
+ * stale hidden note rides under a header because its section IS
+ * displayed;
  * 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.
+ * now is the render's single clock sample: the split, every per-row
+ * verdict, and the caller's pre-filter must agree, or a row aging past
+ * the staleness boundary mid-render could land in two sections at once.
  * Color is applied only when stdout is an interactive terminal (and
  * 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>, showRecent = true, now = Date.now()): 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);
+  const { active, recent, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), now, staleCapMs, openTabs);
   const renderTable = (rows: ChatSessionRow[]) => {
     const cells = (r: ChatSessionRow) => [
       r.name,
       r.session_id,
       humanAge(r.last_seen),
-      chatLiveness(r),
+      chatLiveness(r, now, openTabs),
       r.project ?? "unknown",
       r.topic ?? "",
     ];
@@ -455,11 +486,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();
@@ -470,6 +504,20 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
   if (active.length > 0) {
     parts.push([paint("1", "# Active Sessions"), renderTable(active)].join("\n"));
   }
+  if (recent.length > 0) {
+    if (showRecent) {
+      const explainer = "These sessions have a fresh heartbeat but no open tab, so a wake may not reach them until their tab reopens; headless subordinates may still read mail on their own turns.";
+      parts.push([paint("1", "# Recent Sessions"), paint("3;90", explainer), renderTable(recent)].join("\n"));
+    } else {
+      // Bare note, no section header: there is no Recent section on the
+      // page, so a header would announce a section the view does not
+      // render. The stale hidden note rides under a header because with
+      // --stale its section IS rendered.
+      parts.push(
+        paint("3;90", `${recent.length} recent session${recent.length === 1 ? "" : "s"} hidden (alive, no open tab); --recent to show`),
+      );
+    }
+  }
   if (stale.length > 0 || staleHidden > 0) {
     const lines = [paint("1", "# Stale Sessions")];
     if (stale.length > 0) {
@@ -499,13 +547,24 @@ async function chatCommand(rest: string[]): Promise<void> {
       // sessions from burying the fresh signal. --stale all restores the
       // unbounded view. A bad value dies loudly rather than silently
       // shrinking the roster.
-      // Default: active sessions only. --stale [N|all] opts into the
-      // stale section - bare --stale keeps the one-day display cap, N
-      // bounds it, all removes it. The value is parsed by hand (not
-      // flagValue) because bare --stale is meaningful.
+      // Default: open sessions only (plus MCP rows, which read mail at
+      // their next prompt - "open" is meaningless for them). --recent
+      // opts into the Recent section (alive, no open tab). The two hidden
+      // defaults work differently: --recent's leaves a muted count note
+      // in the renderer (it needs the rows in hand to count them);
+      // --stale's drops the rows silently in the pre-filter below, and
+      // only the empty-roster message points at the flag. Unlike --stale
+      // it takes no window value: recent rows are bounded by the heartbeat
+      // window itself, so there is nothing to cap. The value is parsed by
+      // hand (not flagValue) because bare --stale is meaningful.
+      const showRecent = restArgs.includes("--recent");
       const showStale = restArgs.includes("--stale");
       const staleIdx = restArgs.indexOf("--stale");
-      const staleNext = showStale ? restArgs[staleIdx + 1] : undefined;
+      const rawNext = showStale ? restArgs[staleIdx + 1] : undefined;
+      // A token starting with "--" is a sibling flag (e.g. "--stale
+      // --recent"), not --stale's value: --stale stays bare instead of
+      // eating the flag.
+      const staleNext = rawNext !== undefined && rawNext.startsWith("--") ? undefined : rawNext;
       let staleCapMs: number | null = 24 * 60 * 60 * 1000;
       if (staleNext !== undefined) {
         if (staleNext === "all") staleCapMs = null;
@@ -514,17 +573,28 @@ async function chatCommand(rest: string[]): Promise<void> {
           process.exit(1);
         } else staleCapMs = Number(staleNext) * 24 * 60 * 60 * 1000;
       }
-      let sessions = db.listChatSessions();
-      if (!showStale) sessions = sessions.filter((r) => chatLiveness(r) === "fresh");
+      // 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())();
+      // One clock sample per render: the pre-filter, the split, and every
+      // per-row verdict must agree, or a row aging past the staleness
+      // boundary mid-render could land in two sections at once.
+      const now = Date.now();
+      const registered = db.listChatSessions();
+      // Stale rows are hidden here (not in the renderer) so the
+      // emptiness check can tell an empty directory from a stale-only
+      // one; recent rows are left in because formatChatRoster needs them
+      // to render the hidden-count note.
+      const sessions = registered.filter((r) => showStale || chatLiveness(r, now, openTabs) !== "stale");
       if (sessions.length === 0) {
         console.log(
-          showStale
+          registered.length === 0
             ? "No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register."
             : "No active sessions. (Stale sessions are hidden; run with --stale to include them.)",
         );
         break;
       }
-      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null));
+      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null, openTabs, showRecent, now));
       break;
     }
 
@@ -1050,7 +1120,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 +1214,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 +1366,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

@@ -27,7 +27,13 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 
 ## Global behavior
 
-- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- `--version` and `-v` print the package version and exit 0.
+- `-h` and `--help` print usage and exit 0. The check runs before the DB
+  is opened and before any subcommand dispatch, and scans the WHOLE
+  argument list - not just the leading flags - so `thatch chat list -h`
+  and `thatch -h chat list` show usage instead of executing. Explicit
+  help exits 0 where a usage error exits 1.
+- No other short flags. No subcommand aliases.
 - Unknown command or missing required arg calls `usage()` and exits 1.
 - Args are positional, parsed by hand from `process.argv.slice(2)`. No arg-parsing library.
 - DB opened once at startup, closed at end (except `mcp` which closes early).
@@ -47,11 +53,21 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 Read-only window on the cross-session chat directory ([cross-session-chat.md](cross-session-chat.md)):
 
 - `chat list` renders the roster as aligned columns under a header row
-  (NAME/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout is a TTY
-  (`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).
+  (NAME/SESSION ID/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout
+  is a TTY (`formatChatRoster()` in `bin/thatch`; pipes and QA runners
+  get plain text). Rows are split into Active, Recent, and Stale
+  sections by `splitChatRoster()` (it takes the open-tab set, so fresh
+  opencode rows split into open versus recent); the status column is
+  `chatLiveness()`'s verdict
+  (`open`/`recent`/`stale` for opencode rows - the open-tab reader feeds
+  the open/recent split - `active`/`idle` for MCP rows). The Recent and
+  Stale sections are flag-guarded, and the two guards hide differently:
+  without `--recent` the Recent section is replaced by a muted
+  hidden-count note (the renderer keeps the rows to count them), while
+  without `--stale` stale rows are dropped entirely by a pre-filter in
+  the command case - only the empty-roster message points at the flag.
+  `--stale [N|all]` reveals the stale rows under a one-day display cap
+  whose overflow collapses into a hidden-count note.
 - `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
@@ -113,7 +129,7 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 ## Key invariants
 
 - No arg-parsing library. Args are positional, parsed by hand from `process.argv.slice(2)`.
-- No `--version`, `--help`, `-h`, or short flags. No subcommand aliases.
+- `--version`/`-v` prints the version; `-h`/`--help` prints usage from anywhere in the argument list (checked upstream of dispatch, before the DB opens) and exits 0. No other short flags. No subcommand aliases.
 - DB opened once at startup, closed at end (except `mcp` which closes early).
 - Store name auto-detected from git remote. "global" is the shared store. "all" (search only) means project + global.
 - Unknown command or missing required arg calls `usage()` and exits 1.