@jeffober/thatch 0.2.4 → 0.2.6

package/docs/dev/gotchas.md

@@ -160,6 +160,12 @@ here first. These are the things that have already cost time.
 - **`bun test` does not typecheck**, and `tsconfig.json` excludes `tests`. Test
   type errors are editor-only noise unless you run `tsc` on the test files
   directly. Keep test files type-clean anyway so the editor stays quiet.
+- **`mise run test` (bare `bun test`) also executes the QA barrels**
+  (`tests/qa/*/index.test.ts`), which spawn REAL opencode sessions and spend
+  model tokens, one use case at a time - a full run can hang for many minutes.
+  The unit gate is `mise run check` (`bun test tests/*.test.ts`); QA runs
+  belong to the `mise run qa-auto` / `qa-live` tasks, which select a UC
+  subset by name.
 
 ## Config and notifications
 
@@ -293,3 +299,86 @@ instead of throwing "Cannot use a closed database". Two rules keep this intact:
   renderer quotes every description (`yamlQuote` in src/commands.ts) and a
   unit test pins the quoted form. Keep it that way for any new frontmatter
   field whose value is free-form prose.
+
+## In-memory maps gate nothing durable: reloads and restarts wipe them
+
+- **Any guard whose correctness depends on a runtime.ts Map silently
+  disappears for sessions whose events arrive after a plugin reload or a
+  daemon restart.** The chat auto-registration child check learned this the
+  hard way: `childToParent` kept extraction children out of the roster, but
+  an instance that lost the map to a reload registered every event-bearing
+  child, and v2 cannot delete sessions (sessionDelete is a no-op), so the
+  poller heartbeat those corpse rows forever and the stale-row reaper never
+  reaped them (81 `thatch-extraction` rows by 2026-10-07). The fix pattern:
+  the plugin writes a DURABLE marker at creation time
+  (`chat_machinery`, src/db.ts), and every registration path checks the
+  marker plus a stable title (`isMachinerySessionTitle`) instead of
+  trusting in-memory state alone. If you add a new plugin-created session
+  kind, mark it in the same table and route its events through the same
+  guards - do not rely on Maps surviving a reload.
+
+## A running TUI never adopts a NEW ./tui plugin entrypoint - restart the TUI
+
+- **The v2 TUI discovers its CLI plugins at process startup only.** The
+  server side hot-reloads plugin code (the digest watcher), and the TUI
+  hot-reloads the SOURCE of plugins it already loaded - but a plugin that
+  GAINS a `./tui` entrypoint (or a fresh install of one) is a discovery-
+  level change: a TUI process started before the entrypoint existed never
+  loads it. Symptom (2026-10-08, the thog TUI): `thatch_session_tab` ran
+  fine server-side (the session, the chat registration, the response all
+  real) but the tab never appeared in the strip - the TUI had no
+  `ui.tabs` consumer loaded, so the rpc event landed nowhere. The
+  persisted `tabs.json` (in `$XDG_STATE_HOME/opencode/<channel>/tui/`)
+  proved the registration logic was correct the whole time: a FRESH TUI
+  (the docker sandbox attach) showed the tab immediately.
+- **Fix**: convert the install to the directory shim (docs/user/setup.md),
+  THEN restart the TUI. A restart ALONE fixes nothing when the install is
+  a FILE shim - the file shape never loads a `./tui` entrypoint, whatever
+  the process age. First diagnostic: `ls ~/.config/opencode/plugins/` -
+  a FILE (`thatch.ts`) means no TUI consumer has ever loaded there,
+  restart or not; the directory form (`thatch/index.ts` + `tui.ts`) is
+  required. (2026-10-08, the thog TUI: the restart-and-respawn test
+  DISPROVED the stale-process theory and pointed here - the conversion
+  was the missing install step.)
+- **Fix**: restart the TUI window once after adopting (or changing the
+  shape of) a `./tui` entrypoint. DIAGNOSTIC WARNING: `tabs.json` cannot
+  discriminate here - it is SHARED across windows and written by ANY tab
+  open, manual (a picker navigation) or event-driven - an entry for the
+  session proves only that SOMETHING opened it, not that the spawn-time
+  event worked. The discriminating test: restart the TUI and re-spawn; a
+  tab appearing post-restart confirms the stale-process diagnosis; a tab
+  still absent is a real bug worth a report.
+
+## The two opencode lines discover plugins differently: no one shim shape auto-loads on both
+
+- **v1 auto-discovers plugin FILES only** - its config plugin scan globs
+  `{plugin,plugins}/*.{ts,js}`, which never matches a directory. **v2
+  auto-discovers files AND directories** (and symlinks), and its activation
+  dies on duplicate ids - so a plugins directory holding BOTH `thatch.ts`
+  and `thatch/` loads the server plugin twice on v2 and dies with
+  "duplicate instance plugin ids" before any plugin code runs. There is no
+  single on-disk shape that auto-loads on both lines as a directory-based
+  multi-entry plugin. Consequences: the dev-checkout install uses the file
+  shim for v1-only or v2-only use, or the directory shim for v2's `./tui`
+  entrypoint (session tabs) - deleting the file shim in the same step; the
+  QA fixture keeps the FILE shim because the QA suite is headless (no TUI
+  process ever loads `./tui`, and the file shape is the only one that loads
+  on both lines - a directory shim deterministically killed UC-100's v1
+  chat canary). Local plugin specs handed to a loader explicitly
+  (`"plugin": ["./path"]`) can point at a directory on v1 - it is only the
+  AUTO-discovery scan that is files-only.
+
+## A promptSession wrapper must stay synchronous or fire-and-forget delivery assertions misfire
+
+- **Symptom**: tests that assert on wake delivery immediately after a hook
+  invocation see zero calls; deliveries land one microtask late.
+- **Cause**: the delivery guard (`guardDelivery`, src/runtime.ts) sits on
+  every wake path, and its directory-existence check was first written as
+  `await stat(...)`. Fire-and-forget callers (`void caps.promptSession(...)`)
+  and the repo's mock contract (calls recorded "synchronously inside the
+  mock", asserted with no intervening await) observe the wrapped call
+  before an extra microtask resolves.
+- **Fix**: the existence check is synchronous (`existsSync`), so the guard
+  adds no microtask between the gate and the wrapped call. If you ever
+  replace it with an async check, the callers' fire-and-forget timing -
+  and the tests that pin it - break again. (2026-10-12, wake-delivery-guard)

package/docs/dev/mcp-parity.md

@@ -18,20 +18,20 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR, branch, and command watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel. The `chat_*` tools (cross-session chat) are opencode-only — no host session identity and no wake-up channel |
+| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only and v2-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only and v2-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR, branch, and command watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel. The `chat_*` tools (cross-session chat) are opencode-only — no host session identity and no wake-up channel. `session_tab` and `session_tab_close` are v2-opencode-only — they drive TUI session tabs over the v2 rpc-event bridge |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
-| **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
-| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`, `refine`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
+| **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into the host action (compact: the TUI compact command on v1, `session.compact` on v2; exit: `app.exit` on v1, the session's own tab closing on v2) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and host action routes |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `peer-review`, `refine`, `reflect`, `self-review`, `whois`) | Command markdown synced at plugin init; nudge-backed bodies rendered from the shared prompt cores with `thatch_` tool spellings, self-contained bodies (refine, whois, and the review-mode couchings peer-review/self-review) inline in the registry; `extract` and `whois` are opencode-only (they need session identity) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same bodies with `mcp__thatch__` spellings; `extract` and `whois` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same bodies; Cursor surfaces them as slash commands; `extract` and `whois` excluded | **Full** for the shared actions (same bodies, per-host tool spellings); `extract` and `whois` opencode-only |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
-| **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
+| **Extraction feedback** (toast notifications) | `client.tui.showToast` on v1; the session-tab bridge's toast event -> the TUI plugin's `ui.toast.show` on v2 — fires when the extraction child goes idle, but ONLY when memories were actually written (no toast for no-save runs, to avoid notification fatigue): shows `[thatch] new: N, updated: M, deleted: K` (success); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Behavior auto-fire** (self-discipline rules) | `chat.message` hook scores the prompt embedding against behavior matchers; injects a `[thatch] Situational behaviors` nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires behavior query via the sideband socket's `behaviors` method in parallel with recall and predictions | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scoreBehaviorNudge` entry point in both paths |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed by `thatch setup` (shared only) to the repo's `.claude/skills/` (local) or `$CLAUDE_CONFIG_DIR/skills/` (global) | Installed by `thatch setup` (shared only) to the repo's `.cursor/skills/` (local) or `~/.cursor/skills/` (global) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
-| **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
+| **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `THATCH_PROJECT_DIR` (pinned by project-local setup) → `CLAUDE_PROJECT_DIR` env → cwd | `THATCH_PROJECT_DIR` (pinned by project-local setup) → `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
 | **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |
 | **Hook config format** | n/a — plugin registers hooks in code | Nested: `.claude/settings.json` `{hooks:{Event:{hooks:[{type,command}]}}}` | Flat: `.cursor/hooks.json` `{version:1,hooks:{event:[{command}]}}` | n/a |
 

package/docs/dev/setup-and-hooks.md

@@ -80,7 +80,7 @@ project and every contributor gets them).
 |-------|---------|--------|------|
 | `SessionStart` | `thatch reminder` | plain text to stdout (becomes context) | Recall instructions + hygiene heartbeat + chat identity/mail line (reads the hook's stdin `session_id`) |
 | `PostToolBatch` | `thatch buffer-batch` | **silent** (no stdout) | Appends a batch of tool calls to the file-backed JSONL queue |
-| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Peeks queue (extraction nudge), else fires recall, prediction, and behavior nudges via sideband in parallel, else write nudge |
+| `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Peeks queue (extraction nudge; degraded to a restart instruction under version skew - the old server may lack the referenced tools), else fires recall, prediction, and behavior nudges via sideband in parallel, else write nudge |
 | `Stop` | `thatch chat-notify` | `{ hookSpecificOutput: { additionalContext } }` when chat mail is unread, else `{}` | Post-turn chat wake: the turn continues so the model reads its mail (Claude Code's analog of opencode's poller wake); host loop protections (`stop_hook_active`, 8-consecutive cap) plus the delivered stamp bound repeats |
 
 `PostToolBatch` is silent so the agent loop is not delayed; the buffered
@@ -122,7 +122,7 @@ is honored for symmetry and forward-compatibility. Cursor has no equivalent of
 |-------|---------|--------|------|
 | `sessionStart` | `thatch reminder --json` | `{ additional_context: "..." }` | Recall + heartbeat + chat identity/mail line, JSON-wrapped for Cursor |
 | `postToolUse` | `thatch buffer-tool` | **silent** | Appends a **single** tool call to the file-backed queue |
-| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Peeks queue, else recall, prediction, and behavior via sideband, else write nudge |
+| `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Peeks queue (extraction nudge; degraded to a restart instruction under version skew), else recall, prediction, and behavior via sideband, else write nudge |
 | `stop` | `thatch chat-notify` | `{ followup_message }` or `{}` | Post-turn chat wake: when chat mail is unread, Cursor auto-submits the follow-up as the next user message (Cursor's analog of opencode's poller wake); `loop_limit: 3` bounds consecutive follow-ups |
 
 Differences from Claude Code:
@@ -179,6 +179,11 @@ The host is determined from env vars set by the host process:
 
 Cursor takes priority because Cursor also sets `CLAUDE_PROJECT_DIR` as an alias.
 
+Separately from host detection, the project directory used for store/chat
+identity resolution resolves as `THATCH_PROJECT_DIR ?? CURSOR_PROJECT_DIR
+?? CLAUDE_PROJECT_DIR ?? cwd` in the MCP server; project-local `thatch
+setup` runs pin `THATCH_PROJECT_DIR` into the written MCP config.
+
 ### What it checks
 
 `checkSetup` looks for the instruction markers (start and end) in the host's

package/docs/dev/skills.md

@@ -47,18 +47,18 @@ description: Extract durable project facts ... Use when ...
 | `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 against generic praise. |
 | `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, verified citations, never blocking. |
-| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
-| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
+| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided, and against sibling PR registers when related PRs were detected (cross-PR notes appendix). |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. Also discovers related PRs (stacks chained through base branches, release trains ordered by tracker relations) and builds a sibling register with targeted consistency verdicts. |
 | `thatch-code-archaeology` | Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
-| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. |
-| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. Plans with UI or session state carry a state-and-transition matrix; template ports carry a deltas-from-template ledger; a revision self-check runs between revise and re-review; user-extended runs rotate reviewer lenses and stop on a round with no build-changing findings. Deep-mode triggers are binding. |
+| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. 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` | Refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
-| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. Relaxes round counts only, never mode selection. |
 | `thatch-refine-shared-lib` | Refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
 | `thatch-refine-spike` | Refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box. |
 | `thatch-refine-infra` | Refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute. |
@@ -69,17 +69,17 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-response` | Author-side review response: triage findings, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 | `thatch-memory-verify` | Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
 | `thatch-knowledge-export` | Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via `thatch-memory-verify`. |
-| `thatch-clear-writing` | Prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression; dedicated skills win when loaded. |
+| `thatch-clear-writing` | Prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, chat replies, and code comments. Clarity over compression; dedicated skills win when loaded. |
 
 **opencode-only** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the review specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the review specialists in parallel, synthesize with a workflow-change preface, prior-comment cross-reference, and sibling-register cross-reference. Also the machinery behind the `/thatch/self-review` and `/thatch/peer-review` mode commands, which run it with a weighting overlay (inline, without sub-agents, on hosts that lack the coordinator). |
 
 ## REVIEW_COMMON
 
-The seven problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the eighth specialist, highlights, finds positive things and uses its own structure):
+The seven problem-finding review specialists share a framework interpolated via `${REVIEW_COMMON}` (the technique and highlights specialists do not use it: technique reports informational notes and highlights finds positive things, each with its own structure):
 
 - **Static analysis only** — no running tests/linters/compilers.
 - **Scope gathering** — resolve the git range, `git diff --stat`, read changed
@@ -93,6 +93,9 @@ The seven problem-finding review specialists share a framework interpolated via
 - **Project context awareness** — if a context brief is provided (from the
   coordinator or from loading `thatch-review-context`), use it to avoid false
   positives about intentionally deferred work.
+- **Sibling PR context** — when the brief's sibling register is present
+  (related PRs detected), check it before flagging anything as referenced but
+  missing; a stack member or release-train sibling may deliver the piece.
 - **Workflow context awareness** — if a workflow guide is provided (from the
   coordinator or from loading `thatch-code-archaeology`), use it to understand
   the purpose and evolution of the code, distinguishing intentional behavior
@@ -143,7 +146,7 @@ and `--cursor` pass only the shared set.
 
 ## Adding a skill
 
-1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a problem-finding review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`). The highlights specialist does not use REVIEW_COMMON — it finds positive things, not problems, so the problem-finding framework does not apply.
+1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a problem-finding review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`). The technique and highlights specialists do not use REVIEW_COMMON — technique reports informational notes and highlights finds positive things, so the problem-finding framework does not apply to either.
 2. Add the skill name to the `names` array in `loadSharedSkills()` (or `loadOpencodeOnlySkills()` if sub-agents are needed). The loader in `src/skills.ts` reads `.md` files at init.
 3. If the skill name appears in a tool's workflow (e.g. `thatch-fact-extractor`), update `src/prompts.ts`.
 4. Run `mise run check` — tests verify counts; `installSkills` picks up new files on next init.

package/docs/plans/generalized-session-heartbeat.md

@@ -0,0 +1,212 @@
+# Plan: watcher death detection for closed v2 tabs
+
+Status: v3.1 - empirical premise VERIFIED live (2026-10-07: prompt_async
+to a closed v2 tab returns 404; no silent success; the session row
+persists, so the pre-cancel re-check keys on the throw class). The
+build's gate is open. Two refinement rounds converged (round 2: BUILD,
+no blockers).
+
+## Problem
+
+v2 tab close fires no `session.deleted`, so the closed tab's entry in
+the runtime's `sessionStatus` map (src/runtime.ts:217-222, keys "leave
+only in session.deleted") never leaves, the chat poller keeps hosting
+and heartbeat-ing the dead tab's row (src/runtime.ts:363-368,
+src/chat.ts:879-883), and its watchers poll until the 8h TTL with
+deliveries queuing forever. The session.deleted handler itself names
+the failure mode: "a leaked status key would keep heartbeat-ing a dead
+session as permanently fresh" (src/runtime.ts:1891).
+
+## Rejected: heartbeat-staleness death detection (the original plan)
+
+The original design gated the heartbeat stamp on `fetchStatuses`
+presence so a closed tab would age out. Round 1 proved the premise
+inverted: the live status map carries only ACTIVE (mid-turn) sessions -
+the host deletes idle entries (thatch's own wake-gate contract,
+src/chat.ts:366-368; host source session/status.ts:42-46) - so absence
+means "idle OR closed". Gating stamps on presence would mark every
+idle-open tab stale in 60s (regressing e486148, whose grace exists
+precisely because idle-open tabs emit nothing) and death-cancel the
+watchers of every idle session. And on v2 - the only host with the bug
+- `fetchStatuses` is a permanent `{}` stub (src/opencode/v2.ts:524;
+"session.status exists in v2's schema but nothing publishes it",
+v2.ts:417), so the mechanism does not exist where the bug lives.
+Chat-off sessions (chatPoller.start gated on chatOn,
+src/runtime.ts:407-409) get no stamps at all - a third false-death
+path.
+
+Conclusion: the heartbeat cannot carry tab-death detection on v2. The
+heartbeat keeps its current role (roster liveness for chat, unconditional
+stamps for hosted sessions); death detection needs a different clock.
+
+## New design: delivery-persistence death detection
+
+The signal that DOES distinguish a closed v2 tab from a live one, with
+no host API: **what happens to a pending watcher event.**
+
+- A live v2 session with queued events consumes them: the delivery gate
+  opens (on v2 the stub map reads as idle) and `promptAsync` succeeds -
+  there is no busy-rejection on the v2 prompt path. Queues drain.
+- A closed v2 session: every `deliver()` attempt throws (the session no
+  longer exists server-side) and the queue retries forever
+  (src/watchers.ts:1296-1298 - failed delivery stays pending).
+
+So: **death = a session's pending watcher queue has been non-empty for
+longer than the threshold AND recent delivery attempts have THROWN**
+(not been skipped - a skipped attempt is a busy/compacting session and
+must never count). The heartbeat is untouched; this is one extra clock
+on one queue, per session.
+
+- Threshold: 2 hours default (env `THATCH_WATCH_DEATH_MINUTES`). Far
+  above any legitimate busy turn; far below the 8h TTL, which remains
+  the hard backstop. The failure counter counts CONSECUTIVE thrown
+  deliveries per session (side map keyed by session id - WatcherEvent
+  carries no timestamp); a SKIPPED attempt (busy/compacting) or a
+  success RESETS it - skips are never death evidence.
+- Pre-cancel re-check (round 2): when the threshold fires, re-verify
+  the session via `caps.sessionGet` before cancelling - only a
+  not-found-class result confirms death. A wedged server or 500-loop
+  throws exactly like a dead session does, and without the re-check a
+  two-hour API outage would mass-cancel every hosted watcher.
+- v1 is out of scope: v1 fires session.deleted on tab close (the
+  known-gaps table), so v1 tabs already clean up; crashed v1 daemons
+  are covered by the dormant-row machinery.
+- On death: cancel the session's watchers (watchers.cancelSession -
+  also drops the pending queue, src/watchers.ts:1195-1201), emit a
+  death notice via the existing promptAsync path to other live
+  same-project sessions (`watcherDeathNotice`, src/prompts.ts:1051;
+  dedup per dead session like notifiedWatcherDeaths,
+  src/runtime.ts:801-806), and persist a `watcher_death` runtime_state
+  row (generic runtimeStatePut/All/Delete - no new db helpers).
+- Reader for the persisted row (round 2): the rehydration switch
+  (src/runtime.ts:609-713) must learn the `watcher_death` kind
+  (foreign-pid rows KEPT like dormant watcher rows, not deleted) and
+  the dormant-scan path (src/runtime.ts:779-825) surfaces pending
+  death rows to the scanning session, deduping against
+  `notifiedWatcherDeaths`, deleting the row on surfacing. Without this
+  the persistence half is write-only: unknown foreign-pid kinds are
+  deleted on restart (:615-641) and `dormantScanned` runs once per
+  session per process.
+- Scope guard: only sessions this process HOSTS via the
+  `hostedSessionIds` helper (src/runtime.ts:363-370) are eligible -
+  sibling v1 processes and MCP sessions are never touched.
+- Residual case (round 2, documented): a tab closed MID-TURN whose
+  host never emits a terminal execution event keeps its mapped status
+  `busy` forever - deliveries skip forever, death never fires, TTL
+  covers it. Accepted; the notice will not fire for that shape.
+- The roster zombie (a closed tab's row shows Active for days; the
+  7-day auto-reaper bounds auto rows) is NOT fixed by this plan - no v2-
+  reachable signal distinguishes it. Documented as a known limitation;
+  the reviewer confirmed no last_seen consumer treats staleness as a
+  trigger today, so the honest heartbeat stays unconditional.
+- Death notice payload (session-tab coordination, wanda-warpdrive-00009
+  2026-10-07): the notice carries the dead session's CHAT NAME and
+  session id, not just the watch targets, so a coordinator session
+  running the thatch-coordination skill can mark its task-list entry
+  failed and respawn keyed by chat name, no SDK lookup.
+
+### Confirmed-close fast path (integration with session-tab)
+
+The session-tab tool (docs/dev/features/session-tabs.md; merged to main
+as 5abb381) emits `rpc.thatch-tabs.tab-closed {sessionID,
+chatName?}` from its TUI plugin when a close is TOOL-initiated (shared
+module session-tab-shared.ts; user-initiated closes stay out of scope
+there - the delivery-persistence heuristic covers those). When the
+event lands for a session with watchers, treat it as a CONFIRMED
+close: skip the 2h heuristic entirely and run the death path
+immediately. The rpc definition is imported from session-tab-shared
+(same package). Fallback layering: confirmed close (instant) >
+delivery-persistence heuristic (2h) > TTL (8h).
+
+## Empirical premise: VERIFIED (2026-10-07, live probe via the session-tab smoke flow)
+
+Jeff closed a real v2 tab (session chatting as rosie-unit-one-00007,
+session ses_ee7ec0baeffeziwE83AT2mgLxI) with a command watch armed
+before the close. Probe results against the serve daemon's /api surface
+(Basic auth: username `opencode`, password from
+~/.config/opencode/service.json; unprefixed /session/* paths are the
+TUI SPA fallback - 200 HTML for anything, do not trust them):
+
+- POST /api/session/{id}/prompt_async -> HTTP **404** (clean, no body):
+  the delivery throw is real and 404-class.
+- Message count in the closed session before/after: 0 / 0 - **no silent
+  success, no headless turn**.
+- GET /api/session/{id} -> 200 with the full record: the session ROW
+  persists server-side after tab close, so existence checks cannot
+  confirm death.
+
+Consequence for design point 2's pre-cancel re-check: key on the throw
+CLASS (404 = route/session gone) not on sessionGet existence - a
+sessionGet 200 is expected even for dead tabs. Wedged-server 5xx loops
+still do not count as death; only 404-class delivery throws do.
+
+Location-scoping nuance (wanda-warpdrive-00009, post-probe): the v2
+prompt route is session-location-middleware'd, so the probe's
+cross-location 404 may encode location scoping rather than closed-ness
+per se. The death signal keys on the HOSTING poller's own deliveries
+throwing - same-location throws are the evidence that counts, and the
+session-tab `tab-closed` event papers over the ambiguous cases. The
+pre-cancel re-check and the threshold both run against the hosting
+instance's observed throw class.
+
+## Surfaces touched
+
+### Pending-event durability (from the 2026-10-07 reload-loss incident)
+
+A reload between DETECTION and DELIVERY silently eats notifications:
+pending events live only in the in-memory `#pending` queue, and one-shot
+watchers delete their journal row at detection time ("ends at first
+detection, not first delivery") - so the durability layer is gone
+exactly when undelivered events exist (observed: watch_qn449jio's CI
+notification lost in the 09b805f reload window). Fix folded into this
+build: journal PENDING EVENTS per session (alongside the watcher
+definitions), delete them on successful delivery - which the death
+detection needs anyway for its pending-age signal to survive reloads.
+(Found by robot-devil-00012's code-verified analysis; my own watcher
+was not one-shot, so its exact deletion path stays unproven until a
+THATCH_DEBUG=1 repro.)
+
+## Surfaces touched
+
+- `src/watchers.ts` - per-session delivery-failure tracking (consecutive
+  throws + oldest-pending age) and a death-scan hook the poller calls.
+- `src/runtime.ts` - wire the death callback: notice delivery to live
+  same-project sessions, the `watcher_death` runtime_state row, dedup.
+- `src/db.ts` - runtime_state row helpers for the death record.
+- `tests/watchers.test.ts` - death detection (throwing deliver + old
+  pending vs skipped-deliver + old pending), threshold env, MCP-owner
+  exclusion.
+- `tests/qa/auto/uc-118-watcher-death-detection.ts` (new,
+  barrel-imported).
+- Docs: `docs/user/watchers.md` (death notices), `docs/dev/features/
+  watchers.md` (detection subsection), `docs/dev/features/
+  opencode-plugin.md` known-gaps row (bounded by death detection),
+  `docs/user/cli.md` + `docs/dev/features/cli.md` (new env var).
+
+## Acceptance criteria
+
+1. A closed v2 tab's watchers are cancelled within the threshold once
+   deliveries have been failing; a live same-project session hears the
+   death notice.
+2. A busy or idle LIVE session never triggers death (skipped delivery
+   attempts never count; successful delivery drains the queue).
+3. A transient delivery failure (< threshold) cancels nothing.
+4. MCP-owner and non-hosted sessions are never touched.
+5. `mise run check` + `mise run qa-auto` green.
+
+## Review rounds
+
+- Round 1 (fresh reviewer): DO-NOT-BUILD on the heartbeat mechanism -
+  inverted premise (status absence means idle, not dead; v2 stub
+  returns {}), chat-off and sleep false-death paths, dormantScanned
+  once-per-session guard, incomplete death cleanup. The revision
+  replaces the mechanism with delivery-persistence detection
+  (v2-scoped) and drops the roster-zombie claim.
+- Round 2 (fresh reviewer): BUILD conditional on the empirical probe;
+  all premises verified (thrown deliveries stay pending at
+  src/watchers.ts:1344-1349, live sessions drain at runtime.ts:1866-
+  1874), with three required adjustments folded in: the death-row
+  reader + rehydration handling, the pre-cancel existence re-check,
+  and the known-gaps doc correction. Consensus to build - AFTER the
+  probe.
+