@jeffober/thatch 0.2.4 → 0.2.6

package/docs/dev/README.md

@@ -27,7 +27,7 @@ Shared core
   ├── git.ts          → detect repo identity (store name) + worktree-deletion recovery (repo_paths cache)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
   ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
-  ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
+  ├── commands.ts     → /thatch slash-command registry: actions (prompt cores + self-contained skill couchings) + wrap-ups, per-host sync
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
   ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
@@ -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,8 +89,9 @@ 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. |
-| `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. |
+| `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, session close-out - app exit on v1, the session's own tab on v2). `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. |
 | `setup.ts` | `thatch setup --claude` / `--cursor` installer. Writes MCP config (`.mcp.json` / `.cursor/mcp.json`), appends to CLAUDE.md / AGENTS.md (idempotent), installs hooks in settings.json / hooks.json, installs skills. |
@@ -98,15 +103,16 @@ 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). |
 | `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. The pool is the fallback base for registrations with no usable session title. |
+| `tab-state.ts` | Read-only open-tab reader for the chat roster: globs every opencode channel's `tabs.json` (global + cwd scopes), subtracts fresh confirmed tab closes, and composes the provider the roster surfaces and broadcast targeting consume. Degrades to an empty set - never a false OPEN. See [features/cross-session-chat.md](features/cross-session-chat.md). |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
-| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, plan-refinement, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions: the nudge-backed ones (defrag, extract, hygiene, reflect) from the prompt cores, and the self-contained ones (refine, whois, and the review-mode couchings peer-review, self-review) inline in the registry; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (everything that works on all three hosts: the memory workflows, the review specialists — whose roster comes from `REVIEW_SPECIALISTS` in prompts.ts — plus the synthesizer, context, followup, and response skills, the walkthrough and archaeology skills, the refinement family, the writing skills, and verification/export) and `OPENCODE_ONLY_SKILLS` (the code-review coordinator and thatch-coordination — they need sub-agent support, so they are not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |
@@ -124,7 +130,7 @@ methods. The v1 hook shapes:
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
-| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
+| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the host action (compact: v1 `session_compact` via `executeCommand`, v2 `session.compact` on the promise domain; exit: record the session's watcher deaths, unregister it from chat, then v1 `app.exit` via `publish` or v2 the exit-tab-closed rpc event closing the session's own tab). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
 | `chat.message` | Recall nudge: embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges fire independently in separate try/catch blocks with separate synthetic parts. There is deliberately NO extraction nudge here - extraction is plugin-driven at session idle (see the extraction feature doc); the old model-driven handshake raced its own state machine and was removed. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
@@ -263,14 +269,16 @@ extraction cycle
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks
 
-toast notifications (opencode-only, TUI-rendered)
+toast notifications (opencode-only, TUI-rendered; the bridge's toast
+  event -> the TUI plugin's ui.toast.show on v2)
   → client.tui.showToast — best-effort, silently ignored if TUI not
     connected (headless mode); model-invisible (goes to the user only,
     not the conversation history — the inverse of synthetic nudge parts,
     which are model-visible but TUI-hidden)
   → extraction metrics: `[thatch] new: N, updated: M, deleted: K` (success
-    variant, 4s) — fires when an extraction child goes idle; no-save runs
-    show `[thatch] extraction complete — nothing to save` (info variant)
+    variant, 4s) — fires when an extraction child goes idle, but ONLY when
+    memories were actually written; no-save runs show nothing (no
+    notification fatigue)
   → recall matches: `[thatch] recalled N memories` (info variant, 3s) —
     fires when chat.message matches stored memories
   → prediction matches: `[thatch] N predictions surfaced` (info variant,

package/docs/dev/features/README.md

@@ -23,7 +23,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
 | [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
-| [commands.md](commands.md) | Slash commands (on-demand actions from shared prompt cores, wrap-ups, host sync) |
+| [commands.md](commands.md) | Slash commands (on-demand actions: prompt cores and skill couchings, wrap-ups, host sync) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |

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

@@ -113,6 +113,8 @@ Parameters: `behavior` (statement, semantic match at cosine >= 0.85),
 - Injects `behaviorNudge(items)` as a separate synthetic text part with a
   `[thatch] Situational behaviors` header.
 - 0-evidence behaviors use "consider"; behaviors with evidence use "do".
+- The block ends with a snapshot footer (same as the prediction nudge): the
+  labels are a submission-time snapshot, not a live view.
 - Independent try/catch — a behavior failure does not block recall or
   prediction.
 - Toast: `[thatch] N behaviors surfaced`.
@@ -250,6 +252,14 @@ behavior_provenance(
 )
 ```
 
+Timestamp semantics: a matcher's `updated_at` is the last change to the
+matcher row OR its edge set — `createEdge` bumps it when a new edge lands
+(atomically with the insert), and deleting an item bumps the matchers whose
+edges cascade away (atomically with the delete). The matcher's own text may
+legitimately be older than its links (a corrected behavior re-links the
+existing matcher without touching its text). A behavior's `updated_at` is
+written at creation and then moved by the last confidence change.
+
 ## Key invariants
 
 1. **The firewall principle does NOT apply.** The LLM grading its own

package/docs/dev/features/cli.md

@@ -51,7 +51,8 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
   (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
   text). Rows are split into Active and Stale sections by
   `splitChatRoster()`; the status column is `chatLiveness()`'s verdict
-  (`fresh`/`stale` for opencode rows, `active`/`idle` for MCP rows).
+  (`open`/`recent`/`stale` for opencode rows - the open-tab reader feeds
+  the open/recent split - `active`/`idle` for MCP rows).
 - `chat tail` follows the message stream as JSONL: one `ChatTailEvent`
   per line via `formatChatTailJsonl()` (a bare `JSON.stringify`; no ANSI,
   no markdown rendering, no local-time conversion - the tail is a log for
@@ -88,6 +89,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/commands.md

@@ -2,8 +2,11 @@
 
 Thatch's `/thatch/*` commands come in two families:
 
-- **Actions** (`defrag`, `extract`, `hygiene`, `reflect`) — user-invoked
-  wrappers around behaviors the nudges otherwise run on their own schedule.
+- **Actions** (`defrag`, `extract`, `hygiene`, `peer-review`, `refine`,
+  `reflect`, `self-review`, `whois`) — user-invoked commands. The
+  nudge-backed ones (`defrag`, `extract`, `hygiene`, `reflect`) wrap
+  behaviors the nudges otherwise run on their own schedule; the rest
+  are self-contained, with no nudge counterpart.
 - **Wrap-ups** (`compact`, `exit`) — greenlight-gated pre-compaction and
   pre-exit checklists. opencode only: the greenlight check needs the
   plugin's `command.execute.before` arming and TUI control routes.
@@ -12,11 +15,12 @@ User-facing guide: [../../user/commands.md](../../user/commands.md).
 
 ## Prompt cores
 
-Action bodies are **prompt cores**: constants in `src/prompts.ts`
-(`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) that hold the
-host-agnostic instruction text for one behavior. The nudge envelopes wrap
-the same cores with escalation tiers and the stop-and-wait ending; command
-and prompt renderers wrap them with frontmatter and a user-message section.
+The nudge-backed action bodies are **prompt cores**: constants in
+`src/prompts.ts` (`defragCore`, `hygieneCore`, `reflectCore`,
+`extractionCore`) that hold the host-agnostic instruction text for one
+behavior. The nudge envelopes wrap the same cores with escalation tiers
+and the stop-and-wait ending; command and prompt renderers wrap them with
+frontmatter and a user-message section.
 The point is drift-proofing: a wording change lands in the nudge and the
 command at once, and a test asserts each rendered file contains its core
 verbatim.
@@ -30,13 +34,40 @@ per host: `thatch_find_duplicates` on opencode, `mcp__thatch__find_duplicates`
 on MCP hosts. Each host's renderer passes its own namer
 (`opencodeToolName` / `mcpToolName`).
 
+## Skill-couching actions
+
+A command body can **couch** a skill: wrap the skill's procedure with the
+additional instructions the command needs. `refine`, `peer-review`,
+`self-review`, and `whois` are not prompt cores: they have no nudge
+counterpart to stay in sync with, so their bodies live directly in
+`actionDefs` (src/commands.ts). `refine` triggers the `thatch-refine`
+router skill and `whois` prints the chat identity; neither applies an
+overlay.
+
+`peer-review` and `self-review` share one pipeline couching
+(`reviewPipelineCouching` in src/commands.ts): run the code review
+machinery — the `thatch-code-review` coordinator where that skill is
+installed (opencode), the inline specialist sequence where it is not
+(Claude Code, Cursor) — and apply a mode overlay that reweights the
+findings for whose work is under review. The roster and count for the
+inline sequence come from `REVIEW_SPECIALISTS` in src/prompts.ts, the
+same source as the install list in src/skills.ts and both host
+instruction skill lists. `peer-review` weights org
+velocity and walks the project's persistent memory (the one tool it
+names, spelled through the `ToolNamer` so MCP renderings stay correct);
+`self-review` weights the reputation lenses (no-slop, technique,
+breadcrumbs) and iterates rounds until a round produces no meaningful
+findings. The couching also names the MCP `Focus:` line as a target
+source, because MCP prompts replace the file commands' `$ARGUMENTS`
+section with a `Focus:` line.
+
 ## Rendering and sync
 
 `src/commands.ts` is the single registry:
 
 - `actionDefs(tool)` returns the action set with bodies rendered for one
   host. Actions needing plugin-only capabilities are marked `opencodeOnly`
-  (`extract`: needs session identity via `get_session_info`).
+  (`extract` and `whois`: they need the invoking session's identity).
 - `opencodeCommandDefs()` = wrap-up templates + all actions. Synced by the
   plugin at init into `$XDG_CONFIG_HOME/opencode/command/thatch/`
   (`installOpencodeCommands`), content-compare, self-healing.
@@ -52,7 +83,7 @@ on MCP hosts. Each host's renderer passes its own namer
 
 A parity-guard test asserts the three sets are the same actions minus the
 documented exclusions: opencode = Claude Code set + `compact`, `exit`,
-`extract`; MCP prompts = Claude Code's set.
+`extract`, `whois`; MCP prompts = Claude Code's set.
 
 ## The extract action and session IDs
 

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
@@ -123,10 +146,10 @@ mechanical barrier, a documented trust posture.
 ### Leave tombstones
 
 Every exit path - `chat_unregister`, `session.deleted`, and a greenlit
-`/thatch/exit` (the plugin unregisters the exiting session before
-publishing `app.exit`, so the roster stops advertising a host that is
-about to vanish; the exit template's checklist step asks the model to do
-the same earlier) - writes a
+`/thatch/exit` (the plugin unregisters the exiting session before the
+host close-out - v1 publishes `app.exit`, v2 closes the session's own
+tab - so the roster stops advertising a host that is about to vanish)
+- writes a
 `chat_leave_tombstones` row in the same transaction that deletes the
 directory row. The tombstone is what makes a leave stick: all
 registration paths consult it (the plugin's idle and prompt auto-registerers are
@@ -168,15 +191,78 @@ 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. Opencode rows
+are skipped and reported unless they are OPEN (fresh heartbeat AND a tab
+open now, per the open-tab reader below): a host that has stopped
+heartbeat-ing will never read the mail, and a fresh-but-tab-less session's
+wake can be swallowed without running a turn, so messaging it would spend
+a model turn on a delivery that likely never fires. MCP sessions always
+receive (they read mail at their next prompt). Every skip is listed by
+name in the result's `skipped` field. 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, skip classes, 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
 
@@ -188,7 +274,8 @@ fires no `session.deleted`, so its rows would linger - staleness catches
 them: a row that has missed two consecutive beats (`CHAT_STALE_MS`, 60s
 at the default interval) is stale, meaning its harness stopped. Two beats
 rather than one so a single late poll cycle does not flap the roster.
-Heartbeat age is the ONLY liveness signal, by design. A host process id
+Heartbeat age is the only WRITTEN liveness signal, by design (the tab
+reader below is read-only). A host process id
 cannot serve: the same session is re-hosted by a new process on every
 `-s` resume, so a pid stamped on the row lies as soon as a different
 harness beats it (it says dead while the heartbeat proves alive). RESTART
@@ -199,12 +286,43 @@ into, so without the grace they would read stale while alive-idle and
 mail to them would not wake the tab. Sessions that emit activity
 graduate to permanent hosting; still-silent ones (closed tabs) age out
 at the grace and go stale. `isStale`
-(src/chat.ts) is the single rule; `chatLiveness`, the `chat_send` note,
-and the broadcast skip all call it, so they cannot disagree. `chat_list`
+(src/chat.ts) is the single staleness rule; `chatLiveness`, the `chat_send`
+note, and the broadcast skip all call it, so they cannot disagree.
+
+### The open-tab reader: OPEN vs RECENT
+
+Heartbeat age alone conflates presence with recency: a finished
+conversation stays fresh until its directory's instance stops beating it
+(days), and a closed tab leaves a fresh row. The refinement is a READ-ONLY
+second signal, `src/tab-state.ts`: at roster render and broadcast time,
+glob `<XDG_STATE_HOME>/opencode/*/tui/tabs.json` (one file per release
+channel - "latest" today, hence the glob), parse BOTH scope modes
+(`global.tabs` and per-path `cwd.*.tabs`; the scope depends on opencode's
+`tabs.scope` config), and build the set of sessionIDs carrying a tab.
+Missing files, bad JSON, and absent state trees degrade to an empty set -
+an unknown tab state never reads as OPEN. `chatLiveness` takes the set and
+returns `open` (fresh + tab), `recent` (fresh + no tab), `stale`;
+MCP rows keep `active`/`idle`. Callers compose the raw set with confirmed
+tab closes via `effectiveOpenTabs` (`chatOpenTabs` is the wired provider):
+the `session.tab_closed` bridge event (the session_tab tool's confirmed
+close) writes a `chat_tab_closed` runtime_state marker, and a FRESH marker
+(inside `CHAT_TAB_CLOSED_OVERRIDE_MS`, 2 staleness windows) subtracts the
+session from the set - so a residue tabs.json row cannot read OPEN right
+after a confirmed close. The marker self-expires (the death path stops the
+heartbeat, so the row goes stale on heartbeat age regardless) and is
+superseded by any later beat.
+
+Known limits, accepted: a killed window leaves tab rows behind (the file
+is restart persistence by design), so dead-window residue reads OPEN until
+its heartbeat ages out; tabs disabled degrades everything to RECENT.
+
+`chat_list`
 groups the result into Active and Stale sections - the stale section's
-explainer says what stale means - and `chat_send` states the recipient's
+explainer says what stale means, and each row renders its verdict -
+and `chat_send` states the recipient's
 liveness at send time, so a sender mailing a ghost learns it immediately
-instead of waiting on a wake that will never fire. Both roster surfaces
+instead of waiting on a wake that will never fire, and a sender mailing a
+tab-less session is told the wake is not guaranteed. Both roster surfaces
 order rows with `sortChatRoster` (also src/chat.ts): project first,
 alphabetical, with no-project rows last; most recently seen first within
 a project. The CLI roster bounds
@@ -231,6 +349,22 @@ and a count, pointer-only like watcher notifications, with the model calling
 `chat_read` for content. On success the poller stamps `delivered_at`
 (re-stamping on re-nudges resets the re-nudge timer).
 
+Before any wake attempt runs, the delivery guard (`guardDelivery` in
+`src/runtime.ts`) checks that the runtime instance's own directory - the
+bound directory of every session it hosts - still exists. A deleted
+worktree (merged branch) would otherwise error every attempt, and opencode
+surfaces that error to the user as a toast. The guard skips the attempt
+with a `runtime:delivery` debug line instead, leaving the mail queued; the
+check is per attempt, so a worktree recreated at the same path resumes
+delivery. The existence check cannot say why a path is absent (deleted
+tree, broken symlink, parent permission), so any miss classifies as gone -
+deliberate, because surfacing non-ENOENT errors through the attempt would
+buy the toast back for no recovery the pending-and-retry cycle does not
+already provide. The guard wraps `promptSession` in
+`createRuntime`, which covers chat nudges, watcher notifications and death
+notices, rehydrate pings, chat echoes, and extraction dispatch at once;
+MCP hosts never build a runtime, so they are unaffected.
+
 The hard brake: at most a fixed number of wake prompts per recipient per
 hour (default 6, in-memory on purpose - it is a loop guard, not accounting).
 Without it, two agents politely acknowledging each other would ping-pong
@@ -360,11 +494,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
@@ -382,21 +528,43 @@ caller's identity and mailbox, and is absent entirely when chat is
 disabled - absence is silent by construction.
 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).
+"between turns" (broadcast always delivers). Broadcast also skips fresh
+opencode rows with no open tab (see the open-tab reader) - the skip
+classes are reported by name either way.
+
+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, confirmed-close override window two
+staleness windows (`CHAT_TAB_CLOSED_OVERRIDE_MS` in `src/tab-state.ts`).
+Environment overrides: `THATCH_CHAT_SPLIT_PART_LEN`
+(auto-split part budget, default 2000, clamped 500..9000),
+`THATCH_CHAT_MAX_BODY_CHARS` (whole-body acceptance ceiling, default 20000), and
+`THATCH_OPENCODE_STATE_ROOT` (the open-tab reader's state root, tests and
+QA sandboxes only);
+the split constants are resolved once at module load and sanitized to positive integers
+within their clamps - invalid values silently fall back to the default.
 
 ## Source files
 
 - `src/chat.ts` - ChatStore (directory + inbox SQL, assigned-name draw:
-  pool pick, slugify, counter bump, insert, prune, topic refresh), ChatPoller
+  pool pick, slugify, counter bump, insert, prune, topic refresh, broadcast
+  targeting), ChatPoller
   (heartbeat, gated delivery, re-nudge, rate cap, hourly prune sweep),
-  staleness helper
+  staleness helper, chatLiveness (the open/recent/active/idle/stale
+  verdicts)
+- `src/tab-state.ts` - the read-only open-tab reader: per-channel
+  tabs.json glob (global + cwd scopes), confirmed-close override window,
+  the composed open-tabs provider
 - `src/chat-names.ts` - the static display-name pool (nomenclater style),
   the base for every assigned name
 - `src/db.ts` - the chat tables in schema init (including
@@ -418,5 +586,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/database.md

@@ -96,7 +96,7 @@ prediction_matchers(
   embedding BLOB,
   model TEXT,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- last change to the matcher row or its edge set
 )
 ```
 
@@ -116,7 +116,7 @@ predictions(
   confirm_count REAL NOT NULL DEFAULT 0,
   disconfirm_count REAL NOT NULL DEFAULT 0,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- written at creation, then last confidence change
 )
 ```
 
@@ -167,7 +167,7 @@ behavior_matchers(
   embedding BLOB,
   model TEXT,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- last change to the matcher row or its edge set
 )
 ```
 
@@ -185,7 +185,7 @@ behaviors(
   confirm_count REAL NOT NULL DEFAULT 0,
   disconfirm_count REAL NOT NULL DEFAULT 0,
   created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
+  updated_at TEXT NOT NULL -- written at creation, then last confidence change
 )
 ```
 

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/nudge-pipeline.md

@@ -131,6 +131,20 @@ Tiers 2, 3, and 4 all fire independently. Any subset may inject. All share
 one embedding computation, reused across three cosine scans against
 different tables.
 
+#### Snapshot semantics
+
+A nudge block is computed once, when the message is submitted, and stays
+attached to that message for the whole turn - including every model round
+trip after mid-turn tool calls. Predictions, behaviors, or memories the
+conversation mutates mid-turn do NOT refresh an already-injected block
+(v1: the synthetic part lives on the stored message; v2:
+`pendingInjections` re-injects the prompt-time text into every outbound
+request of the turn, bound to the message it was computed for - see
+[opencode-plugin.md](opencode-plugin.md)). The prediction and behavior
+blocks therefore end with a snapshot footer naming the store state they
+reflect and the live tool to re-check. The recall nudge carries no footer:
+it lists memory labels without confidence claims.
+
 ### MCP path (`bin/thatch`, `flush-tools` subcommand)
 
 The `flush-tools` subcommand fires on `UserPromptSubmit` (Claude Code) or