@jeffober/thatch 0.1.48 → 0.2.1

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/artifacts/skills/thatch-fact-extractor.md

@@ -18,7 +18,7 @@ The extraction nudge or dispatch prompt will give you a session ID. Call `get_ex
 4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
 5. Write for a future session with zero current context. No "we", "our session", "just now".
 6. Call `extraction_done` (with `session_id` set to the parent session's ID from the nudge) to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
-7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
+7. Your final message must be exactly: "Extraction complete. This is the extractor's final report - a background-task completion, not an extraction nudge; the buffer is drained. Never re-dispatch an extractor because a completion arrived - a new extraction nudge is the only dispatch signal." - do not list or summarize what you saved. The memories are in the store; the parent session does not need a report. The frame rides with the completion on purpose: a bare "Extraction complete." was indistinguishable from nudge traffic mid-loop, and the parent model misread it as new work (the September 2026 re-dispatch loop).
 
 ## What to extract
 

package/artifacts/skills/thatch-memory-verify.md

@@ -20,7 +20,7 @@ This skill is the catch.
 
 Call `thatch_memory_show` with the label (or accept the memory content directly if dispatched by a coordinator that already read it).
 
-Note the `created_at` and `updated_at` dates. A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
+Note the age line ("This memory was last updated N ago"). A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
 
 ## Step 2: Classify Claims
 
@@ -111,6 +111,6 @@ If no corrections were needed, report "all claims verified, no updates needed."
 
 # Proactive Use
 
-When `thatch_memory_show` or `thatch_memory_recall` returns a memory with an old `updated_at` date (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The `updated_at` date is included in the memory output for this purpose.
+When `thatch_memory_show` or `thatch_memory_recall` returns a memory whose age line shows it has not been updated in a while (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The age prose ("This memory was last updated N ago") is included in the memory output for this purpose.
 
 This is not mandatory for every old memory. Use judgment: a memory about a stable architectural decision may be fine for months, while a memory about file locations or function names is more likely to drift.

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 |
 |------|-------------|
@@ -105,7 +127,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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). |
 | `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` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, 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 (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. 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). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, 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 (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. 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. |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher and chat delivery gates; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events and pending chat mail (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, cancels the session's watchers, and unregisters it from the chat directory (the crash path — a dead process fires no event — is covered by heartbeat staleness). `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Stops the version checker, the watcher poller, and the chat poller, closes the DB. |
 
@@ -157,11 +179,15 @@ Two of these hooks were dead for weeks because failures were invisible.
 10. **Background completion narration is suppressed, not prevented.** When a
     background sub-agent completes, opencode injects a `<task_result>` block
     into the parent session and triggers a full model generation. Thatch
-    cannot cancel this turn (no pre-response hook). Two mitigations: the
-    fact-extractor skill's return value is constrained to the literal
-    "Extraction complete." so the injected block has no narratable content,
-    and the system prompt's "Background Task Completions" section instructs
-    the model not to narrate completions or treat them as approval to act.
+    cannot cancel this turn (no pre-response hook). The mitigations: the
+    fact-extractor skill's return value is a fixed string so the injected
+    block has nothing to narrate AND the string self-identifies as a
+    completion, not an extraction nudge (a bare "Extraction complete." was
+    misread mid-loop as new nudge traffic and re-dispatched - the September
+    2026 re-dispatch loop); the system prompt's "Background Task
+    Completions" section instructs the model not to narrate completions or
+    treat them as approval to act, and that a completion is never a
+    re-dispatch signal.
 11. **Prediction engine is a statistical model, not an LLM call.** The query
     (embed prompt, cosine-match against matchers, score linked predictions)
     is mechanical — same shape as `thatch_memory_recall` but against different
@@ -187,7 +213,7 @@ Two of these hooks were dead for weeks because failures were invisible.
 ## Data flow
 
 ```text
-thatch_memory_remember(label, content)
+thatch_memory_remember(label?, content)
   → model.passageEmbed("# label\n\ncontent") → Float32Array
   → db.findSimilar(store, embedding) — write-time collision check (no telemetry)
   → db.remember(store, label, content, embedding, model.name, opts)

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
@@ -189,7 +191,14 @@ 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
 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). `isStale`
+harness beats it (it says dead while the heartbeat proves alive). RESTART
+grace: a new daemon re-hosts the dead one's hosted set under a bounded
+window (`CHAT_REHOST_GRACE_MS`, 24h, `THATCH_CHAT_REHOST_GRACE_MINUTES`
+to override) - open TUI tabs reconnect but emit no events until typed
+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`
 groups the result into Active and Stale sections - the stale section's
@@ -394,8 +403,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/memory-store.md

@@ -58,7 +58,7 @@ The "global" store always exists — it is inserted at schema init (`INSERT OR I
 ### Write path (memory_remember)
 
 ```text
-agent calls memory_remember(label, content, opts)
+agent calls memory_remember(label?, content, opts) - label is derived from the content's first heading or line when omitted
   → model.passageEmbed("# label\n\ncontent")  →  Float32Array
   → db.findSimilar(store, embedding, { excludeSlug })  →  write-time collision check
   → db.remember(store, label, content, embedding, model.name, opts)

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()` |