@jeffober/thatch 0.2.2 → 0.2.4

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

@@ -2,7 +2,7 @@
 
 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
+Runs on every user message. 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
 toast notifications, which are TUI-visible but model-invisible.
@@ -10,16 +10,18 @@ toast notifications, which are TUI-visible but model-invisible.
 The nudge pipeline is thatch's core innovation. It is not a passive
 store-and-retrieve system. It is a nudge layer that changes agent behavior by
 injecting context at the right moment. See [extraction.md](extraction.md) for
-the extraction nudge, [prediction-engine.md](prediction-engine.md) for the
+the extraction pipeline (plugin-driven on opencode; nudged on MCP hosts only),
+[prediction-engine.md](prediction-engine.md) for the
 prediction auto-fire, and [behavior-engine.md](behavior-engine.md) for the
 behavior auto-fire.
 
 ## What it does
 
-On every user message, thatch runs through four priority tiers:
+On every user message, thatch runs through the priority tiers:
 
-1. **Extraction nudge**---if tool interactions are buffered, tell the agent to
-   extract memories.
+1. **Extraction nudge** (MCP hosts only)---if tool interactions are queued,
+   tell the agent to dispatch an extractor. There is deliberately no
+   opencode extraction nudge: extraction is plugin-driven at session idle.
 2. **Recall nudge**---semantically search stored memories for context
    relevant to the user's prompt.
 3. **Prediction nudge**---surface user decision-model predictions relevant to
@@ -28,14 +30,16 @@ On every user message, thatch runs through four priority tiers:
    current situation.
 
 Tiers 2--4 fire independently and share one embedding computation. Tier 1
-returns early, skipping tiers 2--4.
+(extraction) exists only on the MCP path.
 
 ## How it works
 
-Two host paths deliver the same four tiers through different mechanisms. The
-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.
+Two host paths deliver the tiers through different mechanisms. The opencode
+path runs in-process with direct event hooks and has THREE tiers (recall,
+prediction, behavior - extraction is plugin-driven at session idle, not
+nudged). The MCP path runs via external CLI hook processes that communicate
+with the long-lived MCP server through the sideband socket and keeps all
+four.
 
 ### opencode path (`src/runtime.ts`, `onChatMessage` - v1 `chat.message` hook, v2 `session.hook("prompt")`)
 
@@ -53,28 +57,25 @@ See [compaction-recovery.md](compaction-recovery.md).
 
 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
+returns early. 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
+error rounds or noise. See
 [session-lifecycle.md](session-lifecycle.md) for the `extractionChildren`
 distinction.
 
-#### Tier 1---Extraction nudge (fallback path)
+#### Tier 1---Extraction nudge: REMOVED from opencode
 
-Fires only when direct extraction was never triggered or threw (the session is
-not in the `extracting` set) **and** the in-memory buffer has pending
-interactions.
-
-- Injects `extractionNudge(count, missed, "thatch_memory_remember", sessionID)`
-  as a synthetic text part.
-- Increments the `missedNudges` counter for escalation: polite at 0, insistent
-  at 2, ALL-CAPS shouting at 3+.
-- Returns early. Tiers 2--4 are skipped.
-
-See [extraction.md](extraction.md) for the full extraction pipeline, including
-the accept/complete/requeue lifecycle and the `extracting` set.
+There is deliberately no extraction nudge on the opencode path. The old
+model-driven handshake (nudge → model dispatches a sub-agent → parent acks
+with `thatch_extraction_done` → child fetches by a model-copied session ID)
+raced its own state machine: the parent's ack accepted the buffer before
+the child fetched, a no-claim completion wiped the accepted set, and
+mis-targeted IDs made every transition a silent no-op - so the same queued
+count re-fired forever while buffered interactions were silently lost (the
+September 2026 dispatch-loop report, both defects). Extraction on opencode
+is now plugin-driven end-to-end (`triggerExtraction` at session idle); see
+[extraction.md](extraction.md). The MCP path keeps its nudge - see below.
 
 #### Tier 2---Recall nudge
 
@@ -127,8 +128,7 @@ and the self-discipline rule data model.
 #### Tier independence
 
 Tiers 2, 3, and 4 all fire independently. Any subset may inject. All share
-one embedding computation. The embedding is computed once, after the
-extraction tier returns early, and is reused across three cosine scans against
+one embedding computation, reused across three cosine scans against
 different tables.
 
 ### MCP path (`bin/thatch`, `flush-tools` subcommand)
@@ -156,10 +156,14 @@ Three priority tiers, first match wins:
 #### Tier 1---Extraction nudge
 
 - `peekQueue(sessionID)` peeks the file-backed JSONL queue without draining
-  it. The queue persists until the agent calls `memory_remember`, which
-  triggers `consumeQueue`.
+  it. The queue persists until the extractor completes
+  (`extraction_done` with the parent's session id) or the agent calls
+  `memory_remember`, which triggers `consumeQueue`. The parent's
+  dispatch-time ack resets the escalation counter but does NOT drain - a
+  drain at ack time deleted the queue before the sub-agent fetched (the
+  accept-before-fetch loss).
 - If interactions are pending: increments the missed count, prints
-  `extractionNudge(count, missed, "mcp__thatch__memory_remember", sessionID)`.
+  `extractionNudge(count, missed, sessionID)`.
 - Breaks. Tiers 2--3 are skipped.
 
 See [extraction.md](extraction.md) for the file-backed queue and the
@@ -253,9 +257,10 @@ TUI display. The opencode framework's history serializer filters on
 
 ## Interactions with other features
 
-- **Extraction pipeline** ([extraction.md](extraction.md)): tier 1 is the
-  extraction nudge. The `extracting` set suppresses tier 1 when direct
-  extraction is active.
+- **Extraction pipeline** ([extraction.md](extraction.md)): the MCP tier 1
+  is the extraction nudge. On opencode there is no extraction
+  nudge - extraction is plugin-driven at session idle, so `chat.message`
+  runs the recall/prediction/behavior tiers only.
 - **Memory store** ([memory-store.md](memory-store.md)): tier 2 searches
   stored memories via `db.search()`. This path records no telemetry---the
   agent has not read the memories yet.
@@ -272,21 +277,21 @@ TUI display. The opencode framework's history serializer filters on
   the nudge pipeline is suppressed during compaction. The compaction guard
   clears stale flags when compaction fails.
 - **Session lifecycle** ([session-lifecycle.md](session-lifecycle.md)):
-  direct extraction (`triggerExtraction`) suppresses tier 1 by adding the
-  session to the `extracting` set.
+  direct extraction (`triggerExtraction`) is triggered by session idle;
+  there is no extraction tier to suppress on opencode.
 
 ## Source files
 
 | File | Role |
 |------|------|
-| `src/runtime.ts` | opencode: per-message nudges (all 4 tiers), compaction guard, extraction fallback |
-| `bin/thatch` | MCP: `flush-tools` and `flush-predictions` subcommands |
+| `src/runtime.ts` | opencode: per-message nudges (recall/prediction/behavior tiers; no extraction nudge), compaction guard |
+| `bin/thatch` | MCP: `flush-tools` and `flush-predictions` subcommands (all 4 tiers) |
 | `src/sideband.ts` | MCP: sideband client helpers (`sidebandMatch`, `sidebandPredictions`, `sidebandBehaviors`) |
 | `src/prompts.ts` | All nudge formatting functions (`recallNudge`, `claudeRecallNudge`, `predictionNudge`, `behaviorNudge`, `extractionNudge`, `claudeWriteNudge`) |
 
 ## Key invariants
 
-- Tier 1 (extraction) returns early. Tiers 2-4 are skipped when tier 1 fires.
+- Tier 1 (extraction, MCP only) returns early. Tiers 2-4 are skipped when tier 1 fires.
 - Tiers 2-4 share one embedding computation. One embed, three cosine scans against different tables.
 - Each tier is wrapped in its own try/catch. A failure in one tier does not block the others.
 - The recall nudge uses `db.search()`, not `db.recall()`, to avoid inflating telemetry. The agent has not read the memories yet.

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

@@ -27,7 +27,10 @@ Subscribes to all session bus events. Dispatches based on `event.type`.
 2. Snapshot the parent's current pending buffer: `parentSnapshots.set(childID, [...extraction.peek(parentID)])`
 3. Return early -- child sessions don't get the session-start reminder
 
-This snapshot is used by `consumeSnapshot` for snapshot-aware drain: when the child writes memories, only the snapshot entries are removed from the parent's buffer, preserving interleaved-turn entries that were added after the snapshot was taken.
+The snapshot is journal-recovery data only (restored child bookkeeping
+after a reload); live delivery is claim-based: the child's payload fetch
+records exactly which entries it received, and its completion signal
+consumes only those.
 
 ### session.created without parentID (top-level session)
 
@@ -39,20 +42,22 @@ This snapshot is used by `consumeSnapshot` for snapshot-aware drain: when the ch
 
 When a child created by `triggerExtraction` goes idle:
 
-1. Drain the parent's snapshot from pending buffer via `consumeSnapshot` (if still present -- a no-save run's entries need draining so they don't replay; a save run already drained them via `tool.execute.after`)
-2. Never drains the entire buffer -- interleaved-turn entries survive
-3. Fire a toast with extraction metrics (new/updated/deleted counts) -- only if memories were actually written
-4. `completeAccepted(parentID)`, reset `missedNudges`
-5. Clean up all maps: `extracting`, `childToParent`, `parentSnapshots`, `childMetrics`, `extractionChildren`
-6. `consume(childID)` -- drain child's own buffer
-7. Delete the child session via `client.session.delete`
+1. `completeClaimed(childID)` -- consume only the entries this child
+   claimed via its payload fetch. A no-claim idle is a no-op: a child that
+   never fetched processed nothing, and its idle signal must not drop
+   entries another extractor holds. Held entries with no completer are
+   bounded by the 15-minute stale reaper
+2. Fire a toast with extraction metrics (new/updated/deleted counts) -- only if memories were actually written
+3. Clean up all maps: `extracting`, `childToParent`, `parentSnapshots`, `childMetrics`, `extractionChildren`
+4. `consume(childID)` -- drain child's own buffer
+5. Delete the child session via `client.session.delete`
 
 ### session.status idle -- task-dispatched sub-agent
 
 When a task-dispatched sub-agent (not created by `triggerExtraction`) goes idle:
 
-- `completeAccepted(parentID)` -- complete the parent's accepted entries (from the nudge-path `extraction_done` accept)
-- Reset `missedNudges`
+- `completeClaimed(childID)` -- complete only what THIS child claimed via
+  its payload fetch (a no-claim idle consumes nothing)
 - Does NOT drain the buffer or delete the session -- the task tool that dispatched the sub-agent needs to read its output
 
 ### session.status idle -- parent session
@@ -60,8 +65,9 @@ When a task-dispatched sub-agent (not created by `triggerExtraction`) goes idle:
 When a parent session (no parentID) goes idle:
 
 - Wrap-up resolution first (below): a pending `/thatch/compact` or `/thatch/exit` resolves here, and a greenlit action returns early
+- `requeueStaleAccepted()` first: accepted entries whose completion signal never came (15 min) return to pending
 - If not compacting, not already extracting, and buffer has pending interactions: `triggerExtraction(sessionID)`
-- On failure: log error, clear `extracting` flag (nudge path takes over as fallback on next chat.message)
+- On failure: log error, clear `extracting` flag (the next idle retries -- there is no model-facing nudge fallback)
 
 ### Wrap-up commands (`/thatch/compact`, `/thatch/exit`)
 
@@ -84,12 +90,21 @@ first-ever install is invisible until the next server start.
 
 ### session.error (child session)
 
-- `requeueAccepted(parentID)` -- move parent's accepted entries back to pending (the extractor never processed them)
+- `requeueClaimed(childID)` if it fetched (the delivery was never
+  processed), else `requeueAccepted(parentID)` -- the error is a terminal
+  death signal, so a claim-less child falls back to whole-set requeue for
+  immediate recovery
+- Clear `extracting` for the parent (the next idle re-triggers)
 - Clean up all maps for the child
 
 ### session.deleted -- child
 
-- `requeueAccepted(parentID)` -- entries go back to pending (never processed)
+- Extraction child: `requeueClaimed(childID)`, else
+  `requeueAccepted(parentID)` (never processed)
+- Task-kind child: `requeueClaimed(childID)` only -- task children are
+  deleted ROUTINELY, so a claim-less task child's deletion must not requeue
+  the whole accepted set (it would yank an in-flight extractor's payload
+  back to pending for duplicate extraction)
 - Clean up all maps for the child
 
 ### session.deleted -- parent
@@ -106,21 +121,20 @@ first-ever install is invisible until the next server start.
 ### Internal state maps
 
 - **childToParent**: `Map<childID, parentID>` -- maps child sessions to their parents
-- **parentSnapshots**: `Map<childID, Interaction[]>` -- snapshot of parent's buffer at child creation time
+- **parentSnapshots**: `Map<childID, Interaction[]>` -- snapshot of parent's buffer at child creation time (journal recovery only; live delivery is claim-based)
 - **childMetrics**: `Map<childID, {new, updated, deleted}>` -- extraction metrics per child
-- **extracting**: `Set<parentID>` -- parent IDs with an active direct-extraction child (suppresses nudge)
+- **extracting**: `Set<parentID>` -- parent IDs with an active direct-extraction child (gates re-triggering)
 - **extractionChildren**: `Set<childID>` -- distinguishes extraction children from task-dispatched sub-agents
 - **compacting**: `Set<sessionID>` -- sessions currently being compacted (suppresses nudges)
 - **pendingWrapUp**: `Map<sessionID, {token, kind}>` -- wrap-up commands awaiting their greenlight check; armed by `command.execute.before`, resolved on the next idle, cleared on session deletion
-- **missedNudges**: `Map<sessionID, number>` -- extraction nudge escalation counter
 
 ## 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; task-dispatched sub-agents (in `childToParent`, not in `extractionChildren`) suppress all tiers
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `compacting` set suppresses all nudges; 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`
+- Memory store ([memory-store.md](memory-store.md)): child sessions write memories via `memory_remember`, which completes their claimed delivery via `tool.execute.after`
 
 ## Source files
 
@@ -130,7 +144,7 @@ first-ever install is invisible until the next server start.
 ## Key invariants
 
 - Child sessions don't get the session-start reminder (early return in `session.created` with parentID).
-- `consumeSnapshot` is snapshot-aware: removes only entries captured at dispatch time, preserving interleaved-turn entries.
+- Delivery is claim-based: the payload fetch records what the fetcher received; only the fetcher's completion consumes it. A no-claim completion is a no-op, never a whole-set drop.
 - Extraction children are deleted after going idle; task-dispatched sub-agents are NOT deleted (task tool reads output).
-- Child errors requeue the parent's accepted entries (never processed). Child deletion also requeues.
+- Child errors requeue what the child held (never processed). Child deletion also requeues.
 - Parent deletion completes accepted entries (takes them with it).

package/docs/dev/features/setup.md

@@ -18,6 +18,8 @@ resolution fit together.
   hooks, and skills for Cursor
 - `--global` flag --- installs to user-scoped config dirs instead of
   project-local
+- `--skills-only` flag --- refreshes just the skill files (same host and
+  scope rules), skipping MCP config, instructions, hooks, and commands
 - **Marker system** --- idempotent replacement of the thatch instruction block
   in `CLAUDE.md` or `AGENTS.md` via start/end markers
 - **`checkSetup`** --- detects installed, not-installed, or markers-broken at
@@ -35,6 +37,11 @@ resolution fit together.
 
 At least one of `--claude` or `--cursor` is required. Both can be passed
 together. `--global` applies to whichever host or hosts are selected.
+`--skills-only` narrows the run to the skill install (`setupSkillsOnly`
+in `src/setup.ts`): it reuses the same path resolution and other-scope
+probe as the full setup paths but only calls `installSkills`, so it is
+safe to run in an already-set-up host when only the skill files need
+refreshing.
 
 ### Claude Code setup (`setupClaudeCode` in `src/setup.ts`)
 

package/docs/dev/features/watchers.md

@@ -73,6 +73,15 @@ gh setup fails registration with a real error instead of producing a
 watcher that never fires. Watch creation is also gated on a cached
 `gh --version` availability check.
 
+CI events (`pr_ci`, `branch_ci`) fire only on a running -> completed
+check-run transition, so a watcher registered after a fast pipeline has
+already finished holds completed runs in its baseline and can never
+notify for that head. When every check run on the head is already
+completed at registration, the tool response says so, with the
+conclusion breakdown (`describeBaselineCheckRuns`), so the caller reads
+the result instead of waiting on a notification that cannot come. The
+rule for catching a push's CI: register the watcher before pushing.
+
 ### Polling
 
 A `setInterval` loop (unref'd - it never keeps the process alive)

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

package/docs/dev/mcp-parity.md

@@ -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/user/cli.md

@@ -148,7 +148,8 @@ thatch buffer-batch             # append tool batch to queue (Claude Code hook)
 thatch buffer-tool              # append single tool to queue (Cursor hook)
 thatch flush-tools [--json]     # peek queue + print nudges (hook)
 thatch flush-predictions [--json]  # prediction-only nudge (hook)
-thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
+thatch setup --claude [--cursor] [--global]     # install config + hooks + skills
+thatch setup --claude --skills-only             # refresh just the skill files
 ```
 
 ## Environment variables

package/docs/user/setup.md

@@ -60,6 +60,16 @@ Skills follow the install scope: project-local installs them to the
 repo's `.claude/skills/` so they version with the project; `--global`
 installs them to `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`).
 
+To refresh just the skill files without rewriting anything else, add
+`--skills-only`:
+
+```bash
+thatch setup --claude --skills-only
+```
+
+This skips the MCP config, instructions, hooks, and commands, and
+reports the same skills directory and install counts as a full run.
+
 `bun` must be on PATH (the thatch binary runs under bun). Setup is
 idempotent. Re-running it updates drifted content without clobbering
 unrelated config, and reports what it did: the skills directory plus
@@ -84,6 +94,9 @@ thatch setup --cursor --global   # user-scoped (~/.cursor/)
 Skills follow the install scope: project-local installs them to the
 repo's `.cursor/skills/`; `--global` installs them to `~/.cursor/skills/`.
 
+As with Claude Code, `--skills-only` refreshes just the skill files and
+skips the MCP config, instructions, and hooks.
+
 Cursor uses a flat hooks format (`{version, hooks:{event:[{command}]}}`)
 and `--json` output for hook commands.
 

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.2",
+  "version": "0.2.4",
   "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/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