@jeffober/thatch 0.2.3 → 0.2.5

package/docs/dev/README.md

@@ -45,6 +45,10 @@ OpenCode plugin path
   │                     lazy-imports the adapter matching the host
   ├── opencode/v1.ts  → v1 adapter: @opencode-ai/plugin hooks object
   ├── opencode/v2.ts  → v2 adapter: @opencode/plugin promise-context domains
+  ├── opencode/tui-plugin.ts → v2 TUI CLI plugin (./tui entrypoint):
+  │                     consumes the session-tab rpc events, drives ui.tabs
+  ├── session-tab-shared.ts → SDK-free cross-entry contract: session-tab rpc
+  │                     definition, subordinate prompt builder, validators
   ├── capabilities.ts → HostCapabilities seam: the host operations the
   │                     runtime needs; capabilitiesFromClient bridges the
   │                     v1 SDK client
@@ -85,7 +89,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `tools.ts` | Thin opencode wrappers. `buildCoreContext` constructs the shared per-call context; `createTools` wraps each tool-def in opencode's `tool()` with a `thatch_` prefix (v1 only). |
 | `mcp.ts` | Stdio JSON-RPC 2.0 server. Compiles zod schemas to JSON Schema via `z.toJSONSchema()` for `tools/list`. Validates args via `z.object().parse()` in `tools/call`. All logging to stderr (stdout is the transport). |
 | `index.ts` | Dual-shape OpenCode plugin entry: the merged default export (`{ id, setup, server }`) loads on opencode v1 (reads `default.server`) and v2 (reads `default.setup`, strips excess keys). Lazy-imports the host adapter so each host's SDK resolves only under its own runtime. |
-| `opencode/v1.ts` + `opencode/v2.ts` | Host adapters. v1 builds HostCapabilities from the PluginInput client and returns the hooks object; v2 registers through the promise-context domains (ToolEditor, session.hook, event.subscribe) and degrades the surfaces v2 lacks. |
+| `opencode/v1.ts` + `opencode/v2.ts` | Host adapters. v1 builds HostCapabilities from the PluginInput client and returns the hooks object; v2 registers through the promise-context domains (ToolEditor, session.hook, event.subscribe) and degrades the surfaces v2 lacks. v2 also wires the session-tab host flow (create -> move -> chat-register -> rpc emit -> prompt) through the `CoreContext.sessionTabHost` seam. |
+| `opencode/tui-plugin.ts` | The v2 TUI CLI plugin (the package's `./tui` entrypoint): listens for `rpc.thatch-tabs.tab-opened` and `rpc.thatch-tabs.tab-closed` events and opens/closes the subordinate session's tab via `ui.tabs.open`/`ui.tabs.close`. See [features/session-tabs.md](features/session-tabs.md). |
 | `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, compaction trigger, app exit). `capabilitiesFromClient` bridges the v1 SDK client. |
 | `runtime.ts` | Shared plugin runtime: wires DB, model, extraction; the nudge tiers, system prompt injection, session event handling, child-session bookkeeping, wrap-up resolution. Host-agnostic: consumed by both adapters. |
 | `os-args.ts` | Pure argv / OS-command-line helpers for startup session resolution (`-s`/`-c`). SDK-free. |
@@ -98,7 +103,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
 | `config.ts` | User config file (`~/.config/thatch/config.json`, beside the DB): Zod section schemas (strict — unknown keys fail validation), load with missing/invalid fallback to defaults, field-level merge, atomic save (temp + rename). Backs the `config_get`/`config_set` tools. |
 | `notify.ts` | Out-of-band notification dispatch: darwin (`osascript` banner + `/usr/bin/say` voice), linux (`notify-send` + `spd-say`/`espeak`), other platforms report unsupported. Injectable spawner (`CoreContext.spawner`) so tests never fire real commands. Backs the `notify_user` tool and the alert state machine. |
-| `alerts.ts` | LLM alert state machine (opencode-only): pause/done/error decisions from session events, per-session dedup (no timer-based debounce - one alert per busy->idle transition, per request id for pauses). Fed by `runtime.ts`'s event hook; delivers through `notify.ts`. Plain memory by design (a reload loses at most one transition). See [../plans/llm-alerts.md](../plans/llm-alerts.md). |
+| `alerts.ts` | LLM alert state machine (opencode-only): pause/done/error decisions from session events, per-session dedup (no timer-based debounce - one alert per busy->idle transition, per request id for pauses). Fed by `runtime.ts`'s event hook; delivers through `notify.ts`. Plain memory by design (a reload loses at most one transition). See [features/notifications.md](features/notifications.md). |
 | `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
 | `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Three sources: GitHub PRs and branches via `gh api` (injected `GhRunner`), and local shell commands via `bash -c` (injected `CommandRunner`) run as condition variables - only the exit code is read, never the command's output. Diffs against last-seen state, queues events (pointer data plus machine status like check conclusions and exit codes, never external content) per session, and delivers them through a plugin-supplied callback when the session is idle. The `pollSeconds` getter surfaces the poll cadence to tool output and notifications. Process-lifetime state by design - no SQLite. |
 | `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |

package/docs/dev/features/cli.md

@@ -88,6 +88,8 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 | `THATCH_CHILD_RECONCILE_MS` | Reload window before a restored extraction child is judged finished (test knob) | `10000` |
 | `CLAUDE_PROJECT_DIR` | Claude Code project dir | `process.cwd()` |
 | `CURSOR_PROJECT_DIR` | Cursor project dir | falls through |
+| `THATCH_WATCH_DEATH_MINUTES` | Pending-age threshold for watcher death detection | `120` |
+| `THATCH_PROJECT_DIR` | Pinned project dir (written by project-local `thatch setup` MCP configs) | falls through |
 | `CLAUDE_CONFIG_DIR` | Claude config dir | `~/.claude` |
 | `CURSOR_CONFIG_DIR` | Cursor config dir | `~/.cursor` |
 | `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` | Enable async extraction | unset |

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

@@ -18,6 +18,8 @@ resolution fit together.
   hooks, and skills for Cursor
 - `--global` flag --- installs to user-scoped config dirs instead of
   project-local
+- `--skills-only` flag --- refreshes just the skill files (same host and
+  scope rules), skipping MCP config, instructions, hooks, and commands
 - **Marker system** --- idempotent replacement of the thatch instruction block
   in `CLAUDE.md` or `AGENTS.md` via start/end markers
 - **`checkSetup`** --- detects installed, not-installed, or markers-broken at
@@ -35,6 +37,11 @@ resolution fit together.
 
 At least one of `--claude` or `--cursor` is required. Both can be passed
 together. `--global` applies to whichever host or hosts are selected.
+`--skills-only` narrows the run to the skill install (`setupSkillsOnly`
+in `src/setup.ts`): it reuses the same path resolution and other-scope
+probe as the full setup paths but only calls `installSkills`, so it is
+safe to run in an already-set-up host when only the skill files need
+refreshing.
 
 ### Claude Code setup (`setupClaudeCode` in `src/setup.ts`)
 
@@ -108,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.