@jeffober/thatch 0.2.3 → 0.2.5

package/docs/dev/features/watchers.md

@@ -88,9 +88,15 @@ A `setInterval` loop (unref'd - it never keeps the process alive)
 runs `poll()` every 60 seconds (configurable). Each cycle:
 fetch the current state, run `diffPrState()` against the watcher's
 last-seen state, filter events to the watched types, queue them, and
-attempt delivery. Poll errors are per-watcher; one bad PR never
-blocks the others. The diff is a pure function, so it is unit-tested
-without any network access.
+attempt delivery. When the fetched snapshot differs from the last-seen
+state, the cycle also rewrites the session's journal row: registry
+rebuilds (v2 reload rehydration, the watch tools' journal reconcile)
+hydrate the journaled state verbatim, so a journal that lags the
+poller would make the next diff re-fire already-delivered events -
+observed live in October 2026 as a watch re-delivering the same CI
+completion on every reload. Poll errors are per-watcher; one bad PR
+never blocks the others. The diff is a pure function, so it is
+unit-tested without any network access.
 
 The interval is surfaced to the model through the registry's
 `pollSeconds` getter: watch-creation output states when the first
@@ -126,6 +132,41 @@ when this run finishes" request from leaving a standing watch polling
 a target nobody is waiting on. `watch_list` marks one-shot watchers
 with a `[once]` tag, and the registration output states the mode.
 
+### Expiry
+
+A watch whose TTL passes is dropped at the next poll cycle, and the
+owning session is told: a `watch_expired` event queues through the
+normal pending path, naming the target and the watch's lifetime in
+minutes. The nudge framing for an all-expiry delivery states that the
+watched condition never occurred - deliberately without the
+greenlit-gating carve-out, because "the watch ran out of clock" must
+never read as "the wait is over". Watches that expire while a session
+is away are a separate path: they are not re-armed, and the re-arm
+notice reports the expired count.
+
+### Death detection (closed v2 tabs)
+
+A closed opencode v2 tab fires no `session.deleted`, so its watchers
+would poll until the TTL with deliveries queued forever. The registry
+declares death when ALL of: the session's pending queue has been
+non-empty longer than the threshold (`THATCH_WATCH_DEATH_MINUTES`,
+default 120), its delivery attempts have THROWN consecutively (a skip -
+busy or compacting - resets the chain; skips are never death evidence),
+the throw is 404-class (verified live 2026-10-07: prompt_async to a
+closed v2 tab returns 404 while the session row persists; a 5xx loop is
+a wedged server, never death), and the session is hosted by this
+process (sibling v1 processes and MCP sessions are never touched).
+MCP-owner watches keep TTL-only death: their turn-driven heartbeat
+cannot distinguish a closed Cursor tab from a parked one. On death:
+watchers and pending drop, and live same-project sessions get a
+`watcherDeathNotice` carrying the dead session's chat name and session
+id (the thatch-coordination loop's respawn key); a durable
+`watcher_death` runtime_state row covers sessions that were busy at
+death time, surfaced and cleared at other sessions' next prompt. The
+notice says the watches were CANCELLED and points at `watch_create` -
+the re-arm-on-resume promise belongs only to the restart-dormant path,
+where the definitions survive and resuming the session re-arms them.
+
 ### Command watches
 
 The command source stretches the fetch/diff recipe in two ways:
@@ -180,6 +221,11 @@ Events queue in an in-memory pending map keyed by session. Delivery
 is gated by a `canDeliver` predicate the plugin supplies: the session
 must be idle (tracked from `session.status` events) and not
 compacting. Proactive prompts are never injected into a running turn.
+The queue is visible to the session itself: `watch_list` appends an
+"N events detected, waiting for idle to deliver" line with a
+per-target breakdown while events sit undelivered, so a busy session
+with queued events is distinguishable from a watcher that fired
+nothing.
 
 When the gate is open, the plugin calls `client.session.promptAsync`
 on the session with a synthetic text part built by
@@ -206,9 +252,11 @@ cycle or when the session next goes idle (the event hook calls
 `pr_review_resolved`, `pr_commit`, `pr_status`, `pr_description`,
 `pr_ci`. The tool's `events` argument selects a subset; the default is
 all eight. Branch watchers add `branch_commit`, `branch_ci`, and
-`branch_workflow` (the full vocabulary is `WATCHER_EVENT_TYPES` in
-src/watchers.ts, test-enforced); command watchers register the single
-`command_success` type.
+`branch_workflow`; command watchers register the single
+`command_success` type. The registry itself emits one lifecycle type
+across all sources, `watch_expired`, which is not selectable via the
+`events` argument (the full vocabulary is `WATCHER_EVENT_TYPES` in
+src/watchers.ts, test-enforced).
 
 ## Interactions with other features
 
@@ -229,6 +277,8 @@ src/watchers.ts, test-enforced); command watchers register the single
 - `THATCH_WATCH_TTL_MINUTES` - watcher time-to-live (default 480)
 - `THATCH_WATCH_MAX_PER_SESSION` - active watchers per session
   (default 5; all sources share the budget)
+- `THATCH_WATCH_DEATH_MINUTES` - pending-age threshold before a dead
+  session's watchers are cancelled and announced (default 120)
 - `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` - per-run kill timeout for
   watched commands (default 30)
 
@@ -248,6 +298,12 @@ src/watchers.ts, test-enforced); command watchers register the single
   mocked gh runner
 - `tests/qa/auto/uc-101-command-watchers.ts` - command-watch lifecycle
   against a mocked command runner
+- `tests/qa/auto/uc-114-watcher-expiry-replay.ts` - expiry notification
+  and the no-replay guarantee across journal rehydration
+- `tests/qa/auto/uc-118-watcher-death-detection.ts` - closed-tab death
+  detection (404-class delivery persistence) and the once-only notice
+- `tests/qa/auto/uc-115-watch-list-pending-events.ts` - pending-event
+  visibility in watch_list while the session is busy
 
 ## Adding a new source type
 

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