@jeffober/thatch 0.1.48 → 0.2.0

package/README.md

@@ -21,7 +21,10 @@ everything runs on your machine.
 ```
 
 On next start, OpenCode npm-installs thatch and its tools are available
-immediately. For async extraction (child sessions run in the background):
+immediately. Works with both opencode 1.x and 2.x (the same package supports
+both plugin APIs). Until the next release ships, npm's `latest` still
+targets 1.x only. For async extraction (child sessions run in the
+background):
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
@@ -30,6 +33,39 @@ export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 Without this env var, extraction still works - the child session runs
 synchronously (fire-and-forget) instead of asynchronously.
 
+### What works in opencode 2.x
+
+The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
+
+- **No toasts.** Toasts are dropped on v2 (no publish surface). The
+  model-facing nudges they accompanied - watcher and chat wake nudges -
+  still arrive; the extraction-result and other TUI-only toasts have no
+  replacement.
+- **Plugin state survives reloads.** Editing the plugin (or `opencode
+  plugin update`) reloads it, but extraction buffers, watcher
+  registrations, and armed wrap-ups are journaled and restored; a process
+  restart restores the state of a resumed (`-c`/`-s`) session. Other
+  sessions' watcher registrations survive as dormant definitions: resuming
+  such a session re-arms its watches on the first message (expired ones
+  are dropped and reported), and a live session in the same project gets a
+  one-line notice that a dead session's watch will re-arm if resumed.
+- **Extraction children are visible.** The fact-extractor child sessions are
+  top-level sessions the host cannot delete, so they accumulate in the
+  session picker, and "continue last session" (`-c`) can land in one after
+  any session that triggered extraction.
+- **`/thatch/compact` does not auto-compact.** The checklist and memory
+  flush run, but the compaction itself cannot be triggered from the plugin
+  API - run `/compact` yourself after the wrap-up completes. `/thatch/exit`
+  cannot auto-exit for the same reason.
+- **No `-c` session listing.** The chat resume listing degrades.
+
+Everything else - tools, memory, nudges, chat, watchers - behaves the
+same on both versions, with one caveat: v2 has no turn-free delivery
+(noReply), so the features that lean on it - the chat transcript echo
+bubble, the session-start reminder, and the post-reload re-attach
+notice - do not render on 2.x. Their model-facing content still
+arrives; only the bubble rendering is lost.
+
 Then **prime your project memory** by running `thatch prime` in your project directory.
 This launches an `opencode` session to build an initial map of the code base
 and seed the memory.
@@ -169,10 +205,13 @@ Thatch gives your agent:
   the agent lists them and nothing fires -- you decide when to retry.
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
-  announcement, or both (macOS and Linux). Preferences live in a
+  announcement, or both (macOS and Linux). On opencode, thatch also watches
+  the session and alerts you automatically when the LLM pauses for your
+  input (a question or permission prompt) or finishes a round of real work
+  -- bookkeeping rounds stay silent. Preferences live in a
   hand-editable config file (`~/.config/thatch/config.json`) that the agent
-  manages through `config_get`/`config_set` -- ask it to change your voice
-  or quiet notifications entirely.
+  manages through `config_get`/`config_set` -- ask it to change your voice,
+  quiet notifications entirely, or tune which alerts fire.
 
 Plus **skills** for memory workflows, structured multi-specialist code
 review, review response, plan refinement, change and feature walkthroughs,

package/bin/thatch

@@ -49,11 +49,13 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
-  thatch chat list [--stale N|all]  Registered chat sessions, grouped Active/Stale:
-                                    name, age, status, project, topic.
-                                    --stale N (days) hides stale sessions
-                                    older than N; default 1. --stale all
-                                    shows every stale session.
+  thatch chat list [--stale N|all]  Registered chat sessions. Default shows
+                                    only active (fresh-heartbeat) sessions:
+                                    name, session id, age, status, project,
+                                    topic. --stale adds the stale section:
+                                    N bounds it to sessions seen in the
+                                    last N days (default 1); all shows
+                                    every stale session.
   thatch chat tail [--once] [--limit N|all] [--match RE]
                    [--from NAME] [--to NAME] [--since DT] [--until DT]
                                    Follow cross-session chat as a JSONL
@@ -415,7 +417,7 @@ async function sessionCommand(rest: string[]): Promise<void> {
 // ---------------------------------------------------------------------------
 
 /** Column headers for the `chat list` roster, in display order. */
-const CHAT_ROSTER_HEADER = ["NAME", "AGE", "STATUS", "PROJECT", "TOPIC"];
+const CHAT_ROSTER_HEADER = ["NAME", "SESSION ID", "AGE", "STATUS", "PROJECT", "TOPIC"];
 
 /**
  * Renders the `chat list` roster as two sections - Active and Stale - each
@@ -436,6 +438,7 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
   const renderTable = (rows: ChatSessionRow[]) => {
     const cells = (r: ChatSessionRow) => [
       r.name,
+      r.session_id,
       humanAge(r.last_seen),
       chatLiveness(r),
       r.project ?? "unknown",
@@ -447,9 +450,10 @@ function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null
     const align = (line: string[]) => line.map((c, i) => (i < line.length - 1 ? c.padEnd(widths[i]) : c));
     const header = align(CHAT_ROSTER_HEADER).map((h) => paint("1", h)).join("  ");
     const body = rows.map((r) => {
-      const [name, age, status, project, topic] = align(cells(r));
+      const [name, sessionID, age, status, project, topic] = align(cells(r));
       return [
         paint("32", name),
+        paint("2", sessionID),
         paint("2", age),
         paint(status === "stale" ? "31" : "32", status),
         project,
@@ -491,21 +495,32 @@ async function chatCommand(rest: string[]): Promise<void> {
       // sessions from burying the fresh signal. --stale all restores the
       // unbounded view. A bad value dies loudly rather than silently
       // shrinking the roster.
-      const staleArg = flagValue(restArgs, "--stale");
+      // Default: active sessions only. --stale [N|all] opts into the
+      // stale section - bare --stale keeps the one-day display cap, N
+      // bounds it, all removes it. The value is parsed by hand (not
+      // flagValue) because bare --stale is meaningful.
+      const showStale = restArgs.includes("--stale");
+      const staleIdx = restArgs.indexOf("--stale");
+      const staleNext = showStale ? restArgs[staleIdx + 1] : undefined;
       let staleCapMs: number | null = 24 * 60 * 60 * 1000;
-      if (staleArg !== undefined) {
-        if (staleArg === "all") staleCapMs = null;
-        else if (!/^\d+(\.\d+)?$/.test(staleArg) || Number(staleArg) <= 0) {
-          console.error(`error: --stale expects a positive number of days or "all", got "${staleArg}"`);
+      if (staleNext !== undefined) {
+        if (staleNext === "all") staleCapMs = null;
+        else if (!/^\d+(\.\d+)?$/.test(staleNext) || Number(staleNext) <= 0) {
+          console.error(`error: --stale expects a positive number of days or "all", got "${staleNext}"`);
           process.exit(1);
-        } else staleCapMs = Number(staleArg) * 24 * 60 * 60 * 1000;
+        } else staleCapMs = Number(staleNext) * 24 * 60 * 60 * 1000;
       }
-      const sessions = db.listChatSessions();
+      let sessions = db.listChatSessions();
+      if (!showStale) sessions = sessions.filter((r) => chatLiveness(r) === "fresh");
       if (sessions.length === 0) {
-        console.log("No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register.");
+        console.log(
+          showStale
+            ? "No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register."
+            : "No active sessions. (Stale sessions are hidden; run with --stale to include them.)",
+        );
         break;
       }
-      console.log(formatChatRoster(sessions, staleCapMs));
+      console.log(formatChatRoster(sessions, showStale ? staleCapMs : null));
       break;
     }
 

package/docs/dev/README.md

@@ -1,5 +1,7 @@
 # Development
 
+Feature docs describe behavior in opencode v1 `client.*` terms; the opencode v2 equivalents and degrades are catalogued in [features/opencode-plugin.md](features/opencode-plugin.md).
+
 ## Architecture
 
 Thatch has three integration paths sharing a common core:
@@ -38,8 +40,21 @@ Shared core
   └── vector-math.ts  → blobToVector + cosineSimilarity helpers
 
 OpenCode plugin path
-  ├── index.ts        → plugin entry: wires DB/model/extraction, registers tools + hooks
-  ├── tools.ts        → thin opencode tool() wrappers over tool-defs
+  ├── index.ts        → dual-shape plugin entry: merged default export
+  │                     ({id, setup, server}) loads on opencode v1 AND v2;
+  │                     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
+  ├── capabilities.ts → HostCapabilities seam: the host operations the
+  │                     runtime needs; capabilitiesFromClient bridges the
+  │                     v1 SDK client
+  ├── runtime.ts      → shared plugin runtime: nudges, system prompt
+  │                     injection, session events, extraction triggers,
+  │                     child-session bookkeeping (host-agnostic)
+  ├── os-args.ts      → pure argv/OS-command-line helpers (startup session
+  │                     resolution; SDK-free)
+  ├── tools.ts        → thin opencode tool() wrappers (v1); tool-defs.ts
+  │                     owns buildCoreContext (shared per-call context)
   ├── extraction.ts   → in-memory ring buffer + shared payload builders
   ├── watchers.ts     → in-memory watcher registry + poller (opencode-only,
   │                     event-driven PR notifications delivered as prompts)
@@ -67,9 +82,13 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | Module | Responsibility |
 |--------|---------------|
 | `tool-defs.ts` | **Single source of truth** for all tools. Each tool has a name, description, zod schema (args), and execute function. Framework-agnostic — neither opencode nor MCP specific. |
-| `tools.ts` | Thin opencode wrappers. Imports tool-defs, wraps each in opencode's `tool()` with a `thatch_` prefix. |
+| `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` | OpenCode plugin entry. Wires DB, model, extraction; registers tools and hooks; installs skills. Internal state beyond the extraction pipeline: `extracting` set (parent IDs with an active direct-extraction child), `childMetrics` map (new/updated/deleted counts per child session), and `triggerExtraction(parentID)` (creates a child session via the SDK client and prompts it with the extraction payload). |
+| `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. |
+| `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. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain, plus recovery from the `repo_paths` cache when the directory is deleted, and the spawn-cwd fallback. See [features/repo-identity.md](features/repo-identity.md). |
@@ -78,7 +97,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `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. |
+| `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). |
 | `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). |
@@ -96,7 +116,9 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 
 ## Plugin hooks
 
-`index.ts` registers these opencode integration points:
+The v1 adapter (`src/opencode/v1.ts`) registers these opencode integration
+points; the v2 adapter routes its domain hooks into the same shared runtime
+methods. The v1 hook shapes:
 
 | Hook | What it does |
 |------|-------------|

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

@@ -128,8 +128,9 @@ Parameters: `behavior` (statement, semantic match at cosine >= 0.85),
 
 ### Default behavior seeding (`src/seed-behaviors.ts`)
 
-Runs at startup in both the opencode plugin (`src/index.ts`) and the MCP
-server (`src/mcp.ts`), after DB and model initialization.
+Runs at startup in both the opencode plugin (`src/runtime.ts`, shared by
+the v1 and v2 adapters) and the MCP server (`src/mcp.ts`), after DB and
+model initialization.
 
 Seeds multiple default behaviors into the global store — session wrap-up
 (check for uncommitted changes, untracked files, stale artifacts), work

package/docs/dev/features/cicd.md

@@ -13,7 +13,7 @@ The CI gate is the never-merge-broken guard before a release. All three must pas
 
 ## Publish pipeline (.github/workflows/publish.yml)
 
-Triggered by pushing a `v*` tag. Publishes to npm via OIDC trusted publishing — no stored npm token.
+Triggered by pushing a `v*` tag. Publishes to npm via OIDC trusted publishing — no stored npm token. The tag push does not trigger ci.yml, so the publish workflow re-runs the full CI gate (typecheck, tests, markdownlint) across the same dual-Bun matrix as its own release gate.
 
 Key details:
 - `id-token: write` permission lets npm authenticate through GitHub's OIDC exchange

package/docs/dev/features/compaction-recovery.md

@@ -37,7 +37,7 @@ During summary generation, tools are blocked. A nudge that instructs the agent t
 
 ## Source files
 
-- `src/index.ts` -- all four hooks/events (experimental.session.compacting, experimental.compaction.autocontinue, session.compacted event, chat.message compaction guard)
+- `src/runtime.ts` -- all four hooks/events (experimental.session.compacting, experimental.compaction.autocontinue, session.compacted event, chat.message compaction guard on v1; session.hook("compaction")/("prompt") on v2), shared by both adapters
 - `src/prompts.ts` -- compactionContext function
 
 ## Key invariants

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

@@ -1,5 +1,7 @@
 # Cross-Session Chat
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 Cross-session chat lets independent opencode sessions on one machine message
 each other through thatch: sessions join a shared directory (automatically,
 under assigned names), see each other in the list, and messages land in
@@ -394,8 +396,8 @@ them the way `THATCH_WATCH_POLL_SECONDS` works if a user needs them.
   chat_name_counters and the auto column), the NOCASE collation migration
   and topic column migration, delegated methods
 - `src/tool-defs.ts` - the chat tool definitions
-- `src/index.ts` - poller construction, delivery closure, `-s` startup
-  registration (`osProcessArgs`, `startupSessionId`), idle
+- `src/runtime.ts` - poller construction, delivery closure, `-s` startup
+  registration (`osProcessArgs`, `startupSessionId` from `src/os-args.ts`), idle
   auto-registration + topic refresh, idle flush,
   session.deleted unregister, dispose, transcript echo in
   tool.execute.after

package/docs/dev/features/extraction.md

@@ -36,7 +36,7 @@ directly for conversation-derived knowledge.
 After every tool execution, non-`thatch_*`, non-`skill`, non-`task` tool
 calls are buffered for later extraction.
 
-**opencode** — `tool.execute.after` hook in `src/index.ts`:
+**opencode** — `tool.execute.after` hook (v1) / `tool.hook` (v2) in `src/runtime.ts`:
 
 - In-memory ring buffer per session (`ExtractionPipeline` in
   `src/extraction.ts`)
@@ -50,6 +50,14 @@ calls are buffered for later extraction.
   itself; `skill`/`task` meta-tools would create a feedback loop (extraction
   triggers a skill load, which gets buffered, which triggers another
   extraction)
+- Code Mode `execute` calls are **unwrapped before filtering**
+  (`unwrapExecuteThatchCalls` in `src/extraction.ts`): when the call's code
+  invokes `tools.thatch_*` tools, the wrapped tools' hook semantics run
+  (ack, drain, metrics) and the call itself is never buffered. Matching on
+  the outer tool name alone re-queued the pipeline's own dispatch/ack
+  traffic every cycle — each extraction run queued the next one, producing
+  an infinite dispatch/ack loop (observed live, September 2026). Execute
+  calls that touch no thatch tools buffer as normal.
 
 **MCP hosts** — `bin/thatch`, `src/extract-queue.ts`:
 
@@ -234,7 +242,7 @@ continues working while the child extracts.
 |------|----------------|
 | `src/extraction.ts` | In-memory ring buffer (`ExtractionPipeline`), shared payload builders (`buildExtractionPayload`, `deriveTitle`, `summarizeArgs`) |
 | `src/extract-queue.ts` | File-backed JSONL queue for MCP hosts |
-| `src/index.ts` | opencode hooks: `tool.execute.after`, `session.status` idle, `session.created`, `session.error`, `session.deleted`, `chat.message` (nudge tier 1) |
+| `src/runtime.ts` | opencode hooks: `tool.execute.after`, `session.status` idle, `session.created`, `session.error`, `session.deleted`, `chat.message` (nudge tier 1) -- shared by the v1/v2 adapters |
 | `bin/thatch` | `buffer-batch`, `buffer-tool`, `flush-tools` subcommands |
 | `src/prompts.ts` | `extractionNudge` (with escalation), `extractionDirectPrompt` |
 

package/docs/dev/features/hygiene.md

@@ -1,5 +1,7 @@
 # Hygiene System
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 Store maintenance signals surfaced at session start. The plugin never deletes
 memories itself — it surfaces problems and lets the agent tend the store.
 
@@ -52,7 +54,7 @@ instructions for the agent to tend the store when convenient.
 
 `hygieneReport(db, repo, worktree)` in `src/hygiene.ts` is shared by:
 
-- The opencode plugin's session-start hook (`src/index.ts`)
+- The opencode plugin's session-start hook (`src/runtime.ts`)
 - The CLI's `thatch reminder` and `thatch hygiene` subcommands (`bin/thatch`)
 
 ## Interactions with other features

package/docs/dev/features/multi-host.md

@@ -32,7 +32,7 @@ wrapping---prefixing, transport, session hooks---lives outside the core.
 
 ## The three paths
 
-### opencode plugin (`src/index.ts`)
+### opencode plugin (`src/opencode/v1.ts` + `src/opencode/v2.ts`)
 
 Runs inside opencode's Bun runtime as a loaded plugin. No setup command is
 needed---opencode discovers the plugin from `opencode.json` and loads it at
@@ -228,7 +228,9 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 
 | File | Role |
 |------|------|
-| `src/index.ts` | opencode plugin entry---hooks, system prompt injection, session events |
+| `src/index.ts` | dual-shape plugin entry (merged default export loads on opencode v1 and v2) |
+| `src/opencode/v1.ts` + `src/opencode/v2.ts` | host adapters: hooks (v1) vs promise-context domains (v2) |
+| `src/runtime.ts` | shared plugin runtime: nudges, system prompt injection, session events |
 | `src/mcp.ts` | MCP server (shared by Claude Code and Cursor)---stdio JSON-RPC, tool dispatch |
 | `src/setup.ts` | Setup installer for Claude Code and Cursor---markers, hooks, skills |
 | `src/prompts.ts` | All three system prompt variants---`systemPrompt()`, `claudeInstructions()`, `cursorInstructions()` |

package/docs/dev/features/notifications.md

@@ -5,19 +5,28 @@ hand-editable user config file. Both are plain child processes and file I/O,
 so the feature works identically on every host -- opencode, Claude Code, and
 Cursor -- with no host-specific plumbing and no new npm dependencies.
 
+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.
+
 ## Source files
 
 | File | Role |
 |------|------|
-| `src/config.ts` | Zod section schemas, config file load/save/merge, platform defaults. |
+| `src/config.ts` | Zod section schemas, config file load/save/merge, platform defaults, `alertMode`. |
 | `src/notify.ts` | Per-platform dispatch for banner + voice, with an injectable spawner. |
 | `src/tool-defs.ts` | `config_get`, `config_set`, `notify_user` tool definitions (shared registry, non-opencodeOnly). |
+| `src/alerts.ts` | Alert state machine: 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). |
 
 ## Config design
 
 The config is one JSON file at `~/.config/thatch/config.json`, placed next to
 `thatch.db` by deriving the path from `THATCH_DB_PATH` (or the XDG default the
-same way `index.ts` and `mcp.ts` derive the DB path). Tests pass an explicit
+same way `runtime.ts` and `mcp.ts` derive the DB path). Tests pass an explicit
 dbPath to keep writes inside a tempdir.
 
 Key decisions:
@@ -81,13 +90,110 @@ Details that matter:
   reporting stays honest. There is no debounce; polling agents notify once at
   the end.
 
+## Alerts: the automatic notification path (opencode only)
+
+`src/alerts.ts` holds an in-memory state machine per session. The plugin
+runtime (both the v1 and v2 adapters feed it the same event stream) drives it
+from the shared `onEvent` hook; delivery reuses `sendNotification` with the
+`alerts` config section choosing the channel per event (`alertMode`, default
+`banner`). Delivery is fire-and-forget (a spoken alert awaits the sentence
+for seconds and must never stall the event pump); the machine owns the
+per-event `none` gate and the per-delivery config re-read is what makes
+config changes apply without a restart.
+
+Events consumed:
+
+| Event | Machine input |
+|-------|---------------|
+| `question.asked` / `permission.asked` | Pause alert, deduped per request id; cleared by the matching replied/rejected event. |
+| `session.status` busy | Marks the session active and resets the round. |
+| `session.status` retry (v1 only) | Clears a recorded error -- opencode recovered on its own -- but preserves the real-work flag (the tool calls before the retry happened). |
+| `session.error` / `session.execution.failed` | Records the error name; on v2 the adapter emits this paired with the idle event, so the verdict always follows. |
+| `session.status` idle (from active) | The verdict: error alert, done alert, or silence. A recorded error delivers its verdict WITHOUT the message fetch (the fetch rides the same host API whose failure plausibly accompanied the failure). |
+| `session.deleted` | Drops the state. |
+
+The verdict combines two sources, because neither alone can answer "was
+this a real round of work the user asked for?":
+
+- **The tool side is live bookkeeping, not message archaeology.** The
+  runtime calls `sessionRealWork` at exactly the extraction buffer's push
+  site -- the buffer's filter is the one classification of "this call was
+  not bookkeeping" (`isMetaToolName`: `thatch_*`, `skill`, `task`,
+  `agent`, `subagent`; execute-wrapped thatch calls are unwrapped and never
+  reach the push). Message parts do not carry tool arguments, so the
+  execute-unwrap cannot be redone from messages. `todowrite` and `question`
+  reach the push (the buffer wants their facts) but are excluded from the
+  alert signal -- see `isNoWorkTool` in `src/alerts.ts`; they deliberately
+  do NOT live in `isMetaToolName`, and moving them there would silently
+  stop the buffer from queueing them.
+- **The trigger side comes from the message list** via the pure
+  `deriveRoundShape` (exported from `src/alerts.ts`, fed
+  `HostCapabilities.sessionMessages` output). The round delimiter is v2's
+  own idle marker: v2 appends a `{type: "idle"}` marker message at every
+  turn end (`SessionMessage.Idle`), so the round is everything after the
+  previous marker -- the host's turn definition, immune to mid-round
+  steers. V1 has no markers and falls back to "newest non-assistant message
+  triggered the round" (a mid-round steer under-classifies there; accepted
+  v1 limitation).
+
+Silence rules, in verdict order:
+
+- **Unknown shape** -- a failed or empty message fetch stays silent.
+  Alerts are best-effort: a spurious banner on every broken fetch costs
+  more than a rare missed completion, and the same fetch failing also
+  breaks the wrap-up greenlight check, so the session degrades
+  consistently. This rule also keeps adapter-level tests (whose client
+  mocks have no message surface) from ever spawning a real banner.
+- **Synthetic-trigger silence** -- nudges, background-task completions, and
+  watcher wake-ups are synthetic deliveries (v2: their own message kind; v1:
+  all-synthetic text parts on the user message). A round they triggered
+  never fires the DONE alert, even when it does real work. It is a silence
+  on the done verdict only: a synthetic round that ends in a real error
+  still banners the error. The rule exists because async thatch activity
+  would otherwise produce a banner every time.
+- **Abort and shutdown silence** -- an error name matching
+  /abort|shutdown|interrupt/i means the user interrupted the turn
+  themselves (`MessageAbortedError`, or v2's user-reason interrupt
+  translation), the process is leaving (`SessionShutdownError`), or the
+  execution was superseded by a newer one (the catch-all for unknown
+  interrupt reasons). Sources: the event-level error, the message-level
+  error on the last assistant message, and v2's interrupted-reason
+  translation.
+- **Error alert** -- any other recorded error (event-level, or message-level
+  on the last assistant message) notifies needs-attention with the error
+  name in the message, instead of done. Notably `SessionInactivityError`:
+  v2's location-activity sweeper interrupts still-executing sessions when a
+  project directory goes quiet for an hour -- the one banner most likely to
+  reach Jeff away from the terminal.
+- **No real work** -- a round whose only tool calls were bookkeeping (or
+  that made none, or whose tool executions all crashed at the host layer)
+  stays silent. A round delegated entirely to subagents also stays silent:
+  dispatch tools are meta, and child sessions never alert.
+
+State is plain memory, deliberately not journaled to `runtime_state`: a v2
+reload mid-turn (plugin save, upgrade) loses that turn's busy->idle
+transition and stays silent. Accepted by design -- the PR #16 journaling
+exists because extraction and wrap-up state corrupt sessions when lost, and
+an alert cannot corrupt anything.
+
+Subagent child sessions never alert: the runtime's idle branch handles
+children (extraction completion) and returns before the alert verdict, and
+child errors requeue extraction instead. Pause asks from children still
+notify -- a subagent blocking on a question blocks the parent too.
+
+Deduplication across TUIs is structural: the runtime is one instance per
+project directory in the shared server regardless of how many TUIs are
+attached, so per-session state is exact by construction. Delivering from the
+TUI side (opencode's attention API) would fire once per attached TUI and was
+rejected for that reason (plus v1 has no TUI plugin surface at all).
+
 ## Prompt surface
 
 - `systemPrompt()` and `mcpInstructions()` list the three new tools and carry
   a short "Notifications" section: when to notify, the source-label rule, and
   the config_get-before-config_set instruction.
 - `notify_user` is not `opencodeOnly`: it needs no host capabilities, so MCP
-  hosts get it too. Nothing was added to `src/tools.ts` or `src/index.ts`.
+  hosts get it too. Nothing was added to `src/tools.ts` or the plugin runtime.
 
 ## Tests
 
@@ -99,8 +205,19 @@ Details that matter:
   platform, plus tool-level tests (merge-no-wipe, echo, `mode: none` no-op,
   configured voice honored) with `THATCH_DB_PATH` pointed at a tempdir.
 - `tests/tool-defs.test.ts` -- registry count and name list (hardcoded literals that fail loudly when the surface changes).
+- `tests/alerts.test.ts` -- the alert state machine: `deriveRoundShape`
+  (idle-marker delimiter, v1 fallback, synthetic trigger detection), the
+  real-work flag, pause dedup and re-arm, abort/shutdown silence,
+  error-with-name, retry recovery, `mode: none` per event, config
+  round-trip (isolated tempdir).
 
 ## QA coverage
 
 `tests/qa/auto/uc-059-tool-prefixing.ts` asserts the full bare-name list; the
-three new names are in its `expected` array.
+three new names are in its `expected` array. `uc-108-llm-alerts.ts` drives
+the full alert event flow against a spy notifier, including the adapter
+seam: raw v2 bus events through `translateEvent` and real-shaped
+`session.context` lists through `mapSessionContextMessages` +
+`deriveRoundShape` (the seam where the idle-marker bug hid). A live
+banner-by-ear check remains a manual verification against a running
+session.

package/docs/dev/features/nudge-pipeline.md

@@ -1,5 +1,7 @@
 # Per-Message Nudge Pipeline
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 Runs on every user message. Four priority tiers share one embedding
 computation. The pipeline injects *synthetic parts*---text the model sees in
 the conversation but the user does not see in the TUI. This is the inverse of
@@ -35,7 +37,7 @@ opencode path runs in-process with direct event hooks. The MCP path runs via
 external CLI hook processes that communicate with the long-lived MCP server
 through the sideband socket.
 
-### opencode path (`src/index.ts`, `chat.message` hook)
+### opencode path (`src/runtime.ts`, `onChatMessage` - v1 `chat.message` hook, v2 `session.hook("prompt")`)
 
 #### Compaction guard
 
@@ -265,7 +267,7 @@ TUI display. The opencode framework's history serializer filters on
 
 | File | Role |
 |------|------|
-| `src/index.ts` | opencode: `chat.message` hook (all 4 tiers), compaction guard, extraction fallback |
+| `src/runtime.ts` | opencode: per-message nudges (all 4 tiers), compaction guard, extraction fallback |
 | `bin/thatch` | MCP: `flush-tools` and `flush-predictions` subcommands |
 | `src/sideband.ts` | MCP: sideband client helpers (`sidebandMatch`, `sidebandPredictions`, `sidebandBehaviors`) |
 | `src/prompts.ts` | All nudge formatting functions (`recallNudge`, `claudeRecallNudge`, `predictionNudge`, `behaviorNudge`, `extractionNudge`, `claudeWriteNudge`) |