@jeffober/thatch 0.2.4 → 0.2.5

package/docs/dev/gotchas.md

@@ -293,3 +293,71 @@ 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.

package/docs/dev/mcp-parity.md

@@ -18,7 +18,7 @@ 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 |
@@ -31,7 +31,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **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

@@ -69,7 +69,7 @@ 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:
 

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.
+

package/docs/plans/prediction-consolidation.md

@@ -1,11 +1,18 @@
-# Prediction Consolidation and Compound Predictions
+# Fire Tracking and Compound Predictions
 
 ## Synopsis
 
-Post-processing layers for the prediction engine: fire tracking, co-fire-based
-consolidation (dedup), and compound (tier-2) predictions minted from
-co-firing constellations of existing predictions. Uses nudge-driven detection
-and the existing edge model for fire behavior. No cron, no separate backend.
+Post-processing layers for the prediction engine: fire tracking and compound
+(tier-2) predictions minted from co-firing constellations of existing
+predictions. Uses nudge-driven detection and the existing edge model for fire
+behavior. No cron, no separate backend.
+
+The consolidation (dedup) half was implemented separately and has graduated —
+the shipped design is documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). What remains here is the fire-tracking prerequisite
+and the co-fire refinements (behavioral dedup, compound detection) that
+consume the accumulated data.
 
 ## Background
 
@@ -14,10 +21,10 @@ auto-fires at chat.message and updates via agent tool calls. What it lacks
 relative to nak's samskara system:
 
 - **Fire tracking** -- no record of which predictions fire together on the same
-  turn. This is the prerequisite for both co-fire dedup and compound detection.
-- **Consolidation** -- no corpus-level dedup pass. Write-time dedup
-  (findNearestPrediction at 0.85) catches near-identical statements at creation,
-  but behavioral duplicates (same preference, different wording) accumulate.
+  turn. This is the prerequisite for co-fire dedup and compound detection.
+- **Consolidation** -- implemented and graduated: a cosine-only dedup pass
+  over the prediction corpus, no prerequisites
+  ([../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)).
 - **Compound predictions** -- no mechanism to mint a higher-order prediction
   from a constellation of predictions that reliably co-fire. Nak's tier-2
   samskaras fire at 77% genuine-engagement vs tier-1's 21% because compound
@@ -43,10 +50,13 @@ existing edge model.
 The co-fire data is for *deciding what to compound*, not for *making the
 compound fire*. This means:
 
-1. A compound needs no tier column, no special scoring path, no fire-path
-   changes. It is a prediction with multiple matcher edges.
-2. The existing `scorePredictions` already follows all edges and deduplicates by
-   prediction_id. A compound scores through its children's edges.
+1. A compound needs no tier column and no fire-path changes. It is a
+   prediction with multiple matcher edges. The scoring path does get one
+   addition: dynamic child suppression (see the compound-domination risk).
+2. The existing `scoreNudge`/`scoreItems` already follow all edges and
+   deduplicate by prediction_id. A compound scores through its children's
+   edges. Minting records the compound-to-children relation (Phase 4) so
+   suppression can tell parent from child.
 3. The existing `prediction_update` tool already finds existing matchers by
    cosine (0.85 threshold) and creates edges. Calling it multiple times with
    different matcher texts but the same prediction statement creates a
@@ -111,14 +121,18 @@ pass null or derive from the socket connection.
 tables. Same conventions (uuid PK, store column, idempotent CREATE TABLE IF
 NOT EXISTS).
 
-### Phase 2: Consolidation (Co-fire Dedup)
-
-**New DB method: `findPredictionDuplicates(store, threshold)`**
+### Phase 2: Co-fire refinement of dedup
 
-Two-pass, mirroring nak's `samskara_collapse_by_cofiring`:
+The cosine-only dedup pass (`findPredictionDuplicates`, the
+`prediction_dedup_pairs` table, the hygiene line, the merge flow) is
+IMPLEMENTED and graduated — documented in
+[../dev/features/prediction-engine.md](../dev/features/prediction-engine.md)
+("Dedup pass"). Once
+fire data accumulates, this plan upgrades that same method with behavioral
+evidence, mirroring nak's `samskara_collapse_by_cofiring`:
 
-**Primary pass (behavioral):** For each pair of predictions (A, B) in the store
-where both have fire_count > 0:
+**Behavioral pass (added to `findPredictionDuplicates`):** For each pair of
+predictions (A, B) in the store where both have fire_count > 0:
 
 ```
 cofires(A, B) >= 3
@@ -131,26 +145,11 @@ when either fires are duplicates. Two that co-fire but also fire independently
 are adjacent-but-distinct. Cosine is a sanity floor against spurious co-fires.
 
 **Safety cap (cosine-only):** If the prediction count exceeds a target (e.g.,
-100), fall through to pure embedding-cosine greedy merge (cosine >= 0.60)
-regardless of co-fire data. This catches accumulation when the behavioral pass
-finds nothing but the pool is still growing.
-
-**Output:** A list of candidate merge pairs with {predictionA, predictionB,
-cofires, ratio, cosine, firesA, firesB}. Surfaced via the hygiene nudge, not
-auto-merged. The agent reviews and merges via prediction_delete + (optionally)
-prediction_update to fold the loser's matchers into the winner.
-
-The merge itself is agent-driven: the agent sees the candidate pair, reads both
-predictions, deletes the weaker one (or uses a future `prediction_merge` tool
-if one is added). This matches the memory dedup pattern
-(`find_duplicates` + `dedup_mark_checked`).
-
-**Integration point:** `hygiene.ts` -- add a line to `hygieneReport`:
-`N prediction duplicate pairs pending review` when candidates exist.
+100), the implemented pure cosine pass already covers the pool;
+no behavioral evidence is required to keep dedup moving.
 
-**Nudge throttling:** Runs at session start only, same as the existing hygiene
-report. The analysis is O(n^2) over the predictions table but n is small
-(tens, not hundreds) so the cost is negligible.
+**Output:** the dedup plan's candidate shape extended with {cofires, ratio,
+firesA, firesB} per pair.
 
 ### Phase 3: Compound Prediction Detection
 
@@ -216,7 +215,14 @@ first child's matcher. Subsequent calls find the existing compound by
 `findNearestPrediction` (0.85 store-wide dedup) and add edges from the other
 children's matchers.
 
-This works with the existing tool surface. No new tools needed for minting.
+This works with the existing tool surface. One addition: minting must also
+record WHICH predictions the compound supersedes, because child suppression
+(see the compound-domination risk) needs the parent-to-children relation at
+scoring time -- shared matcher edges are implicit and cannot distinguish a
+compound from a busy multi-matcher prediction. `prediction_update` gains an
+optional `supersedes` arg (array of prediction ids), carried on the first
+mint call, writing one `prediction_compounds(compound_id, child_id)` row per
+child. No tier column; the compound is still an ordinary prediction.
 
 **Prompt instructions addition** (in prompts.ts, all three host variants):
 
@@ -225,8 +231,9 @@ After the existing prediction instructions, add guidance for compounds:
 - When the hygiene nudge reports co-fire constellations, consider whether the
   members share a generalizable behavior.
 - If so, synthesize a compound statement and call `prediction_update` once per
-  child matcher with the compound statement. The tool handles matcher dedup and
-  edge creation.
+  child matcher with the compound statement, passing the child prediction ids
+  as `supersedes` on the first call. The tool handles matcher dedup and edge
+  creation.
 - A compound should be strictly more general than any single child. If you
   cannot generalize, do not compound.
 - The compound inherits the fire coverage of its children's matchers. It will
@@ -258,7 +265,7 @@ chat.message (user text)
 session.created (top-level)
   → hygieneReport
     → findDuplicates (memories, existing)
-    → findPredictionDuplicates (NEW: co-fire dedup candidates)
+    → findPredictionDuplicates (implemented; co-fire-refined here)
     → findCoFireConstellations (NEW: compound candidates)
     → inject hygiene nudge with all signals
 
@@ -276,44 +283,48 @@ computation, same as existing prediction methods.
 db.ts.
 
 **Code changes by file:**
-- `src/db.ts` -- new table, 4-5 new methods (recordFires, fireCount,
-  cofireCount, totalCohorts, findPredictionDuplicates, findCoFireConstellations)
+- `src/db.ts` -- one new table (`prediction_fires`) + 4 new methods
+  (recordFires, fireCount, cofireCount, totalCohorts, findCoFireConstellations);
+  the co-fire refinement extends the implemented `findPredictionDuplicates`
+  method
 - `src/runtime.ts` -- generate cohort_id, pass to recordFires in auto-fire path
 - `src/sideband.ts` -- same for MCP path
-- `src/hygiene.ts` -- add prediction dedup + constellation counts to report
+- `src/hygiene.ts` -- add constellation count to report (the dedup count is
+  already implemented there)
 - `src/prompts.ts` -- compound minting guidance in all three prompt variants
 - `tests/prediction.test.ts` -- tests for new DB methods
 - `tests/plugin.test.ts` -- test that fire tracking records cohorts
 
 ## Implementation Order
 
+0. **Cosine dedup** -- IMPLEMENTED and graduated (Oct 2026):
+   `findPredictionDuplicates` + `prediction_mark_checked`; nothing left to do.
 1. **Fire tracking** (table + recordFires + caller wiring). Foundation for
-   everything else. Ship and let fire data accumulate.
-2. **Cosine dedup** (findPredictionDuplicates + hygiene integration). Does not
-   need fire tracking. Can ship in parallel with phase 1. Immediate value:
-   catches behavioral duplicates the write-time 0.85 dedup misses.
-3. **Co-fire dedup** (add co-fire ratio + cosine filter to
-  findPredictionDuplicates). Needs fire data to accumulate first. Wait a few
-   weeks after phase 1 ships.
-4. **Compound detection** (findCoFireConstellations + hygiene integration).
+   everything else here. Ship and let fire data accumulate.
+2. **Co-fire dedup** (add the behavioral pass to findPredictionDuplicates).
+   Needs fire data only -- the method and pair table already exist. Wait a
+   few weeks after fire tracking ships.
+3. **Compound detection** (findCoFireConstellations + hygiene integration).
    Needs more fire data than dedup (p_min_cofires = 10). Wait longer.
-5. **Compound minting** (prompt instructions + agent-driven via existing
-  tools). Ships with phase 4 -- the nudge surfaces candidates, the agent
-   compounds.
+4. **Compound minting** (prompt instructions + agent-driven via existing
+  tools). Ships with compound detection -- the nudge surfaces candidates,
+   the agent compounds.
 
-Phases 1-2 can ship together. Phases 3-5 follow once fire data accumulates.
+Fire tracking ships immediately; the rest follow once fire data accumulates.
 
 ## Test Plan
 
 - `prediction.test.ts`: test recordFires, fireCount, cofireCount,
-  totalCohorts with synthetic cohorts. Test findPredictionDuplicates with
-  known co-firing pairs. Test findCoFireConstellations with lift thresholds.
+  totalCohorts with synthetic cohorts, the co-fire refinement of
+  findPredictionDuplicates with known co-firing pairs, and
+  findCoFireConstellations with lift thresholds.
   Use the existing `makeEmbed(seed, dim=384)` helper.
 - `plugin.test.ts`: test that chat.message auto-fire records a cohort.
   Follow the recall-nudge test pattern (mock.module transformers + server
   hooks).
 - `hygiene.test.ts` (if exists) or `plugin.test.ts`: test that hygiene report
-  includes prediction dedup/constellation counts when candidates exist.
+  includes the constellation count when candidates exist (the dedup count
+  tests are implemented, riding UC-113).
 
 ## Risks and Mitigations
 
@@ -324,11 +335,18 @@ precondition gate (minimum prediction count, minimum fire count) before running
 the analysis.
 
 **Risk: Compound predictions fire too much, dominating the nudge.**
-Mitigation: The existing `scorePredictionNudge` deduplicates by prediction_id
-and slices to limit=5. A compound competes on equal footing with its children.
-If a compound and a child both fire, the higher-scoring one wins the slot. The
-compound's score is `cosine(matcher) * edge.weight * confidence` -- same
-formula. No special treatment.
+Mitigation (nak-proven): dynamic child suppression, not equal-footing
+competition. When a compound and its child both score in the same round and
+the compound's score is higher, the child is skipped. The rule resolves
+during the scoring pass, per query -- not as a stored flag -- so the
+surviving set adjusts as it searches and freed slots refill from the
+remaining scored list. If the child outscores the compound (it matched a
+matcher the compound did not inherit), both surface. Implementation: the
+per-round dedup filter in `scoreItems` (src/scoring-engine.ts:153-178)
+gains the suppression check, using the compound-to-children relation
+recorded at mint time. Plain prediction_id dedup and the limit=5 slice are
+unchanged. Fire rows record post-suppression survivors only, so co-fire
+data means co-surfaced.
 
 **Risk: Agent creates poor compounds (too generic, not useful).**
 Mitigation: The prompt instructions include the "strictly more general" guard
@@ -351,9 +369,11 @@ this becomes a concern. Low priority.
   a separate improvement, not part of this plan, but worth doing alongside
   phase 1.
 - The existing write-time dedup (`findNearestPrediction` at 0.85) catches
-  near-identical statements at creation. The co-fire dedup in phase 3 catches
-  behavioral duplicates that differ in wording. The two are complementary:
-  write-time catches semantic twins, co-fire catches behavioral twins.
+  near-identical statements at creation. The implemented dedup pass
+  (cosine, with its co-fire refinement here) catches
+  behavioral duplicates that differ in wording. The layers are
+  complementary: write-time catches semantic twins, the dedup passes catch
+  behavioral twins.
 - Nak's tier-2 decline ledger (`samskara_tier2_declines`, TTL'd 7 days) prevents
   re-offering a declined constellation every sweep. Thatch's equivalent: a
   `prediction_constellation_declines` table or a `dedup_pairs`-style