@jeffober/thatch 0.2.4 → 0.2.5

package/docs/dev/features/cross-session-chat.md

@@ -86,6 +86,29 @@ worktree, a `.git` directory means the project root, no `.git` reads as
 undetected. The roster shows it as a `loc:` token so sessions coordinating
 on a shared tree can tell who sits where.
 
+### Machinery sessions never auto-register
+
+Sessions the plugin itself creates as machinery are not chat
+participants and never join the directory: the direct-extraction child
+(`triggerExtraction`, titled `thatch-extraction`) is the current case.
+The primary guard is durable, not in-memory: child creation writes a
+`chat_machinery` row (src/db.ts), and both auto-register paths (prompt
+and idle) refuse a marked session. This matters because the in-memory
+`childToParent` mapping that normally keeps children out is lost to a
+plugin reload or daemon restart - an instance that processes the child's
+events without the mapping would otherwise register it, and since v2
+cannot delete sessions (see docs/dev/features/opencode-plugin.md), the
+row never cleans up. The poller heartbeats every registered row of the
+project it serves, so a machinery corpse stayed fresh forever and the
+stale-row reaper could not reap it (81 corpse rows by 2026-10-07). The
+idle path deletes any corpse row it finds for a marked session
+(self-healing) and additionally refuses a session whose fetched title is
+the machinery title (`isMachinerySessionTitle`, src/chat.ts) - the title
+is the one signal that survives even a lost marker. Markers age out with
+the 7-day auto-row TTL; session ids are never reused, so an expired
+marker cannot resurrect a row. Explicit `chat_register` is unaffected:
+a model deliberately joining the directory is never machinery.
+
 ### Startup registration and reclaim
 
 A session continued via `opencode -s <id>` gets no event when it comes
@@ -168,15 +191,73 @@ unregistration; a departed sender degrades to an unknown name in the
 reader's view (the endpoints are deliberately not foreign keys - leaving the
 directory must not be blocked by history).
 
+Bodies over the part budget are not refused: `splitChatBody` (src/chat.ts)
+auto-splits them into parts, and the first part is prefixed "(message 1 of
+N)" while every part but the last is suffixed "(continued in next
+message)", so a reader assembles the batch before acting on it. Cuts
+prefer blank-line paragraph boundaries and back off a hard cut so a
+surrogate pair never splits mid-character. The parts of one send are
+inserted in ONE transaction - a crash cannot leave a partial batch - and
+the tool output reports the split ("SENT AS N PARTS") so a caller cannot
+mistake it for a single delivery.
+
+Two budgets govern the split, and the docs state both honestly:
+
+- The part budget is `CHAT_SPLIT_PART_LEN`, default 2000 UTF-16 units
+  (`THATCH_CHAT_SPLIT_PART_LEN` to override, clamped to 500..9000). The
+  DEFAULT is sized to the worst host we have observed: a version-skewed
+  opencode install whose tool-result renderer clipped at exactly 2000
+  characters with no saved-output pointer, cutting each part off before
+  the model saw it. Current opencode v2 (pinned tag v2.0.24) passes
+  50 KiB and 2000 lines per tool result (packages/core/src/tool-output.ts
+  MAX_LINES/MAX_BYTES, host-configurable via
+  `tool_output.max_lines/max_bytes`), so a host on a known-good version
+  can safely raise the override.
+- The whole body is capped by `CHAT_MAX_BODY_CHARS`, default 20,000
+  characters (`THATCH_CHAT_MAX_BODY_CHARS`), checked up front at accept; the
+  number of parts derives from it (ceil(total/partLen)). The refusal
+  reports the attempted count so a caller can split deterministically.
+  The grouped chat_read of a split batch renders as ONE tool result, so
+  the ceiling keeps a worst-case batch read (at most ten 2000-char parts
+  plus framing) comfortably inside the 50 KiB v2 envelope while still
+  bounding the context bomb the old 10k refusal used to block.
+
+Read-side clipping: the chat_read drain shows each message up to
+`CHAT_READ_PAGE_LEN` (2000) characters; longer rows are shown clipped
+with a per-message marker that names the unit - "[clipped: showing 2000
+of 9050 characters" - and the deterministic recovery path. Every drain
+line carries the message id, and `chat_read` accepts `message` (a row id)
+and `offset` (a character offset) to page through one message a page at a
+time without draining or marking anything read. This is the recovery for
+both a drain clip and a HOST-side tool-result clip (the version-skew host
+above): even when a marker or a whole message is cut, the frame note at
+the top of the result teaches the paging call, and ids make it exact.
+
 `chat_broadcast` posts one message to every other registered session at
-once, one inbox row per recipient - the existing wake machinery (grouping,
-gating, rate cap) treats each as ordinary mail. Stale sessions are skipped
-and reported rather than messaged: a host that has stopped heartbeat-ing
-will never read the mail, and dead mail to a dead process is just clutter.
-The sender is excluded. It is a separate tool rather than a magic
-`chat_send` recipient because "send to all" changes the behavior (fan-out,
-stale skipping, no address resolution), and a function that changes
-behavior drastically on a parameter value is two functions.
+once, one inbox row per recipient per part - the existing wake machinery
+(grouping, gating, rate cap) treats each as ordinary mail. Stale sessions
+are skipped and reported rather than messaged: a host that has stopped
+heartbeat-ing will never read the mail, and dead mail to a dead process is
+just clutter. The sender is excluded. It is a separate tool rather than a
+magic `chat_send` recipient because "send to all" changes the behavior
+(fan-out, stale skipping, no address resolution), and a function that
+changes behavior drastically on a parameter value is two functions.
+
+Retries are idempotent by READ STATE within a short window: a send (or
+per-recipient broadcast batch) whose content matches an existing row on
+sender, recipient, body, and delivery kind within `CHAT_DEDUPE_WINDOW_MS`
+(10s) succeeds without a second insert - but ONLY while a matching row is
+still UNREAD in the recipient's inbox. The mail is there; a retry adds
+nothing. Once every matching row was read, the identical body DELIVERS
+again: presumptively an intentional resend after the first was consumed
+(a repeated "ok", a resend the reader asked for). The tool output says
+why it suppressed ("still UNREAD in the recipient's inbox"). This exists
+because a harness that times out a chat_send which actually committed
+retries the call, and the identical body otherwise lands twice (observed
+2026-10-07). The same body outside the window is always a new message.
+For a split batch, ANY unread part suppresses the retry - idempotent even
+while the recipient is mid-read (the poller keeps nudging the unread
+parts), and only a fully read batch lets an intentional repeat through.
 
 ### Polling, heartbeat, staleness
 
@@ -360,11 +441,23 @@ parent pid against that table (`chatDerivedIdentity` on CoreContext,
 freshness-capped at 600s to bound pid reuse). A second model-proof layer
 is `CLAUDE_CODE_SESSION_ID`, which the host sets in the stdio server's
 environment at spawn. `resolveChatIdentity` priority: opencode host
-context > ppid mapping > env id > claimed `as`. Cursor's hooks and MCP
+context > ppid mapping > env id > claimed `as`. The `as` fallback is also directory-bound: the
+claimed identity must belong to the caller's project (the store slug
+every registration writes as the row's project column) - a cross-project
+or null-project claim is refused with a re-register escape hatch.
+Cursor's hooks and MCP
 servers share one workspace process (ambiguous ppid, no per-session env),
 so Cursor keeps the claimed-`as` path, documented in the user doc's
 security model.
 
+**Server project resolution.** The MCP server resolves its own project
+directory as `THATCH_PROJECT_DIR ?? CURSOR_PROJECT_DIR ??
+CLAUDE_PROJECT_DIR ?? cwd` (a superset of detectRepo's chain), maps
+`unknown` to `global` exactly like the hook, and project-local setups
+pin `THATCH_PROJECT_DIR` into the written MCP config so the resolution
+is cwd-independent. Global-scope registrations are never pinned - one
+entry serves every project.
+
 **Continuation adoption (Claude Code).** Claude Code forks the session id
 on resume - and has been observed to fork spontaneously (agent-team
 conversion, self-update, config reload) - which would strand the old
@@ -384,12 +477,23 @@ Staleness semantics differ by kind: an opencode row's stale age means its
 harness stopped beating (broadcast skips it), while an mcp row's age only means
 "between turns" (broadcast always delivers).
 
+The `/thatch/whois` command (opencode-only action, src/commands.ts) is the
+user-facing identity report: it relays `chat_status` for the invoking
+session's handle, then joins the roster row for topic, project, and the
+`loc:` worktree token - the topic being the live TUI session title, it is
+how the operator maps a roster handle to a visible tab. An argument looks
+up another session's row instead. It reports only; it never reads mail or
+mutates anything.
+
 ## Defaults
 
 Timing constants live in `src/chat.ts`: poll interval 30s, staleness
 threshold two missed beats (60s), re-nudge window 15 minutes, nudge cap 6 per recipient
-per hour, auto-row TTL 7 days. There are no environment overrides yet; add
-them the way `THATCH_WATCH_POLL_SECONDS` works if a user needs them.
+per hour, auto-row TTL 7 days. Environment overrides: `THATCH_CHAT_SPLIT_PART_LEN`
+(auto-split part budget, default 2000, clamped 500..9000) and
+`THATCH_CHAT_MAX_BODY_CHARS` (whole-body acceptance ceiling, default 20000);
+both are resolved once at module load and sanitized to positive integers
+within their clamps - invalid values silently fall back to the default.
 
 ## Source files
 
@@ -418,5 +522,8 @@ them the way `THATCH_WATCH_POLL_SECONDS` works if a user needs them.
 - `tests/qa/auto/uc-097-chat.ts` - full lifecycle against a mocked poller
 - `tests/qa/auto/uc-099-chat-cli.ts` - `chat list` roster and `chat tail`
   JSONL contract over a seeded DB
+- `tests/qa/auto/uc-116-chat-send-dedupe.ts` - a retried send is suppressed
+- `tests/qa/auto/uc-119-chat-split-long-messages.ts` - an oversized body is
+  auto-split into marker-decorated parts
 - `tests/qa/live/uc-098-chat-cross-session.ts` - two real sessions exchange
   a message through the shared DB

package/docs/dev/features/notifications.md

@@ -10,8 +10,7 @@ Two delivery paths share the dispatcher and the config file:
 - **Agent-initiated**: the LLM calls `notify_user`. Works on every host.
 - **Automatic alerts** (opencode-only): the plugin runtime watches session
   events and notifies when the LLM pauses for human input or finishes a
-  round of real work. See the Alerts section below and
-  `docs/plans/llm-alerts.md` for the design decisions.
+  round of real work. See the Alerts section below for the design decisions.
 
 ## Source files
 

package/docs/dev/features/opencode-plugin.md

@@ -71,9 +71,10 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
 | session messages | `client.session.messages` | `session.context` | mapped into the v1 `{info: {role}, parts}` shape, so the wrap-up greenlight check works (the promise domain has no `message` accessor) |
 | session list | `client.session.list` | none | degrade (`-c` resume listing loses its data source) |
 | compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
-| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context; a `tui` companion plugin entrypoint is the known lift candidate) |
-| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984). On v2 the right target closes THIS session's tab (tab-scoped), not `app.exit`: the daemon hosts every tab; the `tui` companion entrypoint's `ui.tabs.close` is the known lift candidate) |
-| tab close | n/a | no session.deleted on v2 tab close | known gap: a closed tab's watchers keep polling until their TTL (deliveries fail their idle gate and stay pending); restart dormancy covers the daemon-restart case, not tab close |
+| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context; the `./tui` companion entrypoint now EXISTS for the session-tab feature - extending it to publish toasts is the remaining lift) |
+| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984). On v2 the right target closes THIS session's tab (tab-scoped), not `app.exit`: the daemon hosts every tab; the `./tui` entrypoint's `ui.tabs.close` is the known lift candidate and the session-tab rpc bridge is the transport) |
+| session tabs | n/a | rpc event bridge | NEW: `thatch_session_tab` (v2Only) spawns a detached subordinate session (create -> move -> chat-register -> emit `rpc.thatch-tabs.tab-opened` -> prompt); the `./tui` CLI plugin consumes the event and calls `ui.tabs.open` (open-without-focus, idempotent). The deferred `thatch_session_tab_close` will emit `rpc.thatch-tabs.tab-closed {sessionID, chatName?}` - the shape is reserved and consumed by the generalized-session-heartbeat plan |
+| tab close | n/a | no session.deleted on v2 tab close | bounded 2026-10-07: watcher death detection cancels a closed tab's watchers once its pending events age past `THATCH_WATCH_DEATH_MINUTES` (default 120) while deliveries throw 404-class errors, and announces the death to live same-project sessions; the roster row itself still lingers until the reaper. NOTE: an earlier version of this row claimed deliveries "fail their idle gate" - wrong: the v2 gate opens (the status stub reads as idle) and the PROMPT fails; same leak, different link |
 | wake gate after reload | `session.status` event map | map rehydrates empty | known gap: v2's fetchStatuses stub is structural (the promise context has no session.status), so in the reload window - until the session's next status event - the proactive-prompt gate is fully open |
 | dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; child rows carry a kind marker (extraction vs task-dispatched sub-agent, defaulting to extraction for pre-marker rows) so only extraction children restore the `extracting`/`extractionChildren` sets; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
 
@@ -112,15 +113,29 @@ key (`plugin` vs `plugins`) is auto-migrated by v2. The only user-owned file
 with a content change is the dev-session shim, and its new dual-shape content
 loads under both hosts.
 
+The session-tab feature adds a second user-owned artifact: the TUI-side
+plugin entry. A local FILE plugin shim carries a `server` entrypoint only
+(v2's `plugin/module.ts`), and the TUI's plugin discovery loads directories
+and symlinks, never plain files - so the dev-checkout install must be a
+DIRECTORY shim: `thatch/index.ts` (the dual-shape re-export, unchanged) plus
+`thatch/tui.ts` (re-exporting the TUI plugin). DELETE the old `thatch.ts`
+file in the same step - a file and a directory shim coexisting dies with
+`duplicate instance plugin ids: thatch` before any plugin code runs (the
+duplicate check is in activation, so nothing inside the plugin can
+self-heal it).
+
 ## Source files
 
 - `src/index.ts` -- dual entry, merged default export, lazy wrappers
 - `src/opencode/v1.ts` -- v1 hooks adapter
 - `src/opencode/v2.ts` -- v2 promise-context adapter + capability impl
+- `src/opencode/tui-plugin.ts` -- v2 TUI CLI plugin (the `./tui` entrypoint: consumes the session-tab rpc events, drives `ui.tabs`)
+- `src/session-tab-shared.ts` -- the cross-entry session-tab contract (rpc definition, prompt builder, validators)
 - `src/capabilities.ts` -- `HostCapabilities`, `capabilitiesFromClient`
 - `src/runtime.ts` -- the shared runtime (all behavioral logic)
 - `src/os-args.ts` -- pure argv helpers
 - `tests/opencode-v2.test.ts` -- v2 adapter contract tests (mocked context)
+- `tests/session-tab-shared.test.ts` -- session-tab validators, rpc definition shape, TUI guard logic
 - `tests/plugin.test.ts` -- v1 adapter contract tests (mocked client)
 
 ## Interactions with other features

package/docs/dev/features/prediction-engine.md

@@ -6,8 +6,9 @@ calls and updates it based on user feedback.
 
 ## What it does
 
-- Four tools: `prediction_query`, `prediction_update`, `prediction_list`,
-  `prediction_delete`. All defined in `src/tool-defs.ts`.
+- Tools: `prediction_query`, `prediction_update`, `prediction_list`,
+  `prediction_delete`, `prediction_mark_checked`. All defined in
+  `src/tool-defs.ts`.
 - Auto-fires at every user message: embeds the prompt, cosine-matches against
   matchers, injects scored predictions as a synthetic nudge part.
 - Bayesian confidence model — a graded score that is reinforced or weakened
@@ -101,6 +102,33 @@ Runs in a single DB transaction:
 Returns a status line with final confidence and confirm/disconfirm counts.
 Embeds both the matcher and prediction text.
 
+### Dedup pass (corpus-level consolidation)
+
+Write-time dedup (0.85, both stores) catches near-identical statements at
+creation. Wording-different duplicates — the same preference restated weeks
+later — land below that floor and accumulate. The dedup pass finds them:
+
+- `findPredictionDuplicates(store, threshold = 0.70)` in `src/prediction.ts`:
+  pairwise cosine over the store's predictions, skipping pairs already
+  adjudicated in `prediction_dedup_pairs`. The threshold is band placement:
+  [0.85, 1] is write-time territory, below 0.70 short-statement embeddings
+  are too noisy to call duplicates.
+- Pairs are keyed on the canonical SORTED id pair — (A,B) and (B,A) are one
+  row, the same contract as the memory side's `dedup_pairs`.
+- `prediction_mark_checked(id_a, id_b, status)` records the verdict:
+  `duplicate` (merged or treat as one) or `distinct` (both legitimate).
+  Distinct verdicts are the load-bearing case — a destroyed duplicate is
+  gone, but a judged-distinct pair re-surfaces every session start unless
+  recorded.
+- The hygiene report surfaces `N prediction duplicate pairs pending review`;
+  the agent merges (fold the loser's matchers with `prediction_update`, then
+  `prediction_delete` the loser) or judges distinct, and marks the pair
+  either way. Scans are per-store: cross-store writes are edge-linked at
+  write time instead of duplicated.
+- The co-fire refinement (behavioral evidence layered onto this method once
+  fire tracking exists) is designed in
+  [../../plans/prediction-consolidation.md](../../plans/prediction-consolidation.md).
+
 ### Auto-fire (opencode: `chat.message` hook)
 
 - Reuses the prompt embedding already computed for the recall nudge — no extra
@@ -190,11 +218,11 @@ that user preferences are stable, not time-sensitive.
 
 | File | Role |
 |------|------|
-| `src/prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names |
+| `src/prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names, plus the corpus dedup pass (`findPredictionDuplicates`, pair verdicts) |
 | `src/scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence (shared base for prediction and behavior) |
 | `src/db.ts` | Prediction tables, `scorePredictionNudge` |
-| `src/tool-defs.ts` | Four prediction tools (`query`, `update`, `list`, `delete`) |
-| `src/prompts.ts` | `predictionNudge` formatting, verb selection |
+| `src/tool-defs.ts` | Five prediction tools (`query`, `update`, `list`, `delete`, `mark_checked`) |
+| `src/prompts.ts` | `predictionNudge` formatting, verb selection, dedup-merge guidance |
 | `src/sideband.ts` | `predictions` method for the MCP path |
 
 ## Database tables
@@ -241,6 +269,15 @@ prediction_provenance(
     created_at   TEXT,
     FOREIGN KEY (prediction_id) REFERENCES predictions(id) ON DELETE CASCADE
 )
+
+prediction_dedup_pairs(
+    store      TEXT,
+    id_a       TEXT,
+    id_b       TEXT,
+    status     TEXT,
+    checked_at TEXT,
+    PRIMARY KEY (store, id_a, id_b)
+)
 ```
 
 ## Key invariants
@@ -254,3 +291,5 @@ prediction_provenance(
    `chat.message` hook and MCP sideband) prevents scoring drift.
 5. **Matcher text is embedded raw.** No header prepend — unlike
    `memory_remember`, which prepends `# label\n\n` before embedding.
+6. **Adjudicated dedup pairs never re-surface.** Verdict rows are keyed on
+   the canonical sorted id pair; `findPredictionDuplicates` skips them.

package/docs/dev/features/session-tabs.md

@@ -0,0 +1,155 @@
+# Session tabs (coordinated subordinates)
+
+## What it does
+
+`thatch_session_tab` (opencode v2 only) lets a coordinating LLM spawn a
+detached subordinate LLM session in a new TUI tab. The subordinate is a full
+peer session: it runs its own agent loop across many turns, in a directory
+of the coordinator's choosing, while the coordinator keeps working. The user
+sees the subordinate's tab appear beside the coordinator's, unfocused.
+
+This is NOT the `task` tool: task subagents run inside the dispatcher's turn
+and return their result inline. A tab subordinate outlives the dispatching
+turn and is supervised over cross-session chat.
+
+## How it works
+
+```text
+coordinator session (LLM)
+  |  tool call: thatch_session_tab {prompt, title, worktree|directory}
+  v
+v2 adapter (src/opencode/v2.ts, buildSessionTabHost via CoreContext.sessionTabHost)
+  |  validate (tool-defs: title, exactly-one location arg, fs existence,
+  |            worktree same-main-checkout identity)
+  |  1. session.create({title, metadata: {thatch: {...}}, location})
+  |  2. worktree flow: session.move({directory: worktree})  (idle -> steer = immediate)
+  |  3. db.registerChatSession(subordinate)   (participant, never machinery-marked)
+  |  4. rpc emit rpc.thatch-tabs.tab-opened {sessionID, directory}
+  |  5. session.prompt({text: preamble + task})
+  v
+SSE event feed (isOpenCodeEvent passes rpc.*; fans out across all locations)
+  v
+TUI CLI plugin (src/opencode/tui-plugin.ts, loaded from package exports "./tui")
+  |  data.listen -> type filter -> directory guard (mirrors the built-in
+  |  tui.* handlers: the event routes by the coordinator instance's
+  |  directory) -> data.session.sync -> ui.tabs.open(sessionID)
+  v
+Tab strip: subordinate tab appears, unfocused
+```
+
+Key properties:
+
+- **v2-only by construction.** The ToolDef carries `v2Only: true`; the v1
+  adapter (`src/tools.ts`) and the MCP server (`src/mcp.ts`) filter it. The
+  system prompt lists the tool only when the runtime is built with
+  `v2Tools: true` - a prompt listing a nonexistent tool is the
+  first-call-mistake class.
+- **The event routes by the coordinator's location**, so the tab opens in
+  the coordinator's window under any `tabs.scope` - even when the session
+  lives in a worktree or temp dir. Tab ownership is by window, not by
+  session location.
+- **The move precedes the emit**: a failed move leaves no stranded open tab
+  (placement is identical either way because routing is by coordinator
+  location).
+- **No ack**: a headless run, a connecting TUI, or `tabs.mode: off` means
+  the event lands nowhere (harmlessly). The tool response says "tab
+  requested"; the session exists and is findable in the sessions list
+  regardless.
+- **The subordinate is a chat participant**, deliberately never marked
+  machinery: pre-registration (idempotent, like an explicit chat_register)
+  gives the coordinator its chat name in the tool response, and the
+  auto-register converges on the same name. Gated on the chat-enabled
+  config like every other registration path: with chat off the
+  subordinate still spawns, but no roster row is written and the tool
+  response reports no chat name. `validateTitle` rejects the
+  machinery title so `isMachinerySessionTitle` can never misfire. A
+  mid-flow failure (create, move, emit, prompt) throws with the created
+  session id and the completed steps in the message - v2 has no session
+  delete, so the stranded session can at least be named and reported.
+- **The worktree flow boots a second per-location thatch instance** (shared
+  db): the subordinate's pollers, nudges, extraction, wrap-up, and alerts
+  run in the worktree location's instance, and chat wake for the idle
+  subordinate depends on that instance being alive. The watcher poller
+  handoff is per location (`WatcherRegistry.#live` is keyed by directory):
+  the subordinate's instance booting never stops the coordinator's
+  poller - each location's instance polls only its own directory's
+  watchers. The pump caches the subordinate's location from the
+  tab-opened payload's directory field (its final, post-move directory),
+  never from the rpc envelope's location stamp (that is the publisher's
+  directory), so the subordinate's location-less execution events route
+  to the instance that owns it.
+
+## The cross-entry contract
+
+`src/session-tab-shared.ts` (SDK-free, per the isolation rule in
+`src/index.ts`) holds the rpc definition (`thatch-tabs`: `tab-opened`,
+`tab-closed` - the latter emitted by the close tool (below) and consumed
+by the generalized-session-heartbeat plan), the subordinate prompt builder,
+and the validators. The TUI entrypoint may import only
+`@opencode/plugin/tui` and this module.
+
+## Interactions
+
+- **Chat**: the subordinate registers in its final directory's repo slug (a
+  worktree resolves to the main checkout's slug), so coordinator and
+  subordinate share a chat scope across the move.
+- **Extraction/wrap-up/alerts**: the subordinate is a normal session owned
+  by its location's instance; the coordinator observes it via chat, not the
+  event pump (its post-move events fail the pump's directory filter
+  deliberately - the `childSessions` forwarding set is for extraction
+  children, and adding moved sessions would double-process their events).
+- **Session metadata**: the created session carries
+  `metadata.thatch.{coordinatedBy, coordinatorSessionID, worktree?}`. The
+  host inherits parent metadata onto children - the subordinate's own
+  extraction children carry the marker too; treat inherited markers as
+  inherited, not first-party.
+
+## Closing a subordinate's tab
+
+`thatch_session_tab_close {session}` (the target: the subordinate's chat
+name or session id, resolved name-first through the chat roster) emits
+`rpc.thatch-tabs.tab-closed {sessionID, chatName?}` over the same rpc
+bridge. The TUI plugin consumes it symmetrically with open: the directory
+guard applies, and `ui.tabs.close(sessionID)` closes the tab in every
+window showing one (windows not showing it no-op). Close is TAB-LEVEL: the
+session survives, the strip's reopen stack can restore it, and chat history
+is untouched.
+
+Two consumers ride the event: the death-detection machinery
+(generalized-session-heartbeat) treats a tool-initiated close as a
+CONFIRMED close - the closed session's watchers cancel immediately instead
+of waiting on the 2h delivery-failure heuristic - and the coordinator's own
+workflow closes dispatched subordinates once their work is verified. The
+pump routes the close by the CLOSED session's own directory (resolved from
+the pump's session-location cache, or live through the session API), not
+by the event's location stamp: the stamp names the publishing coordinator
+instance, while the watchers and status bookkeeping live in the instance
+that owns the session - its post-move location.
+
+## Install requirement (the `./tui` entrypoint)
+
+A local FILE plugin shim gets a `server` entrypoint only
+(`packages/core/src/plugin/module.ts` at v2), and the TUI's plugin discovery
+loads directories and symlinks, never plain files. The dev-checkout install
+must therefore be a directory shim (`thatch/index.ts` + `thatch/tui.ts`),
+and the old file shim must be DELETED in the same step - coexisting shims
+die with `duplicate instance plugin ids: thatch` before any plugin code can
+run. npm installs need the `exports` map to include `.` (the bare-specifier
+path) alongside `./tui`, and `@opencode/plugin` is an optional peer
+dependency for the TUI entry's runtime resolution.
+
+## Testing
+
+- Unit: `tests/session-tab-shared.test.ts` (validators, definition shape,
+  guard logic), `tests/opencode-v2.test.ts` (the execute flows' ordering via
+  the `makeContext` double with `session.move` + the `rpc` domain).
+- QA: uc-059 (tool list + MCP leak check), uc-014/uc-060 (skill counts),
+  uc-119 (the live spawn flow through the docker sandbox).
+- Live smoke (recorded 2026-10-08, ALL SCENARIOS PASSED): headless legs -
+  directory variant, worktree variant (the move persisted in the session
+  row + metadata), headless no-tab; TUI-visual legs (a real container
+  attach) - the subordinate's tab appeared unfocused, the title rendered,
+  the subordinate responded, and the persisted strip state matched; kill +
+  re-attach restored both tabs (restart persistence). Sandbox note: mkdir
+  the /qa host dir BEFORE `docker run -v` - a missing host path is created
+  inside the Docker VM, invisible to the mac.

package/docs/dev/features/setup.md

@@ -115,6 +115,11 @@ Cursor takes priority because Cursor also sets `CLAUDE_PROJECT_DIR` as an
 alias. Without the priority check, Cursor sessions would be misidentified as
 Claude Code.
 
+Separately, the project directory for store/chat identity resolution
+follows `THATCH_PROJECT_DIR ?? CURSOR_PROJECT_DIR ?? CLAUDE_PROJECT_DIR
+?? cwd` in the MCP server; project-local setups pin `THATCH_PROJECT_DIR`
+into the written MCP config.
+
 `checkSetup` looks for start and end markers in the host's instructions file
 --- `CLAUDE.md` for Claude Code, `AGENTS.md` for Cursor. It checks local first,
 then global. Local takes priority.

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