@jeffober/thatch 0.1.21 → 0.1.22

package/artifacts/skills/thatch-fact-extractor.md

@@ -17,7 +17,8 @@ You will be given a JSON payload with:
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
 4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
 5. Write for a future session with zero current context. No "we", "our session", "just now".
-6. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
+6. Call thatch_extraction_done to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
+7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
 
 ## What to extract
 

package/artifacts/skills/ticket-description.md

@@ -44,7 +44,7 @@ Sections, in order: SYNOPSIS, PROBLEM, BACKGROUND (conditional), PROPOSED APPROA
 
 **SYNOPSIS, PROBLEM, PROPOSED APPROACH, and ACCEPTANCE CRITERIA are mandatory.** A small ticket gets short sections, not fewer sections. Conditional sections appear only when warranted; omit them when empty. Never emit an empty header.
 
-**Scale the body to the work's conceptual size.** A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause.
+**Scale the body to the work's complexity, not its size in files or lines.** Estimate complexity by how much new mental model the implementer must build (see the point-based budgets in Length and style). A one-line fix gets a one-line PROBLEM, a one-line PROPOSED APPROACH, and one or two acceptance criteria. A multi-PR feature gets full sections with real depth. The implementer should be able to start work after reading the ticket, but they should not have to read a novel to fix a guard clause. Most of this skill's guidance exists to tame large tickets; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
@@ -66,11 +66,13 @@ The reader should know what the problem is before they read why it happens.
 
 No solution yet. The reader should finish this section agreeing there is something to address, even with zero code knowledge.
 
-Cover three things, each in its own paragraph:
+Cover three things, each in its own paragraph when the ticket has the complexity to warrant it:
 1. **What is wrong**, concretely. Name the component, the behavior, and the failure mode.
 2. **Why it matters.** Incident history, risk rating, customer impact, or "preventive: blocks a class of bug we keep almost-hitting."
 3. **Hazard rating and motivation.** How likely is the bad outcome, and under what conditions? Then answer "why now?": if the risk is low, what motivates this ticket? A prior PR identified it as a follow-up, the API still permits a failure shape, or the next planned change would make it worse. The lead's question is "should I prioritize this?" - give them the answer. _PLAT-135's ticket did this well: it named the cross-wait, then said "why it never fired" and rated the window as once-per-process cold load._
 
+A small ticket covers all three in a single paragraph; split into one paragraph per topic only when the content earns it.
+
 If the problem is preventive (no current defect), say so plainly. Then say why it is worth fixing despite the low risk.
 
 ### BACKGROUND (conditional)
@@ -89,6 +91,8 @@ Omit when the problem is self-contained. A one-line "follow-up from #6838" can l
 
 The design concept. Not a full implementation plan. Enough that the implementer knows the direction: "load key material outside the mutex" not "restructure ActiveKey to use cachedKey/publish helpers with a publish function that zeroizes the loser's DEK." The implementer writes the implementation plan; the ticket sets the compass heading.
 
+Present each mechanism in one short paragraph: what it does, plus the constraint that justifies its existence. Keep a justification when it answers an objection the reader will have (a lock that looks redundant, a retry that looks pointless). Compress failure-mode sagas to their consequence: "a leaked lock blocks every later attempt" carries what a paragraph of driver internals would. Reasons of the form "why not X" (no metric, no kill switch, no singleflight) go in NOTES as declined alternatives.
+
 For investigative tickets, this is "investigate X and propose a solution" rather than a concrete approach. Say so explicitly so the implementer knows the ticket expects analysis before implementation.
 
 This is where the ticket diverges most from a PR description. A PR description describes a change that already happened. A ticket proposes one that hasn't. The prose is prescriptive ("the fix should...") rather than descriptive ("this PR moves...").
@@ -105,7 +109,9 @@ Bad criteria are vague:
 - "improve the locking situation" (untestable)
 - "restructure ActiveKey" (implementation detail, not a behavior)
 
-If the criterion has a test shape, name it: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation.
+If a criterion's test design is non-obvious, name the test shape: "SetMaxOpenConns(1) with the connection held by a tx that also resolves the key." This gives the implementer the test design without dictating the implementation. "Tested explicitly" is not a test shape.
+
+Keep the list coarse: three to seven criteria cover most tickets. This section defines "done"; it is not a test inventory. Merge parallel checks that verify the same behavior under different triggers. Drop criteria that restate PROPOSED APPROACH as a checklist - the criterion must add an observable gate, not echo the design.
 
 ### RELEASE PLAN (conditional)
 
@@ -115,7 +121,7 @@ Rollout strategy for tickets that change production behavior. Only when the chan
 - Deploy sequence (which services, in what order).
 - Rollback path (what to do if it goes wrong).
 
-A pure internal refactor with no operator-visible behavior change does not need this section. A migration that gates on a backfill completing does.
+A pure internal refactor with no operator-visible behavior change does not need this section. Neither does a change whose rollout is a normal deploy: if the only available bullets say "nothing special happens," omit the section - its absence is the nothing-special signal. A migration that gates on a backfill completing, or a revert that is not free, does need it.
 
 ### VALIDATION (conditional)
 
@@ -129,10 +135,12 @@ Only when prod verification is non-trivial. A pure refactor with good tests does
 
 ### DEPENDENCIES (conditional)
 
-Blocking relationships and ordering constraints. "Blocked by PLAT-126" is the tracker field; the _why_ belongs here: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue.
+The tracker's blocker links carry the what; this section carries only what links cannot. Write a bullet when there is a _why_ the link cannot express: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue. "Blocked by PLAT-126" with nothing to add is the tracker field - set the link there and omit the bullet.
 
 Distinguish hard data dependencies (cannot run until X completes) from soft dependencies (should run after X for cleanliness, but technically works independently). Say which kind it is.
 
+If every bullet would restate a tracker link, omit the section and set the links.
+
 ### NOTES
 
 Always a `## NOTES` markdown header. Never a bare `Notes:` line ending a section.
@@ -195,12 +203,24 @@ These are hard rules, not suggestions.
 
 ## Length and style
 
-Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM.
+Target: the implementer can start work after one read. The lead can prioritize after reading SYNOPSIS and PROBLEM. Err on the shorter side.
+
+Estimate the ticket's **complexity** (how much new mental model the implementer must build), not its size in files or lines. Complexity drives the word budget the way scrum points drive effort estimates:
+
+- **1 point** (one guard, one flag, one constant): the implementer needs to know what to change, not a lesson in the subsystem. ~100-200 words. SYNOPSIS one line, PROBLEM 2-4 sentences (still rate the hazard, even if it is "no current defect"), PROPOSED APPROACH 1-2 sentences, one to three acceptance criteria.
+- **2-3 points** (new function, restructured flow, multi-file refactor): the implementer needs a before/after they cannot infer from the code alone. ~200-400 words. Full mandatory sections; BACKGROUND only when prior work or project context earns it.
+- **5 points** (new feature, migration sequence): the implementer needs a mental model they do not have yet. ~400-600 words. RELEASE PLAN, VALIDATION, and DEPENDENCIES when prod coordination warrants.
+- **8 points** (multi-PR effort, subsystem redesign, constraint-dense work): ~800-1100 words. Complex tickets legitimately need more text; spend it on context and starting state, not on repetition. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
 
-Scale the body to the work's conceptual size:
-- Small fix (one guard, one flag, one constant): one paragraph per mandatory section, one to three acceptance criteria. ~20-line ceiling.
-- Moderate change (new function, restructured flow, multi-file refactor): full sections with real depth. No hard ceiling, but each paragraph earns its place.
-- Large change (new feature, multi-PR effort, migration sequence): full sections plus RELEASE PLAN and VALIDATION. May run a full page. If PROPOSED APPROACH is longer than the rest of the ticket combined, the ticket is probably a design doc wearing a ticket costume; split it.
+Estimate by: how many new concepts the implementer must learn, whether the problem and approach have non-obvious mechanics, whether the work spans multiple workflows or systems. Not by files the change will touch or sections present. A mechanical multi-file rename is 1 point. A one-line fix with subtle semantics is 2-3.
+
+**When a ticket runs long, take the section-level levers first.** Omit RELEASE PLAN, VALIDATION, DEPENDENCIES, or NOTES when they carry nothing a normal deploy or the tracker links already say. Coarsen ACCEPTANCE CRITERIA. Compress PROPOSED APPROACH failure sagas to their consequences. These levers remove duplication, not knowledge.
+
+**Then step up the abstraction ladder.** Do not compress terminology or cut connective tissue to hit a word count. Instead, replace a sequence of mechanism details with the principle that subsumes them.
+
+Example: instead of six claims about how a connection pool reuses connections, how session locks are session-scoped, how a lock taken by one statement does not guard the next, and how nothing reports the mismatch, write: "Some Postgres features attach to the connection, not the statement. The pool freely reuses connections between statements, so state set by one statement may not be there for the next, and nothing reports the mismatch." Same understanding, fewer words, no compression. The mechanism details belong in the linked design doc or the code itself, not in the ticket.
+
+Brevity means fewer ideas, not compressed claims. If the ticket is still too long after the levers and the ladder, cut the lowest-value claim entirely. Do not cut the connective tissue that makes the remaining claims parse on first read. The knowledge build-up - each section introducing what the next one needs - survives every trim; what goes is redundancy.
 
 Inside sections, telegraphic bullet style is fine for criteria and plans: lowercase start, abbreviations (`w/`, `1x`, `~`), parenthetical shorthand. Full sentences for PROBLEM and BACKGROUND prose.
 
@@ -231,6 +251,8 @@ Read project context when the request, existing ticket, code comments, branch na
 
 Use available source material: linked tickets, linked PRs, nearby docs, code comments, commit messages, and project memory. Build a private term map: term -> plain behavior -> source. Do not dump the map into the ticket. Use it to write the shortest useful BACKGROUND.
 
+When rewriting an existing ticket, mine the old text for facts - harm statements, platform behaviors, traps already discovered - but draft the new description from the sources, not from the old text. Editing the old ticket inherits its phrasing and its habits; the rewrite should stand on the plan docs, the code, and the mined facts.
+
 If a term or dependency controls the work and you cannot resolve it from available context, stop and ask the user. Do not guess. Do not write around the missing definition with vaguer words.
 
 Put project context in BACKGROUND only when it helps the implementer start work or helps a lead schedule it correctly. Omit generic backstory.
@@ -389,14 +411,14 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 1. **Gather**: read the code the ticket references. Check `git log` for recent changes to the same files. Identify the problem, the prior work, and the proposed direction.
 2. **Search before create**: search Linear/Jira for likely duplicate tickets. If one exists, surface it before drafting or filing.
 3. **Codebase comparison**: verify the problem still exists in the current code. If it was already fixed, tell the user. If it was partially mitigated, note the mitigation.
-4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user.
+4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user. When rewriting an existing ticket, mine the old text for facts but draft fresh.
 5. **Draft PROBLEM first**, in one breath, without looking at code. If you cannot state the harm in three sentences, you do not understand the problem yet. Go back and read.
 6. **Write BACKGROUND** (if needed): what prior work led here, what was done, what was left behind, and what project context an engineer new to this area needs to start.
-7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice.
-8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Name the test shape where relevant.
-9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback.
+7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice. One short paragraph per mechanism, each with the constraint that justifies it; compress failure sagas to their consequence; move "why not X" reasoning to NOTES.
+8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Coarse: three to seven, merging parallel checks and dropping restatements of the approach. Name the test shape only where the test design is non-obvious.
+9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback. Omit when the rollout is a normal deploy.
 10. **Write VALIDATION** (if needed): monitoring, signals, smoke tests.
-11. **Write DEPENDENCIES** (if needed): what blocks this, what this blocks, and why.
+11. **Write DEPENDENCIES** (if needed): only the why that tracker blocker links cannot express. Omit when the links carry it; set the links instead.
 12. **Write SYNOPSIS last** - it is a compression of PROBLEM + the core approach.
 13. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the work (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check.
 14. **Add NOTES** for non-goals, declined alternatives, and scope limits. Use `## NOTES` header. Omit if empty.
@@ -404,7 +426,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 16. **Verify links**: check repo file links, external docs, tickets, PRs, and design artifacts where tooling allows. Do not claim an unverified link was verified.
 17. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify prescriptive voice (not descriptive). Verify first-use definitions for subsystem jargon in BACKGROUND or PROBLEM. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PROBLEM. Verify NOTES bullets are either short pointers or self-contained.
 18. **Clarity pass**: read the draft as a cold lead skimming a backlog, then as an implementer picking up the work cold. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with specific behavior? Does every process word name object/action/effect? Does every contrast name current and proposed behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
-19. **Verify length**: if the body exceeds what the work's conceptual size warrants, cut until each line earns its place. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
+19. **Verify length**: estimate the ticket's complexity (see the point-based budgets in Length and style). If the body exceeds the budget, take the section-level levers first (omit conditional sections that duplicate the tracker or a normal deploy, coarsen acceptance criteria, compress approach sagas), then step up the abstraction ladder (replace mechanism sequences with the principle that subsumes them). If still over, cut the lowest-value claim entirely. Do not compress terminology or cut connective tissue to hit a word count. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
 
 ## Anti-patterns
 
@@ -427,3 +449,7 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 - **Conclusion buried at the end.** PROBLEM that builds to its point in the last sentence forces the reader to absorb the explanation before knowing what is being explained. Lead with the problem, then explain why.
 - **Hazard rating without motivation.** "No incident has hit this shape" answers "how bad?" but not "why prioritize this?" Answer "why now?" so the lead can decide whether to schedule it.
 - **NOTES bullets that are both wordy and terse.** A bullet that compresses a paragraph of rationale into one dense sentence reads as a private note. Either flag the thing and point to the full explanation, or write a self-contained sentence or two. Not the middle thing.
+- **RELEASE PLAN that argues the release is boring.** If every bullet says the rollout is routine, omit the section. Its absence is the nothing-special signal.
+- **DEPENDENCIES that restate tracker links.** "Blocked by PLAT-126" with nothing to add is the tracker field. Set the link; keep the section only for the why a link cannot express.
+- **Test inventory as acceptance criteria.** A dozen bullets covering every code path is a test plan, not a definition of done. Keep three to seven observable gates; merge parallel checks.
+- **Failure sagas in PROPOSED APPROACH.** Paragraphs of driver internals, pool lifecycle, or library quirks. Compress to the consequence; the implementer discovers the saga at the keyboard.

package/docs/qa/use-cases/README.md

@@ -28,7 +28,7 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-017](UC-017-buffer-tool-vs-buffer-batch.md) | `buffer-batch` (Claude, `tool_calls[]`+`session_id`) vs `buffer-tool` (Cursor, single+`conversation_id`) |
 | [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 | [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
-| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` drain |
+| [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` accept/complete |
 | [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
 | [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
 | [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |

package/docs/qa/use-cases/UC-003-extraction-nudge.md

@@ -18,13 +18,15 @@ client and a synthetic tool call sequence._
 - The agent loads `thatch-fact-extractor` and saves durable facts via
   `thatch_memory_remember` — or saves nothing if the activity was routine.
 - The buffer is **not** drained on nudge delivery — it persists until the agent
-  writes a memory or calls `thatch_extraction_done`. If the nudge is ignored,
+  writes a memory or accepts it by calling `thatch_extraction_done`. Accepting
+  quiets the nudge while holding the entries until the extractor completes; a
+  child extractor that errors or is deleted requeues them. If the nudge is ignored,
   the next message carries a repeat nudge, escalating in urgency:
   - 1st-2nd miss: polite tone
   - 3rd consecutive miss (missedCount=2): insistent (directive) tone
   - 4th+ consecutive miss (missedCount>=3): ALL-CAPS tone
-  The counter resets when the buffer drains (memory write or
-  `thatch_extraction_done`).
+  The counter resets when the buffer drains (memory write) or is accepted
+  (`thatch_extraction_done`).
 - A `thatch_memory_remember` call in a child sub-agent session also drains the
   parent's buffer (via the `childToParent` Map), so dispatching the
   fact-extractor as a background task clears the parent's queue.

package/docs/qa/use-cases/UC-020-extraction-escalation.md

@@ -1,6 +1,6 @@
 # UC-020: Extraction nudge escalation and acknowledgment
 
-_Automatable: missedNudges counter + escalation tiers + extraction_done drain
+_Automatable: missedNudges counter + escalation tiers + extraction_done accept
 are testable with the mock client and a synthetic tool call sequence._
 
 **Preconditions**
@@ -27,10 +27,12 @@ are testable with the mock client and a synthetic tool call sequence._
   persists until a memory is written or `extraction_done` is called. The nudge
   repeats each turn with escalated tone (and the payload grows if new tool
   activity adds entries between nudges).
-- Step 6: `thatch_extraction_done` drains the buffer and resets the
-  `missedNudges` counter. The tool returns `"[acknowledged] extraction buffer
-  drained"`.
-- Step 7: no extraction nudge appears (buffer is empty). If the user prompt
+- Step 6: `thatch_extraction_done` in the parent accepts the buffer (moves it
+  to a holding area) and resets the `missedNudges` counter. The tool returns
+  `"[acknowledged]"`. Held entries drop when the extractor completes (child
+  memory write, child `extraction_done`, or child idle); if the child errors
+  or is deleted first, the entries requeue and the nudge replays.
+- Step 7: no extraction nudge appears (buffer is accepted). If the user prompt
   semantically matches existing memories, a recall nudge may appear instead.
 - Alternative drain path: if a child sub-agent (dispatched via the `task`
   tool) writes a memory via `thatch_memory_remember`, the parent's buffer is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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/extraction.ts

@@ -91,6 +91,7 @@ export function buildExtractionPayload(
  */
 export class ExtractionPipeline {
   #buffers = new Map<string, ToolInteraction[]>();
+  #accepted = new Map<string, ToolInteraction[]>();
   #maxBuffer = 20;
 
   /** Record a tool execution for later extraction. */
@@ -110,6 +111,46 @@ export class ExtractionPipeline {
     this.#buffers.delete(sessionID);
   }
 
+  /**
+   * Accept the session's buffer: move it to a holding area so the nudge
+   * stops replaying while a dispatched extractor works. AMQP-style accept —
+   * the entries are not dropped until a completion signal arrives (the
+   * extractor writes a memory, calls extraction_done, or goes idle). If the
+   * extractor dies first, requeueAccepted puts them back.
+   */
+  accept(sessionID: string): void {
+    const buf = this.#buffers.get(sessionID) ?? [];
+    if (buf.length === 0) return;
+    this.#buffers.delete(sessionID);
+    const existing = this.#accepted.get(sessionID) ?? [];
+    this.#accepted.set(sessionID, [...existing, ...buf]);
+  }
+
+  /** Drop accepted entries: the extractor finished (save or no-save). */
+  completeAccepted(sessionID: string): void {
+    this.#accepted.delete(sessionID);
+  }
+
+  /**
+   * Move accepted entries back to pending: the extractor errored or its
+   * session was deleted before completing, so the facts were never
+   * processed. Prepended so they replay in original order. Not capped at
+   * maxBuffer — a silent drop here would defeat the point of requeueing;
+   * the next push trims back to the cap.
+   */
+  requeueAccepted(sessionID: string): void {
+    const accepted = this.#accepted.get(sessionID);
+    if (!accepted || accepted.length === 0) return;
+    this.#accepted.delete(sessionID);
+    const buf = this.#buffers.get(sessionID) ?? [];
+    this.#buffers.set(sessionID, [...accepted, ...buf]);
+  }
+
+  /** Returns the session's accepted (held) interactions. Test/introspection. */
+  peekAccepted(sessionID: string): ToolInteraction[] {
+    return this.#accepted.get(sessionID) ?? [];
+  }
+
   /**
    * Remove entries that were in the snapshot (by reference identity), keeping
    * any that arrived after the snapshot was taken. Used by the child-parent

package/src/index.ts

@@ -129,27 +129,34 @@ export const server: Plugin = async ({ client, worktree }) => {
     //    agent writes a memory, so ignored nudges accumulate and the payload
     //    grows with each missed cycle.
     //
-    //    A memory_remember call in a child session (sub-agent) also drains
-    //    the parent's buffer — but only the entries that existed at dispatch
-    //    time (the snapshot). Entries from interleaved turns survive so their
-    //    facts aren't silently dropped. Without this, dispatching the
-    //    fact-extractor as a background task writes memories in the child but
-    //    never clears the parent's queue — the nudge replays every turn.
+    //    Buffer lifecycle is AMQP-style accept/complete, so a failed
+    //    extractor does not silently drop unprocessed interactions:
+    //    - thatch_extraction_done in the parent ACCEPTS the buffer: it moves
+    //      to a holding area and the nudge quiets, but entries are not
+    //      dropped yet.
+    //    - COMPLETE drops the held entries. Signals: a memory_remember or
+    //      extraction_done call in a child session of that parent (the
+    //      extractor confirming it processed them), or the child going idle
+    //      (a no-save run that never acks still counts as processed).
+    //    - REQUEUE returns the held entries to pending. Signals: the child
+    //      session errors or is deleted before completing.
     //
-    //    thatch_extraction_done is an explicit acknowledgment tool the model
-    //    calls in the parent session after dispatching. Covers the case where
-    //    the sub-agent errors out or the host doesn't expose parent-child
-    //    session relationships.
+    //    A memory_remember call in a child session (sub-agent) also drains
+    //    the parent's pending buffer — but only the entries that existed at
+    //    dispatch time (the snapshot). Entries from interleaved turns survive
+    //    so their facts aren't silently dropped.
     "tool.execute.after": async (input, output) => {
       if (input.tool === "thatch_memory_remember") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
-        // If this is a child session, drain only the parent's snapshot entries
-        // (those present at dispatch time). Interleaved-turn entries survive.
-        // If no snapshot was recorded (e.g. session.created event never
-        // arrived), fall back to draining the entire parent buffer.
+        // If this is a child session, complete the parent's accepted entries
+        // (the extractor confirmed it is alive and saving) and drain the
+        // parent's snapshot entries from the pending buffer. If no snapshot
+        // was recorded (e.g. session.created event never arrived), fall back
+        // to draining the entire parent buffer.
         const parentID = childToParent.get(input.sessionID);
         if (parentID) {
+          extraction.completeAccepted(parentID);
           const snapshot = parentSnapshots.get(input.sessionID);
           if (snapshot) {
             extraction.consumeSnapshot(parentID, snapshot);
@@ -161,11 +168,21 @@ export const server: Plugin = async ({ client, worktree }) => {
         }
         return;
       }
-      // Explicit acknowledgment tool drains the buffer without requiring a
-      // memory write. The model calls this after dispatching the
-      // fact-extractor to a sub-agent.
+      // thatch_extraction_done has two roles depending on the session:
+      // - parent, after dispatching the fact-extractor: ACCEPT the buffer
+      //   (quiet the nudge, hold the entries for completion).
+      // - child extractor, at the end of its run: COMPLETE the parent's
+      //   accepted entries, including no-save runs that write no memory,
+      //   and drop the child's own buffer (its work is done).
       if (input.tool === "thatch_extraction_done") {
-        extraction.consume(input.sessionID);
+        const parentID = childToParent.get(input.sessionID);
+        if (parentID) {
+          extraction.completeAccepted(parentID);
+          missedNudges.delete(parentID);
+          extraction.consume(input.sessionID);
+        } else {
+          extraction.accept(input.sessionID);
+        }
         missedNudges.delete(input.sessionID);
         return;
       }
@@ -290,7 +307,13 @@ export const server: Plugin = async ({ client, worktree }) => {
     // snapshots the parent's current buffer — so the child's later
     // memory_remember drains only those snapshot entries, not the parent's
     // entire buffer (which may have grown from interleaved turns).
-    // session.deleted cleans both maps to avoid unbounded growth.
+    //
+    // The accepted-buffer lifecycle completes or requeues on child lifecycle
+    // events: idle means the extractor finished (a no-save run writes no
+    // memory but still processed the payload); error or deletion before
+    // completion means the facts were never extracted, so the entries go
+    // back to pending. session.deleted also cleans both maps to avoid
+    // unbounded growth.
     event: async ({ event }) => {
       if (event.type === "session.created") {
         const info = event.properties.info;
@@ -299,9 +322,30 @@ export const server: Plugin = async ({ client, worktree }) => {
           parentSnapshots.set(info.id, [...extraction.peek(info.parentID)]);
         }
       }
+      if (event.type === "session.error") {
+        const childID = event.properties.sessionID;
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID) extraction.requeueAccepted(parentID);
+        return;
+      }
+      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+        const childID = event.properties.sessionID;
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID) {
+          extraction.completeAccepted(parentID);
+          missedNudges.delete(parentID);
+        }
+        return;
+      }
       if (event.type === "session.deleted") {
-        childToParent.delete(event.properties.info.id);
-        parentSnapshots.delete(event.properties.info.id);
+        const id = event.properties.info.id;
+        // A child deleted before completing never processed its payload.
+        const parentID = childToParent.get(id);
+        if (parentID) extraction.requeueAccepted(parentID);
+        childToParent.delete(id);
+        parentSnapshots.delete(id);
+        // A deleted parent takes its accepted entries with it.
+        extraction.completeAccepted(id);
         return;
       }
 

package/src/prompts.ts

@@ -426,7 +426,9 @@ export function extractionNudge(
   return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
     `${acknowledge} ` +
-    `Then answer the user. ` +
+    `This is a system nudge, not user input. After dispatching and acknowledging, ` +
+    `stop: do not advance pending work on this nudge's account. If you are ` +
+    `waiting for the user to respond, continue waiting. ` +
     `Use ${toolName} to save durable facts from this payload:\n${payload}`;
 }
 

package/src/tool-defs.ts

@@ -352,29 +352,35 @@ const markCheckedDef: ToolDef = {
 };
 
 /**
- * Acknowledge that the extraction nudge has been handled. Drains the
- * extraction buffer so the nudge does not replay on the next turn.
+ * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
  *
- * The actual draining happens in the host's post-tool hook
+ * Called in a PARENT session after dispatching the fact-extractor, it accepts
+ * the buffer: entries move to a holding area and the nudge quiets, but they
+ * are not dropped until the extractor completes. Called in a CHILD extractor
+ * at the end of its run, it completes the parent's accepted entries —
+ * including no-save runs that write no memory. If the child errors or is
+ * deleted before either signal, the host requeues the entries so the facts
+ * are not lost.
+ *
+ * The actual state changes happen in the host's post-tool hook
  * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) —
  * this tool's execute function is a no-op confirmation. The tool exists so
- * the model can call it in the parent session after dispatching the
- * fact-extractor to a sub-agent, giving the hook a recognizable tool name
- * to key on. Without it, the buffer only drains when a memory_remember
- * call lands in the same session (or a tracked child session), which fails
- * if the sub-agent errors out or the host doesn't expose parent-child
- * session relationships.
+ * the model has a recognizable tool name to key on. In the MCP path the
+ * file-backed queue is consumed on this call (or on any memory_remember),
+ * which is durable across interruption because the queue persists on disk
+ * until then.
  */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
-    "Acknowledge that the extraction nudge has been dispatched to a sub-agent. " +
-    "Drains the extraction buffer so the nudge does not replay. " +
-    "Call this in the parent session after dispatching a background task " +
-    "to run the thatch-fact-extractor skill.",
+    "Acknowledge extraction-buffer work. In a parent session, call after " +
+    "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
+    "(quiets the nudge) while keeping entries until the extractor completes. " +
+    "In the fact-extractor sub-agent, call at the end of the run to mark the " +
+    "entries complete, even when nothing was worth saving.",
   args: {},
   async execute() {
-    return "[acknowledged] extraction buffer drained";
+    return "[acknowledged]";
   },
 };