@jeffober/thatch 0.2.1 → 0.2.3

package/docs/dev/gotchas.md

@@ -67,32 +67,26 @@ here first. These are the things that have already cost time.
 - **Hook failures are logged with a `[thatch]` prefix and never swallowed.** Two
   hooks were dead for weeks before failures were made visible. If you add a
   hook, log on failure.
-- **`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 (`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
-  buffer drains. The primary opencode path doesn't use the nudge at all:
-  `triggerExtraction` creates a child session directly, and the `extracting`
-  set suppresses the nudge in `chat.message` while a direct-extraction child
-  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 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
-  receiving the nudge, the fallback path still used by MCP hosts. Both use
-  the same `childToParent`/`parentSnapshots`/`consumeSnapshot` plumbing.
-  Without this, either path would write memories in the child but never
-  clear the parent's queue — the nudge would replay every turn.
-  `thatch_extraction_done` is the belt-and-suspenders explicit
-  acknowledgment: it drains the buffer without requiring a memory write
-  (covers cases where the sub-agent errors out or the host doesn't expose
-  parent-child session relationships).
+- **There is no model-facing extraction nudge on opencode.** The old
+  `chat.message` extraction nudge (and its `missedNudges` escalation) drove
+  a model-driven handshake that raced its own state machine: parent acks
+  landed before the child's payload fetch, no-claim completions wiped
+  in-flight accepted sets, and mis-targeted session ids made every
+  transition a silent no-op - so the same buffered count re-fired forever
+  (the September 2026 dispatch-loop report). Extraction is now plugin-driven
+  end-to-end: `triggerExtraction` at session idle creates the child and
+  interpolates the session ID itself; the child's payload fetch records the
+  claim; completions are claim-scoped; the 15-minute stale reaper bounds
+  crashed extractors. The nudge survives on MCP hosts only, where no plugin
+  can create sessions and the file-backed queue is durable until the
+  extractor completes.
+- **A child's `thatch_memory_remember` completes only its claimed delivery**
+  via the `childToParent` Map and the claim recorded by its payload fetch.
+  A child that never fetched has no claim, and its memory write (or idle
+  signal, or ack) consumes nothing - the entries stay held/pending for the
+  real extractor. `thatch_extraction_done` is the explicit no-save
+  completion: claim-scoped like everything else, so a mis-ordered or
+  mis-targeted ack can never drop another extractor's in-flight delivery.
 - **The no-save drain runs in the child-idle handler regardless of writes.**
   When the extraction child goes idle after a no-save run (nothing worth
   extracting), the parent's snapshot entries must still be drained from the
@@ -286,3 +280,16 @@ instead of throwing "Cannot use a closed database". Two rules keep this intact:
   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.
+
+## Command frontmatter descriptions must be quoted YAML scalars
+
+- **A plain-scalar frontmatter value containing a colon followed by a space
+  is invalid YAML, and not every host path rescues it.** `/thatch/hygiene`'s
+  description ("Tend the memory store: stale entries, ...") shipped unquoted;
+  the first parse throws
+  and only opencode's fallback sanitizer recovers it — and a long-lived
+  server was observed dropping the description entirely while a fresh server
+  parsed it fine, which made the bug look like a TUI rendering issue. The
+  renderer quotes every description (`yamlQuote` in src/commands.ts) and a
+  unit test pins the quoted form. Keep it that way for any new frontmatter
+  field whose value is free-form prose.

package/docs/dev/mcp-parity.md

@@ -23,7 +23,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **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 |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`, `refine`) | 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-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 |
@@ -78,28 +78,27 @@ and the nudge (fallback):
 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
-   `client.session.promptAsync` (or `prompt`) with the extraction payload. The
-   `extracting` set suppresses the nudge in `chat.message` while the child runs.
+   `client.session.promptAsync` (or `prompt`) with the extraction prompt (the
+   parent's session ID is interpolated into the prompt by the plugin). The
+   `extracting` set gates re-triggering while the child runs.
 3. The child session runs the `thatch-fact-extractor` skill, writes memories via
-   `thatch_memory_remember`. A memory write in the child drains the parent's
-   buffer snapshot (via the `childToParent` Map and `consumeSnapshot`) and
-   resets the missed-nudge counter.
-4. When the child goes idle, the handler drains any remaining snapshot entries
-   (covers no-save runs), deletes the child session, and fires a toast via
+   `thatch_memory_remember`. The child's payload fetch records its claim; its
+   memory write (or `extraction_done`) completes that claim - consuming only
+   the entries it received.
+4. When the child goes idle, the handler finalizes the claim-scoped
+   completion, deletes the child session, and fires a toast via
    `client.tui.showToast`.
 
-**Nudge (fallback path):**
+**Failure recovery (no model-facing nudge exists on opencode):**
 
 1. If `triggerExtraction` throws (session creation or prompt fails), the catch
-   block clears the `extracting` flag. On the next `chat.message`, the buffer is
-   **peeked** (not drained) and a synthetic text part carrying the JSON payload
-   is injected into the conversation. 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.
-2. The agent sees the nudge, loads the `thatch-fact-extractor` skill, and saves
-   durable facts via `thatch_memory_remember`. A memory write in the session
-   (or a child sub-agent via the `childToParent` Map) or `thatch_extraction_done`
-   drains the buffer and resets the missed-nudge counter.
+   block clears the `extracting` flag. The pending buffer is untouched, and
+   the next idle re-triggers extraction - the plugin retries without any
+   model cooperation.
+2. If the child errors or is deleted before completing, what it held is
+   requeued to pending. If its completion signal never comes at all, the
+   15-minute stale reaper returns accepted entries to pending. Either way
+   the next idle re-extracts - no interaction is silently lost.
 
 Claude Code and Cursor use a **file-backed** queue (`src/extract-queue.ts`)
 because hooks fire one-shot with no cross-call state:

package/docs/dev/setup-and-hooks.md

@@ -25,7 +25,7 @@ code (`src/opencode/v1.ts`):
 | `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
 | `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
 | `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_`, non-`skill`, non-`task` tool calls into the in-memory extraction ring buffer (max 20). In child sessions, also tracks new/updated/deleted counts via `childMetrics` for the extraction toast. |
-| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending and not already extracting (fallback — direct extraction via the `event` hook is the primary path), else prompt-aware recall nudge. Suppressed while compacting, while `extracting` is set, or for task-dispatched sub-agent sessions (children that are not extraction children). |
+| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Prompt-aware recall nudge (plus prediction/behavior auto-fire). No extraction nudge - extraction is plugin-driven at session idle. Suppressed while compacting or for task-dispatched sub-agent sessions (children that are not extraction children). |
 | `event` | `{ event: { type, properties } }` | — | Dispatches on `event.type`: `session.created` (top-level) → `client.session.prompt` with reminder + hygiene heartbeat; `session.created` (child with `parentID`) → records `childToParent` + snapshots parent's pending buffer. `session.status` idle (parent, pending interactions) → `triggerExtraction` (direct child-session extraction); idle (child) → complete/drain, `showToast` with metrics, delete child. `session.error` (child) → requeue parent's accepted entries. `session.deleted` → requeue if child, drop accepted if parent, clean maps. `session.compacted` → clear compacting flag. |
 | `dispose` | — | — | Closes the DB. |
 

package/docs/dev/skills.md

@@ -55,7 +55,14 @@ description: Extract durable project facts ... Use when ...
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
-| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). |
+| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. |
+| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box. |
+| `thatch-refine-infra` | Refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | Refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
 | `thatch-pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |

package/docs/user/README.md

@@ -328,6 +328,13 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
 
 ### Writing skills
 

package/docs/user/commands.md

@@ -17,6 +17,13 @@ or you invoke it.
   The agent asks before forgetting anything that may still matter.
 - `/thatch/reflect` — run the session-reflection skill to persist what the
   current session learned.
+- `/thatch/refine` — refine a plan for a code change under the current
+  project type's requirements: the agent classifies the project (team,
+  personal, shared library, spike, infrastructure, or open source
+  contribution), confirms the pick, and runs the refinement loop with
+  that type's expectations applied. Text after the command can name the
+  type directly (for example, `/thatch/refine shared-lib`) to skip
+  classification.
 - `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
   pre-flight checklist (flush extraction, finish promised memory writes,
   surface loose ends) before a compaction or an exit, gated by a greenlight
@@ -31,6 +38,7 @@ or you invoke it.
 | `/thatch/extract` | yes | no | no |
 | `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/refine` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/compact`, `/thatch/exit` | yes | no | no |
 
 Why the gaps: `/thatch/extract` needs the invoking session's ID, which only

package/docs/user/skills.md

@@ -77,6 +77,18 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
 
+### Plan refinement skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
+
 ## Stale skill cleanup
 
 When skills are renamed or removed in a new release, thatch automatically

package/docs/user/watchers.md

@@ -16,6 +16,12 @@ baseline, then polls the GitHub API through the `gh` CLI once a
 minute. When the target changes in a way the watcher cares about, the
 plugin prompts the agent with a notification.
 
+Register before you push. CI notifications fire when a check run goes
+from running to completed, so a watcher created after a fast pipeline
+has already finished will never fire for that commit. If every check on
+the head is already done when the watcher is created, the response says
+so and reports the results directly.
+
 PR watched events:
 
 - `pr_comment` - new top-level comments on the PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat.ts

@@ -212,7 +212,7 @@ export type ChatHostKind = "opencode" | "mcp";
 // Display names appear inside wake prompts and chat_list output, so they are
 // capped tight. Bodies are capped so a runaway sender cannot turn a nudge
 // into a context bomb; the reader fetches full content via chat_read anyway.
-const MAX_BODY_LEN = 10_000;
+export const MAX_BODY_LEN = 10_000;
 
 // Assigned names are lowercase slugs of a pool name with a numeric counter
 // suffix ("al-go-rithm-00001"), which satisfies NAME_CHARSET. The charset

package/src/commands.ts

@@ -100,6 +100,16 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
       description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
       body: hygieneCore(),
     },
+    {
+      name: "refine",
+      description: "Refine a plan under the project type's requirements (classifies the project first)",
+      // A skill trigger, not a nudge behavior: the body points at the
+      // thatch-refine router skill, which classifies the project and loads
+      // the matching type deltas on top of the plan-refinement core loop.
+      body: `Load and follow the thatch-refine skill to refine a plan for the current project.
+
+The user message may name a project type (team-app, personal, shared-lib, spike, infra, oss-contribution); if it does, skip classification and use that type. If no plan is drafted yet in this session, the skill's loop starts with drafting one.`,
+    },
     {
       name: "reflect",
       description: "Persist what this session learned as memories",
@@ -108,10 +118,20 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
   ];
 }
 
+/**
+ * Renders a YAML double-quoted scalar. Plain scalars break on values
+ * containing ": " (invalid YAML - the mapping key would be ambiguous), and
+ * opencode's lenient fallback parser does not rescue every host path, so the
+ * description must always be quoted.
+ */
+function yamlQuote(value: string): string {
+  return JSON.stringify(value);
+}
+
 /** Renders one action as a full command markdown file. */
 export function renderActionCommand(action: ActionDef): string {
   return `---
-description: ${action.description}
+description: ${yamlQuote(action.description)}
 ---
 ${userMessageSection}
 
@@ -121,7 +141,7 @@ ${action.body}`;
 }
 
 const COMPACT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then compact if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then compact if clear")}
 ---
 ${userMessageSection}
 
@@ -138,7 +158,7 @@ ${COMPACT_READY_TOKEN}
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
 
 const EXIT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then exit opencode if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then exit opencode if clear")}
 ---
 ${userMessageSection}
 

package/src/extract-queue.ts

@@ -56,10 +56,25 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   const additions: ToolInteraction[] = [];
   for (const tc of toolCalls) {
     const lower = tc.tool_name.toLowerCase();
-    if (lower === "mcp__thatch__memory_remember" || lower === "mcp__thatch__extraction_done") {
+    if (lower === "mcp__thatch__memory_remember") {
+      // The session that writes a memory has processed its queued
+      // interactions itself - drain. This is the parent's self-serve path.
       resetMissedCount(sessionID);
       consumeQueue(sessionID);
       existing.length = 0;
+    } else if (lower === "mcp__thatch__extraction_done") {
+      // An extraction_done ack must NOT drain the queue. When the PARENT
+      // acks after dispatching (per the nudge), a drain here deletes the
+      // queue before the sub-agent's get_extraction_payload fetch - the
+      // accept-before-fetch race, which on this path is a hard delete
+      // (silent interaction loss). The queue is consumed instead by the
+      // extractor's completion: extraction_done with the parent's
+      // session_id (drainExtractionQueue in mcp.ts), or the parent's own
+      // memory_remember above. A no-drain ack only resets the escalation
+      // counter - the queue persists on disk (durable across
+      // interruption), and an extractor that dies without completing
+      // leaves it in place for the next nudge to re-dispatch.
+      resetMissedCount(sessionID);
     }
     if (lower.startsWith("mcp__thatch__")) continue;
     if (lower === "skill" || lower === "task" || lower === "agent") continue;

package/src/extraction.ts

@@ -342,9 +342,10 @@ export class ExtractionPipeline {
    * Requeues accepted entries that have waited longer than maxAgeMs for a
    * completion signal that never came: the extractor sub-agent crashed
    * without acking, or the completion ack was lost. Without this, accepted
-   * entries linger unprocessed AND un-nudged - silent loss. Returns the session ids that had entries
-   * requeued; the regular nudge path picks them up from pending on the
-   * session's next message.
+   * entries linger unprocessed with nothing to re-extract them - silent
+   * loss. Returns the session ids that had entries requeued; on opencode
+   * the idle trigger re-extracts them, on MCP hosts the next flush-tools
+   * nudge picks them up.
    */
   requeueStaleAccepted(maxAgeMs = ACCEPTED_STALE_MS): string[] {
     const stale = [...this.#acceptedAt.entries()]

package/src/opencode/v2.ts

@@ -529,8 +529,9 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
       // returns the created SessionInfo directly.
       const result = await session.create({ location: { directory: worktree }, title: input.title });
       const id = result?.id;
-      // A shape mismatch must fail into the runtime's extraction fallback
-      // (the nudge path), not silently corrupt the child-session maps.
+      // A shape mismatch must fail loudly: the runtime logs it and retries
+      // extraction at the next idle. It must not silently corrupt the
+      // child-session maps.
       if (!id) throw new Error(`v2 session.create returned no id: ${JSON.stringify(result)?.slice(0, 200)}`);
       // Register for event forwarding: the child's events carry the project
       // directory, which the pump's directory filter would otherwise drop.
@@ -539,7 +540,7 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
     },
     // No delete on the v2 SessionDomain: extraction child sessions are not
     // cleaned up on v2 (documented gap; the bookkeeping maps still keep the
-    // nudge path consistent). Two user-visible consequences: the session
+    // claim/completion lifecycle consistent). Two user-visible consequences: the session
     // picker accumulates one thatch-extraction entry per extraction, and
     // "continue last session" (-c) logic that picks the newest top-level
     // session will land in an extraction child after any session that

package/src/prompts.ts

@@ -192,6 +192,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
 - \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
 - \`thatch-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
@@ -506,6 +513,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 - \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
 - \`thatch-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
@@ -788,46 +802,25 @@ export function reflectCore(tool: ToolNamer): string {
 }
 
 /**
- * Extraction nudge with escalation. Both the opencode plugin (src/runtime.ts)
- * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with
- * their respective tool name prefix. The missedCount parameter tracks
- * consecutive nudges delivered without any memory_remember call in between,
- * escalating the tone from polite to insistent to shouting.
+ * Extraction nudge with escalation - MCP hosts only (Claude Code / Cursor).
+ * There is deliberately no opencode variant: the opencode plugin extracts via
+ * its own child sessions (triggerExtraction at session idle) and no longer
+ * asks the model to run the handshake. Only hosts with no plugin lifecycle
+ * (each hook a fresh process, no session-creation API) still need a model-
+ * driven dispatch, and their file-backed queue (extract-queue.ts) is durable
+ * until the extractor's completion, so the handshake cannot lose entries
+ * there.
+ *
+ * The missedCount parameter tracks consecutive nudges delivered without any
+ * memory_remember call in between, escalating the tone from polite to
+ * insistent to shouting.
  *
  * The sessionID replaces the inline payload: the nudge tells the model to
  * dispatch a sub-agent that calls get_extraction_payload to fetch the queued
  * interactions as a tool response. This keeps the full payload out of the
  * main session's context window.
- *
- * Call extractionNudgeOpencode for the opencode plugin path (task tool with
- * background parameter) or extractionNudgeMcp for the Claude Code/Cursor
- * CLI path (generic sub-agent wording).
  */
 export function extractionNudge(
-  count: number,
-  missedCount: number,
-  toolName: string,
-  sessionID: string,
-): string {
-  const isOpencode = toolName.startsWith("thatch_");
-  return isOpencode
-    ? extractionNudgeOpencode(count, missedCount, sessionID)
-    : extractionNudgeMcp(count, missedCount, sessionID);
-}
-
-function extractionNudgeOpencode(
-  count: number,
-  missedCount: number,
-  sessionID: string,
-): string {
-  const plural = count === 1 ? "" : "s";
-  const dispatch = 'Dispatch a task with background: true and subagent_type: "general" (required for thatch tool access)';
-  const drainTool = "thatch_extraction_done";
-  const fetchTool = "thatch_get_extraction_payload";
-  return buildExtractionNudge(count, missedCount, plural, dispatch, drainTool, fetchTool, sessionID);
-}
-
-function extractionNudgeMcp(
   count: number,
   missedCount: number,
   sessionID: string,