@jeffober/thatch 0.1.48 → 0.2.1

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
 
@@ -47,6 +49,18 @@ not a compaction summary, compaction has already failed (the auto-continue
 never fired). Thatch clears the stale `compacting` flag and proceeds normally.
 See [compaction-recovery.md](compaction-recovery.md).
 
+#### Task sub-agent guard
+
+If the session is a child in `childToParent` but not in `extractionChildren`
+(a task-dispatched sub-agent), all nudge tiers are skipped and the hook
+returns before tier 1. Dispatched sub-agents may have restricted tool lists
+that exclude the thatch tools, and even where the tools exist the child is
+driven by its dispatch prompt, so a nudge only produces "No tool named"
+error rounds or noise. `extraction.requeueStaleAccepted()` still runs before
+the guard - it is session-independent maintenance. See
+[session-lifecycle.md](session-lifecycle.md) for the `extractionChildren`
+distinction.
+
 #### Tier 1---Extraction nudge (fallback path)
 
 Fires only when direct extraction was never triggered or threw (the session is
@@ -265,7 +279,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`) |

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

@@ -0,0 +1,133 @@
+# Feature: OpenCode plugin dual-adapter (v1 + v2)
+
+The opencode plugin supports both opencode lines from one npm package: the
+1.18.x plugin API and the 2.x plugin API. The user's setup (shim file, config
+key, DB, skills) is identical under either host.
+
+## Architecture
+
+```text
+src/index.ts          dual entry -- merged default export { id, setup, server }
+  │                     opencode v1 reads default.server; v2 reads
+  │                     default.setup and strips excess keys. Both loaders
+  │                     verified against tagged upstream source.
+  ├── (lazy) → src/opencode/v1.ts   v1 adapter (@opencode-ai/plugin)
+  └── (lazy) → src/opencode/v2.ts   v2 adapter (@opencode/plugin)
+                     both delegate to:
+                src/runtime.ts      shared runtime (nudges, system prompt,
+                                    session events, extraction, bookkeeping)
+                     ↑ consumes
+                src/capabilities.ts HostCapabilities seam
+```
+
+### The isolation rule
+
+`src/index.ts`'s static import graph must stay SDK-free. Each adapter
+imports its host's SDK (`@opencode-ai/plugin` vs `@opencode/plugin`), and the
+SDKs resolve only under their own host's install, so the entry reaches both
+adapters exclusively through dynamic `import()`. A top-level await would make
+either host's load block on (or fail from) the other host's adapter. The pure
+helpers (`osProcessArgs`, `startupSessionId`, ...) live in `src/os-args.ts`,
+which is safe to re-export statically.
+
+### The export shape
+
+Upstream loaders decide everything:
+
+- **v1** (`packages/opencode/src/plugin/shared.ts`, `readV1Plugin`, identical
+  across 1.18.0-1.18.32): reads only `mod.default`; uses `default.server` if
+  present and never reaches the named-export ("legacy") fallback. Excess keys
+  (like `setup`) are invisible to it. A default export with `id` but no
+  `server` throws and the host SILENTLY SKIPS the plugin (error-publish is
+  commented out in the upstream caller).
+- **v2** (`packages/core/src/plugin/module.ts` @ v2.0.9): decodes `default`
+  as `{ id, effect }` or `{ id, setup }` with Effect Schema; excess keys
+  (like `server`) are tolerated and stripped (verified empirically at
+  effect@4.0.0-rc.112, the version v2 pins).
+
+So the merged object `{ id, setup, server }` satisfies both. A module with a
+named `server` export plus a v2-shaped default does NOT work on v1 -- that
+shape throws in `readV1Plugin`.
+
+## The capability seam
+
+`HostCapabilities` (src/capabilities.ts) is the interface of host operations
+the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
+(src/tool-defs.ts, the per-tool-call seam); they stay separate on purpose.
+
+| Capability | v1 source | v2 source | v2 strategy |
+|---|---|---|---|
+| bus events | `event` hook | `event.subscribe` (raw SSE) | client-side location filter; location-less events resolve via `session.get` (`{sessionID}` input) and drop unresolvable (mirrors v1's server-side filter); events for plugin-created extraction children pass by ID (they live in the project directory, which differs from the instance directory on below-root launches) |
+| incoming message | `chat.message` hook | `session.hook("prompt")` | the hook awaits the runtime; nudge injections append to the OUTBOUND request's last user message in the generate hook (v2 wire `Message` carries parts in `content`, not `parts`) |
+| system prompt | `experimental.chat.system.transform` | `session.hook("context")` | mutates the request's system array; the runtime's plain strings convert to `{type: "text", text}` SystemPart objects at the boundary |
+| compaction | `experimental.session.compacting` + `.autocontinue` + `session.compacted` | `session.hook("compaction")` | flag lands; context-injection surface unverified |
+| wrap-up commands | `command.execute.before` + command files | `command.transform` + `CommandEditor.add` | registered in code: `execute` arms the greenlight check (`onCommandExecuteBefore`) and delivers the same prompt body the v1 file carries, substituting the invocation's prompt text for `$ARGUMENTS` (v2's `session.prompt` does no template expansion); the runtime installs only ACTION command files on v2 and REMOVES stale wrap-up files from earlier v1 runs (a file and a registered command with the same name would collide) |
+| tools | `hooks.tool` map via `tool()` | `tool.transform` + `ToolEditor.add` | zod shapes pre-converted to JSON Schema with our own zod (v2's `instanceof $ZodType` detection fails for ours and drops the schema); results wrap as `{ content }` |
+| tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts); the title is derived from the tool name and args (`deriveTitle`), since v2's `Tool.Result.output` is a typed output value, not a title |
+| noReply deliveries | `promptAsync` with `noReply` | none | gated off via `HostCapabilities.noReplyDelivery` -- chat echoes and the session-start reminder are skipped on v2 (delivering them would start real model turns: a feedback loop) |
+| synthetic wake deliveries | `promptAsync` with `synthetic` parts | `session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
+| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete degrades (extraction children are not cleaned up on v2 -- the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
+| session status | `client.session.status` | none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
+| 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 |
+| 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 |
+
+## Live verification and remaining unknowns
+
+The v2 adapter was written against tagged source (v2.0.9) before a live
+binary was available, then verified against a real v2.0.15 binary on
+2026-09-23: merged-default loading, tool schemas (via pre-converted JSON
+Schema - see the gotcha), event shapes, the execution-lifecycle idle signal,
+synthetic wake delivery, and command registration all work; the full QA
+suite runs green against a v2 serve.
+
+Still unverified against the live binary (static analysis only):
+
+- Whether `session.hook("prompt")` fires for `session.synthetic` inbox
+  items. If it does not, `pendingInjections` from the prior real turn gets
+  appended to the synthetic turn's outbound request.
+- Whether `SessionGenerate.messages` are fresh objects per model call within
+  a turn. If not, the generate hook pushes duplicate nudges on every tool
+  round trip.
+- An npm-installed copy (not the dev checkout, which has devDependencies
+  present) loading under v2 - the isolation rule's real-world proof.
+
+The app-exit gap (no server-side publish surface for `tui.command.execute`)
+is upstream:
+[anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984).
+Install opencode-v2 (brew formula `anomalyco/tap/opencode-v2`; conflicts
+with the v1 formula's binary name, so it cannot coexist) and re-run the QA
+live suite against it.
+
+## User setup compatibility
+
+No config file moves or changes format. The DB, model cache, version-check
+files, and skills dirs are host-agnostic and shared. opencode's own config
+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.
+
+## 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/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/plugin.test.ts` -- v1 adapter contract tests (mocked client)
+
+## Interactions with other features
+
+Everything downstream of the hooks is unchanged by the dual adapter:
+[extraction.md](extraction.md), [nudge-pipeline.md](nudge-pipeline.md),
+[session-lifecycle.md](session-lifecycle.md),
+[cross-session-chat.md](cross-session-chat.md),
+[watchers.md](watchers.md), [notifications.md](notifications.md). The MCP
+path ([mcp-parity.md](../mcp-parity.md)) does not touch any of this.

package/docs/dev/features/qa-system.md

@@ -96,6 +96,49 @@ opencode session timeout, compaction trigger). Run them locally with
 | `qa-auto` | `bin/qa-run auto` | Run automatable only (fast, no LLM). Pass UC names as args to select a subset. |
 | `qa-live` | `bin/qa-run live` | Run live only (spawns opencode, costs tokens). Pass UC names as args to select a subset. |
 
+### The opencode version matrix (default behavior)
+
+Every task that runs opencode-driven use cases runs one leg per
+DISCOVERED opencode install, with test names suffixed
+(`UC-001-memory-roundtrip [v1]`, `UC-001-memory-roundtrip [v2]`) when
+there are several. There is no separate matrix command - the ordinary
+tasks just do the matrix based on what is available.
+
+Discovery (tests/qa/binaries.ts) asks the package manager where its
+formulas are installed (`brew --prefix opencode`, `brew --prefix
+opencode-v2`), falls back to the PATH-resolved binary, validates each
+candidate by running `--version`, tags it by major (`v1`, `v2` - the
+version output decides, not the formula name), and dedups candidates
+that resolve to the same binary. A machine with one install runs
+single-leg with unsuffixed names, so single-binary setups behave
+exactly as they did before the matrix existed.
+
+A use case opts into or restricts the matrix with `hosts: ["v1"]` /
+`["v2"]` / `["v1", "v2"]` on the `UseCase`:
+
+- Live use cases (no custom `run`) are matrixed by default - the default
+  `runViaOpencode` path spawns opencode by definition.
+- Automatable use cases keep a single leg unless they declare `hosts` -
+  the fast suite is not doubled for cases that never touch opencode.
+  Declare `hosts` when a custom `run` spawns opencode itself (UC-098) or
+  drives a serve (UC-100).
+
+`QA_HOSTS=v1` (comma-separated) narrows the legs when iterating against
+one major; a value matching no discovered install registers nothing
+with an explanatory line.
+
+Legs get separate fixtures (the fixture directory is keyed by test name
+suffix) because hosts cannot share one: a v2 session db in a shared
+fixture fails the v1 leg's serve with "Database is not empty and has no
+session table".
+
+The v1 and v2 `run` CLIs disagree on flags (v1 has `--dir`, which v2
+dropped; v2 needs `--standalone` to skip the background daemon, which a
+fixture sandbox must not boot). `opencodeRunArgs(ctx, prompt)` in the
+runner builds the right invocation per leg by version-detecting the
+binary the leg's PATH selects; `runViaOpencode` and UC-098's custom runs
+go through it.
+
 The `qa` task runs auto first via `&&`. Auto failures stop before live runs.
 The `qa-live` task does not use `--concurrent` — live sessions are
 resource-heavy and benefit from sequential execution.

package/docs/dev/features/repo-identity.md

@@ -104,7 +104,7 @@ are per-worktree -- so git reads are equivalent from either. Consumers:
 
 - `src/git.ts` -- resolution chain, cache validation, spawn-cwd fallback
 - `src/db.ts` -- `repo_paths` table, accessors, `repoPathCache` adapter
-- `src/index.ts` -- plugin init order (DB before detection), identity from
+- `src/runtime.ts` -- plugin init order (DB before detection), identity from
   the session directory, watcher runner wrapper
 - `src/mcp.ts` -- MCP server init order
 - `bin/thatch` -- CLI `defaultStore()` and hook-line identity resolution

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

@@ -1,5 +1,7 @@
 # Session Lifecycle Management (opencode)
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, handle child session cleanup, and resolve wrap-up commands.
 
 ## What it does
@@ -15,7 +17,7 @@ opencode emits bus events for session lifecycle changes. Thatch subscribes to th
 
 ## How it works
 
-### Event handler (`src/index.ts`, event hook)
+### Event handler (`src/runtime.ts`, shared by both adapters)
 
 Subscribes to all session bus events. Dispatches based on `event.type`.
 
@@ -115,14 +117,15 @@ first-ever install is invisible until the next server start.
 ## Interactions with other features
 
 - Extraction pipeline ([extraction.md](extraction.md)): direct extraction is triggered by `session.status idle`; child lifecycle managed here
-- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `extracting` set suppresses tier 1; `compacting` set suppresses all tiers
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `extracting` set suppresses tier 1; `compacting` set suppresses all tiers; task-dispatched sub-agents (in `childToParent`, not in `extractionChildren`) suppress all tiers
 - Hygiene ([hygiene.md](hygiene.md)): hygiene report runs at `session.created` for top-level sessions
 - Compaction recovery ([compaction-recovery.md](compaction-recovery.md)): `session.compacted` event clears the compacting flag
 - Memory store ([memory-store.md](memory-store.md)): child sessions write memories via `memory_remember`, which triggers drain via `tool.execute.after`
 
 ## Source files
 
-- `src/index.ts` -- event handler (all session events), `triggerExtraction`, `cleanupChild`, internal state maps
+- `src/runtime.ts` -- event handler (all session events), `triggerExtraction`, `cleanupChild`, internal state maps
+- `src/opencode/v1.ts`, `src/opencode/v2.ts` -- host adapters wiring the runtime into each opencode plugin API
 
 ## Key invariants
 

package/docs/dev/features/watchers.md

@@ -1,5 +1,7 @@
 # Watchers
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 Watchers are the general mechanism for event-driven notifications from
 external sources: the model registers a watch on something outside the
 session, thatch polls it in the background, and the plugin prompts the
@@ -42,10 +44,15 @@ The registry lives in plugin memory, never in SQLite. Three reasons:
    in-memory; the file-backed queue exists only for the MCP path's
    separate short-lived hook processes.
 
-The cost: a restart loses watches. Accepted because the session that
-created them loses its conversational context too - a notification
-into a session that no longer knows why it is being watched is worse
-than a lost watch.
+The cost used to be "a restart loses watches", accepted because the
+session that created them loses its conversational context too - a
+notification into a session that no longer knows why it is being
+watched is worse than a lost watch. The dormant-recovery layer keeps
+the best of both: the definition survives the restart (journaled),
+nothing polls or delivers while its session is away, and resuming the
+session re-arms the watches into a session that again knows why it is
+being watched. See the `runtime_state` row in
+`docs/dev/features/opencode-plugin.md` for the journal mechanics.
 
 `session.deleted` also cancels the session's watchers and pending
 events, and `dispose` stops the poller. These are cheap insurance;
@@ -221,7 +228,7 @@ src/watchers.ts, test-enforced); command watchers register the single
 - `src/watchers.ts` - registry, poller, gh CLI runner, command runner,
   diff functions
 - `src/tool-defs.ts` - the watch tool definitions (see `TOOL_DEFS`)
-- `src/index.ts` - registry construction, delivery closure,
+- `src/runtime.ts` - registry construction, delivery closure,
   session.status tracking, session.deleted cleanup, dispose
 - `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
   Watchers section

package/docs/dev/gotchas.md

@@ -41,7 +41,7 @@ here first. These are the things that have already cost time.
   a memory, write it with `archived: true`; to unarchive, `archived: false`.
 - **Updating an archived memory requires explicit `archived` param.** If the
   entry is already archived and a `remember` call omits the `archived` param,
-  the tool returns an error (`db.ts:395`). Pass `archived: true` to keep it
+  the tool returns an error (`db.ts:585`). Pass `archived: true` to keep it
   archived or `archived: false` to unarchive. This guard prevents accidental
   unarchival via an unrelated content update.
 
@@ -70,7 +70,7 @@ here first. These are the things that have already cost time.
 - **`chat.message` has two priority tiers**: extraction nudge first (returns
   early), then the prompt-aware recall nudge. Don't run both in one turn.
 - **The extraction nudge peeks, never flushes.** The buffer is NOT drained
-  on nudge delivery (`index.ts:366` — `peek()` call). It persists until the
+  on nudge delivery (`extraction.peek()` in `triggerExtraction`, src/runtime.ts). It persists until the
   agent writes a memory or calls `thatch_extraction_done`. Ignored nudges
   accumulate; the `missedNudges` counter escalates the tone (polite at 0-1
   misses, insistent at 2, ALL-CAPS at 3+). The counter resets when the
@@ -80,8 +80,8 @@ here first. These are the things that have already cost time.
   is active. The peek-not-drain semantics still hold for the fallback nudge
   path (MCP hosts and any `triggerExtraction` failure).
 - **A child sub-agent's `thatch_memory_remember` drains the parent's buffer**
-  via the `childToParent` Map (`index.ts:79` declaration, `index.ts:272`
-  lookup). Two paths reach this machinery: (a) the **plugin-initiated child
+  via the `childToParent` Map in src/runtime.ts (declaration plus `.get()`
+  lookups in the idle and remember handlers). Two paths reach this machinery: (a) the **plugin-initiated child
   session** — `triggerExtraction` calls `client.session.create` with a
   `parentID`, the primary opencode path; (b) the **agent-initiated background
   task** — the model dispatches the fact-extractor via the `task` tool after
@@ -196,3 +196,93 @@ prose end marker stopped matching, and setup could never update the block
 again while `checkSetup` reported `markers-broken` on every session. Rule:
 never use file content as its own delimiter; agents will reword it. The
 legacy-prose detection constants exist only to migrate old installs.
+
+## The dual-shape plugin entry: named `server` + v2 default export silently breaks v1
+
+opencode v1's plugin loader (`readV1Plugin`, identical across 1.18.x) reads
+ONLY `mod.default`. A module that exports a named `server` plus a v2-shaped
+default `{ id, setup }` (no `server` inside the default) makes v1 throw on
+load - and the host swallows the error and SKIPS the plugin with no visible
+message. The failure looks like "thatch tools disappeared", not like a load
+error. This is why the dual entry exports a MERGED default object
+(`{ id, setup, server }`) and why every shim (the user's
+`~/.config/opencode/plugins/thatch.ts` and the QA runner's generated one)
+must re-export the default as well as the name. A named-only shim loads on
+v1 and silently disables thatch on v2 - same invisible failure, opposite
+host.
+
+## The extraction buffer matches on tool NAME, so Code Mode execute calls re-queue pipeline traffic
+
+The non-bufferable filter in `onToolExecuteAfter` (`src/runtime.ts`) matches
+`input.tool`, but a Code Mode `execute` call that wraps
+`tools.thatch_extraction_done` / `tools.thatch_memory_remember` inside its
+code string arrives as tool name `execute`. Unfixed, every execute-wrapped
+ack landed back in the buffer as an extractable interaction: each
+extraction run's payload contained only the previous run's dispatch and ack,
+the nudge always found pending interactions, and a session could loop
+forever on dispatch → ack → nudge (observed live in an oink session,
+September 2026 - the looped agent answered every turn with "Extractor
+dispatched and acknowledged. Stopping per the nudge" and never resumed the
+user's work; only a human message broke the cycle). The fix unwraps execute
+calls (`unwrapExecuteThatchCalls` in `src/extraction.ts`) and runs the
+wrapped tool's hook semantics instead of buffering. Lesson for sibling
+hooks: when a filter reasons about tool identity, an aggregator tool
+(arbitrary code execution over other tools) defeats name-based matching -
+unwrap the aggregation before classifying.
+
+## LLMs guess tool-call shapes on the first call, so teach the shape at the mention site
+
+A September 2026 audit of every thatch tool-call error in the opencode
+session database (~19k calls, both v1 and v2 storage) found the failures
+cluster on the model's FIRST thatch call - usually the startup recall round -
+and fall into a short list of avoidable mistakes:
+
+- **Bare positional string instead of an object argument** (the largest
+  bucket): `thatch_memory_recall({ query: "..." })` called as
+  `thatch_memory_recall("...")`. Root cause: the opencode system prompt's
+  startup section and the recall nudge both used positional-style examples
+  (`thatch_memory_recall "query"`), and Code Mode models mimic that shape
+  inside `execute`. Both now teach the object form.
+- **Required discriminator params omitted**: `memory_remember` without
+  `label` (models pass `title`/`id`/`statement` instead, or nothing),
+  `prediction_update` without `signal`, `behavior_codify` without
+  `situation`. Fixes: `label` is optional and derived from content;
+  tool descriptions state the all-args-required contract.
+- **Nudges leak into tool-less agent contexts**: task-dispatched sub-agents
+  (explore/general and friends) have restricted tool lists that exclude the
+  thatch tools, but `chat.message` nudges fired for them anyway, producing
+  guaranteed "No tool named ..." error rounds. The chat.message hook now
+  skips nudges for child sessions that are not extraction children.
+
+The general lesson: any surface that names a tool to an LLM (system prompt,
+nudge, skill text) is a usage-shape prior. Give the argument shape at the
+mention site, because the model's first call happens before it has seen a
+working example. Also note Code Mode `execute` validation failures are only
+persisted in the v2 `session_message` store - they are invisible in the v1
+`part` table, so error-rate analysis on old data undercounts them.
+
+## ThatchDB lazy reopen: new accessors must go through the private getters, and journal writes stay guarded at call sites
+
+`ThatchDB` reopens its SQLite connection on first use after `close()`
+(`src/db.ts`, the `#db`/`#predictions`/`#behaviors`/`#chat` private getters), so
+an in-flight tool call that races a v2 plugin reload's `dispose()` completes
+instead of throwing "Cannot use a closed database". Two rules keep this intact:
+
+- **New facade methods need no extra wiring, but new state-holding members
+  do.** The engine facades (`ChatStore`, `PredictionEngine`, `BehaviorEngine`)
+  capture the `Database` handle at construction; the reopen rebuilds them. A
+  new member that captures the Database directly must get its own private
+  getter that ensures the handle is open first - a plain field keeps serving
+  the stale closed handle and the reopen silently never fires for it (this
+  exact bug is pinned by the "engine facades are rebuilt" test in
+  tests/db.test.ts).
+- **Post-dispose journal writes are no-ops at their call sites, not in
+  db.ts.** After a reload, the RELOADED instance owns the `runtime_state`
+  rows, so delayed writers in `src/runtime.ts` check the `disposed` flag
+  BEFORE touching the db - the lazy reopen would otherwise hand a stale
+  writer a fresh connection. All three journal callbacks are guarded (the
+  extraction pipeline's finalization, the WatcherRegistry journal - a poll
+  cycle suspended at an await can outlive `watchers.dispose()` - and the
+  wrap-up arming write, whose command executes are not drained by the v2
+  cleanup). Do not "fix" the guard away by moving it into db.ts: the
+  accessor cannot tell a legitimate in-flight caller from a stale writer.

package/docs/dev/mcp-parity.md

@@ -24,8 +24,9 @@ This document maps the feature parity and documents the remaining gaps.
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
 | **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
-| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
+| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
+| **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Behavior auto-fire** (self-discipline rules) | `chat.message` hook scores the prompt embedding against behavior matchers; injects a `[thatch] Situational behaviors` nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires behavior query via the sideband socket's `behaviors` method in parallel with recall and predictions | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scoreBehaviorNudge` entry point in both paths |
@@ -72,8 +73,8 @@ and the nudge (fallback):
 
 **Direct extraction (primary path):**
 
-1. `tool.execute.after` buffers every non-thatch, non-skill, non-task tool
-   call into a per-session in-memory array (max 20 interactions).
+1. `tool.execute.after` buffers every non-meta tool
+   call (`isMetaToolName` in `src/extraction.ts`) into a per-session in-memory array (max 20 interactions).
 2. When the parent session goes idle (`session.status` idle event) with pending
    buffer entries, the plugin calls `triggerExtraction`: creates a child session
    via `client.session.create` (with `parentID`), then prompts it via