@jeffober/thatch 0.2.1 → 0.2.3

package/docs/dev/features/extraction.md

@@ -15,19 +15,23 @@ directly for conversation-derived knowledge.
 
 - Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call for later
   extraction
-- Two paths: **direct extraction** via a child session (opencode, primary) and
-  **nudge-based extraction** (all hosts, fallback for opencode, primary for
-  MCP)
-- The extraction nudge escalates: polite (0–1 missed), insistent (2),
-  all-caps shouting (3+)
+- Two paths: **direct extraction** via a plugin-created child session (the
+  only opencode path) and **nudge-based extraction** (MCP hosts only)
+- The MCP extraction nudge escalates: polite (0–1 missed), insistent (2),
+  all-caps shouting (3+). There is deliberately no opencode nudge: the
+  model-driven handshake it required raced its own state machine (acks
+  before fetches, no-claim completions wiping in-flight sets, mis-targeted
+  session ids making every transition a silent no-op) and was removed —
+  see "Key invariants"
 - `thatch_get_extraction_payload` fetches queued interactions as JSON,
-  keeping the full payload out of the main session's context window
-- `thatch_extraction_done` acknowledges and quiets the nudge
+  keeping the full payload out of the main session's context window; the
+  fetch is also the **delivery record** (it claims the entries for that
+  fetcher)
+- `thatch_extraction_done` completes only the calling child's claimed
+  delivery — never the whole accepted set
 - AMQP-style buffer lifecycle for opencode: pending → accepted → completed,
   with requeue on failure
 - File-backed JSONL queue for MCP hosts (no cross-call state)
-- Parent-child session drain: the child drains the parent's snapshot,
-  preserving interleaved-turn entries added after the snapshot was taken
 
 ## How it works
 
@@ -71,57 +75,70 @@ calls are buffered for later extraction.
 - Filters the same tools as opencode (`mcp__thatch__memory_remember`,
   `mcp__thatch__extraction_done`, `mcp__thatch__*`, `skill`, `task`, `agent`)
 
-### Direct extraction (opencode, primary path)
+### Direct extraction (opencode, the only opencode path)
 
 When a parent session goes idle (`session.status` idle event) with pending
-buffer interactions:
+buffer interactions — after `requeueStaleAccepted()` has returned any
+timed-out accepted entries to pending:
 
 1. `triggerExtraction` adds the parent ID to the `extracting` set — this
-   suppresses the nudge in `chat.message`
+   gates re-triggering while a child runs
 2. Peeks the buffer to count pending interactions
 3. Creates a child session via
    `client.session.create({ parentID, title: "thatch-extraction" })`
 4. The `session.created` event fires, populating `childToParent` and
-   `parentSnapshots` (a snapshot of the full pending buffer at dispatch time)
+   `parentSnapshots` (a snapshot of the full pending buffer at dispatch
+   time — journal-recovery data only; claims subsumed the snapshot drain)
 5. Adds the child ID to the `extractionChildren` set
-6. Prompts the child with `extractionDirectPrompt(count, sessionID)`
+6. Prompts the child with `extractionDirectPrompt(count, sessionID)` — the
+   plugin interpolates the parent's session ID into the prompt, so no
+   model ever has to copy one
 7. If background sub-agents are enabled
    (`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`): `promptAsync`. Otherwise:
    fire-and-forget `prompt`
 8. On prompt failure: `cleanupChild` removes the child from all maps and
-   deletes the child session
+   deletes the child session. The entries stay pending; the next idle
+   retries (there is no nudge fallback)
 
 The child session then:
 
-- Calls `thatch_get_extraction_payload` to fetch the queued interactions
+- Calls `thatch_get_extraction_payload` — the fetch **claims** the entries
+  for this fetcher (claim = accept + delivery record)
 - Runs the [thatch-fact-extractor](../skills.md) skill
 - Writes memories via `thatch_memory_remember`
 - Goes idle
 
 On child idle (`session.status` idle event, extraction child):
 
-1. Drains the parent's snapshot from the pending buffer via
-   `consumeSnapshot` — removes only entries captured at dispatch time by
-   reference identity, preserving interleaved-turn entries
+1. `completeClaimed(childID)` — consumes only the entries this child
+   claimed via its 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
 2. Fires a toast with extraction metrics (only if memories were actually
    written)
-3. `completeAccepted(parentID)`, resets `missedNudges`
-4. Cleans up all maps
-5. `consume(childID)` — drains the child's own buffer
-6. Deletes the child session
+3. Cleans up all maps
+4. `consume(childID)` — drains the child's own buffer
+5. Deletes the child session
 
-### Nudge-based extraction (fallback for opencode, primary for MCP)
+If the extraction child is deleted before completing,
+`requeueClaimed`/`requeueAccepted` returns what it held to pending. If its
+completion signal never comes at all, `requeueStaleAccepted` (15 min)
+returns the accepted entries to pending — the next idle re-extracts them.
 
-If direct extraction was never triggered or threw an error (session not in
-the `extracting` set) **and** the buffer has pending interactions:
+### Nudge-based extraction (MCP hosts only)
+
+Claude Code and Cursor have no SDK client to create child sessions and no
+plugin lifecycle (each hook invocation is a fresh process), so extraction
+there is still model-driven. When the buffer has pending interactions, the
+next user prompt (`UserPromptSubmit`/`beforeSubmitPrompt`) gets an
+extraction nudge telling the agent to spawn a sub-agent for the
+fact-extractor skill.
 
-- The next user message (`chat.message` for opencode,
-  `UserPromptSubmit`/`beforeSubmitPrompt` for MCP) gets an extraction nudge
 - The nudge carries the session ID and fetch tool name — not the full
   payload — so the sub-agent calls `thatch_get_extraction_payload` to
   retrieve the interactions as a tool response
 
-**Nudge escalation** (via the `missedNudges` counter):
+**Nudge escalation** (via the file-backed missed counter):
 
 | Missed count | Tone |
 |--------------|------|
@@ -129,26 +146,29 @@ the `extracting` set) **and** the buffer has pending interactions:
 | 2 | Insistent |
 | 3+ | All-caps shouting |
 
-The buffer persists until the agent writes a memory or calls
-`thatch_extraction_done`. Ignored nudges repeat and escalate.
-
-- **opencode**: in-memory `missedNudges` map
-- **MCP hosts**: file-backed `.count` file per session
+The file-backed queue persists until the extractor completes
+(`extraction_done` with the parent's `session_id`) or the parent writes a
+memory itself. The parent's dispatch-time ack resets the escalation
+counter but does NOT drain the queue — a drain at ack time deleted the
+queue before the sub-agent fetched (the accept-before-fetch loss; the
+opencode path removed the handshake for the same failure class).
 
 ### Buffer lifecycle (opencode, AMQP-style)
 
 Buffered interactions move through four states in `ExtractionPipeline`
 (`src/extraction.ts`):
 
-- **pending** — interactions in the ring buffer. The nudge fires on
-  `chat.message`.
-- **accepted** — moved from pending by `accept()`. The nudge quiets, but
-  entries are not dropped yet.
-- **completed** — dropped by `completeAccepted()`. Triggered by a
-  `memory_remember` or `extraction_done` call in the child, or the child
-  going idle.
-- **requeued** — moved back to pending by `requeueAccepted()`. Triggered by
-  the child session erroring or being deleted before completing.
+- **pending** — interactions in the ring buffer. The idle trigger
+  (`triggerExtraction`) fires on them; there is no model-facing nudge.
+- **accepted** — moved from pending by `accept()` (a parent's legacy ack,
+  or a fetcher's claim). Entries are held, not dropped, and are still
+  served by the payload provider.
+- **completed** — dropped by `completeClaimed()` (the fetcher's completion
+  signal) or `completeAccepted()` (the parent session being deleted —
+  nothing exists to replay into).
+- **requeued** — moved back to pending by `requeueClaimed()` /
+  `requeueAccepted()` (child error or deletion before completing) or
+  `requeueStaleAccepted()` (15-minute completion timeout).
 
 Key methods:
 
@@ -157,36 +177,42 @@ Key methods:
 | `push()` | Add interaction to pending buffer (capped at 20) |
 | `peek()` | Read without clearing |
 | `consume()` | Delete the session's pending buffer (called on memory write) |
-| `accept()` | Move pending to accepted — quiet the nudge, hold entries |
-| `completeAccepted()` | Drop accepted entries — extractor finished |
-| `requeueAccepted()` | Move accepted back to pending — extractor died |
-| `consumeSnapshot()` | Remove only entries that were in the snapshot (by reference identity). Used for child-parent drain. |
-
-### Parent-child session drain
-
-When a child session writes a memory via `thatch_memory_remember`:
-
-1. `tool.execute.after` detects the memory write
-2. If in a child session (`childToParent.has(sessionID)`): track metrics,
-   `completeAccepted(parentID)`, drain the parent's snapshot via
-   `consumeSnapshot`, reset the parent's `missedNudges`
-3. `consume(sessionID)` — drains the child's own buffer
-
-`consumeSnapshot` is **snapshot-aware**: it removes only entries that were
-in the parent's buffer at dispatch time (by reference identity).
-Interleaved-turn entries — added after the snapshot was taken, while the
-child was extracting — survive. This prevents data loss when the parent
-continues working while the child extracts.
+| `accept()` | Move pending to accepted — hold entries (non-destructive) |
+| `claim()` | Accept + record WHICH fetcher received the entries — the delivery record |
+| `completeClaimed()` | Drop only the completing fetcher's claimed entries |
+| `completeAccepted()` | Drop accepted entries — used on parent deletion |
+| `requeueClaimed()` / `requeueAccepted()` | Move held entries back to pending — extractor died |
+| `requeueStaleAccepted()` | Requeue accepted entries held longer than 15 min |
+
+### Parent-child delivery (claim semantics)
+
+The payload fetch is the delivery record:
+
+1. `thatch_get_extraction_payload` with a fetcher identity calls
+   `claim(parentID, fetcherID)`: the pending buffer is accepted and the
+   fetcher's claim records exactly which entries it received
+2. The fetcher's completion signal (`extraction_done` or
+   `memory_remember` from that child) calls `completeClaimed(fetcherID)` —
+   consuming only the claimed entries, by reference identity
+3. A completion from a fetcher with no claim is a **no-op** — it processed
+   nothing, so it must not drop entries another extractor holds (a sibling
+   sub-agent going idle, or a mis-ordered ack, once wiped the whole
+   accepted set this way — the accept-then-racing-completion loss)
+4. Entries that arrived after the fetch stay pending; the next idle
+   re-extracts them
 
 ### MCP file-backed queue drain
 
 - `drainExtractionQueue(sessionID)` calls `resetMissedCount` +
   `consumeQueue` (deletes the JSONL file)
 - Triggered by: `thatch_extraction_done` called with the parent's
-  `session_id`, or `thatch_memory_remember` called
-- `appendBatch` in `extract-queue.ts` self-detects
-  `memory_remember`/`extraction_done` calls and resets the counter +
-  consumes the queue inline
+  `session_id` (the extractor's completion), or `thatch_memory_remember`
+  called by the parent itself
+- `appendBatch` in `extract-queue.ts` self-detects `memory_remember` and
+  resets the counter + consumes the queue inline. It detects
+  `extraction_done` too, but only resets the counter — draining at the
+  parent's dispatch-time ack deleted the queue before the sub-agent
+  fetched (the accept-before-fetch loss)
 
 ### The `extraction_done` tool
 
@@ -197,6 +223,10 @@ continues working while the child extracts.
 - The real state transitions happen in the host's post-tool hook
   (`tool.execute.after` for opencode, `PostToolBatch`/`appendBatch` for MCP)
 - The tool exists primarily so the model has a recognizable name to key on
+- On opencode there is no parent ack any more: a parent-side
+  `extraction_done` is tolerated as a non-destructive accept (entries
+  held, not dropped) for backward compatibility with an in-flight older
+  nudge
 
 ### The `get_extraction_payload` tool
 
@@ -226,14 +256,15 @@ continues working while the child extracts.
 - [Memory store](memory-store.md) — extraction writes memories via
   `thatch_memory_remember`
 - [Nudge pipeline](nudge-pipeline.md) — the extraction nudge is tier 1
-  (highest priority, returns early)
+  (highest priority, returns early) on MCP hosts; opencode's
+  `chat.message` runs the recall tier only
 - [Session lifecycle](session-lifecycle.md) — direct extraction is triggered
   by `session.status` idle; child lifecycle is managed by the event handler
 - [Skills](../skills.md) — the thatch-fact-extractor skill is dispatched to
   child sessions
 - [Multi-host](multi-host.md) — in-memory ring buffer for opencode,
   file-backed queue for MCP hosts
-- [Compaction recovery](compaction-recovery.md) — extraction nudge is
+- [Compaction recovery](compaction-recovery.md) — nudges are
   suppressed during compaction (tools are blocked)
 
 ## Source files
@@ -242,25 +273,33 @@ 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/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 |
+| `src/runtime.ts` | opencode hooks: `tool.execute.after`, `session.status` idle (direct extraction trigger), `session.created`, `session.error`, `session.deleted`, `chat.message` (recall/prediction/behavior nudges; no extraction nudge) -- shared by the v1/v2 adapters |
 | `bin/thatch` | `buffer-batch`, `buffer-tool`, `flush-tools` subcommands |
 | `src/prompts.ts` | `extractionNudge` (with escalation), `extractionDirectPrompt` |
 
 ## Key invariants
 
-1. **Tool filtering is absolute.** `thatch_*`, `skill`, and `task` tools are
-   never buffered. Buffering them would echo the store into itself or create
-   a feedback loop.
-2. **The nudge peeks, never flushes.** The buffer persists until a memory
-   write or `extraction_done`. Ignored nudges repeat and escalate.
-3. **`consumeSnapshot` is snapshot-aware.** It removes only entries captured
-   at dispatch time (by reference identity), preserving interleaved-turn
-   entries added while the child was extracting.
+1. **Tool filtering is absolute.** `thatch_*`, `skill`, `task`, and
+   `subagent` tools are never buffered. Buffering them would echo the store
+   into itself or create a feedback loop.
+2. **Extraction never depends on model cooperation on opencode.** The
+   plugin creates the extraction child, interpolates the session ID, and
+   drives the lifecycle from events. The old model-driven handshake (model
+   dispatches, parent acks, child copies the ID) raced its own state
+   machine — the September 2026 dispatch-loop report (accept-before-fetch
+   loss + never-terminating re-nudge) — and was removed. The opencode
+   `chat.message` hook computes no extraction nudge.
+3. **Completion is claim-scoped.** Only a fetcher that recorded a claim
+   (via `get_extraction_payload`) can consume entries, and only the entries
+   it received. No-claim completions are no-ops; no transition drops
+   entries another extractor holds. The stale reaper bounds any orphan
+   linger at 15 minutes.
 4. **`tool.execute.after` is a plugin hook, not a bus event.** The event bus
    has no such event. Moving the buffering logic into the `event` handler
    silently never fires it.
 5. **MCP host hooks must be silent.** `PostToolBatch`/`postToolUse` produce
    no stdout — only `flush-tools` prints. Any stdout delays the agent loop.
-6. **The no-save drain runs unconditionally.** The child-idle handler drains
-   the remaining snapshot regardless of whether the child wrote memories,
-   covering no-save extraction runs.
+6. **The MCP queue is durable until the extractor completes.** The
+   parent's dispatch-time ack must not drain it (see the invariant above);
+   the drain happens at the extractor's completion or the parent's own
+   memory write.

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/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)