@jeffober/thatch 0.1.48 → 0.2.1

package/src/commands.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   defragCore,
@@ -161,12 +161,26 @@ export interface CommandDef {
   content: string;
 }
 
+/**
+ * The wrap-up command's prompt body, for hosts that register commands in
+ * code (opencode v2 CommandEditor): the execute hook arms the greenlight
+ * check and delivers this same text as the session prompt.
+ */
+export function wrapUpCommandContent(kind: "compact" | "exit"): string {
+  return kind === "compact" ? COMPACT_TEMPLATE : EXIT_TEMPLATE;
+}
+
+/** The action commands only - no wrap-ups (used where wrap-ups register in code). */
+export function opencodeActionCommandDefs(): CommandDef[] {
+  return actionDefs(opencodeToolName).map((a) => ({ name: a.name, content: renderActionCommand(a) }));
+}
+
 /** The opencode command set: wrap-ups plus every action, as full file contents. */
 export function opencodeCommandDefs(): CommandDef[] {
   return [
     { name: "compact", content: COMPACT_TEMPLATE },
     { name: "exit", content: EXIT_TEMPLATE },
-    ...actionDefs(opencodeToolName).map((a) => ({ name: a.name, content: renderActionCommand(a) })),
+    ...opencodeActionCommandDefs(),
   ];
 }
 
@@ -205,9 +219,34 @@ function syncCommandFiles(dir: string, defs: CommandDef[]): string[] {
   return written;
 }
 
-/** Sync opencode's commands into <configHome>/opencode/command/thatch/. */
-export function installOpencodeCommands(configHome: string): string[] {
-  return syncCommandFiles(join(configHome, "opencode", "command", "thatch"), opencodeCommandDefs());
+/**
+ * Sync opencode's commands into <configHome>/opencode/command/thatch/.
+ * defs overrides the set (hosts whose plugin API registers wrap-up commands
+ * in code pass the action-only set - a registered command and a file with
+ * the same name would collide).
+ */
+export function installOpencodeCommands(configHome: string, defs: CommandDef[] = opencodeCommandDefs()): string[] {
+  return syncCommandFiles(join(configHome, "opencode", "command", "thatch"), defs);
+}
+
+/**
+ * Removes wrap-up command files left in the opencode command dir. Hosts
+ * that register wrap-up commands in code (v2) pass the action-only set to
+ * installOpencodeCommands, but files written by earlier v1 runs persist -
+ * syncCommandFiles never removes - and a stale file collides with the
+ * registered command (both versions share the config dir). Call this
+ * before installing on such hosts. Idempotent: missing files are fine.
+ */
+export function removeWrapUpCommandFiles(configHome: string): void {
+  const dir = join(configHome, "opencode", "command", "thatch");
+  for (const kind of ["compact", "exit"] as const) {
+    try {
+      unlinkSync(join(dir, `${kind}.md`));
+    } catch {
+      // ENOENT is the expected steady state; anything else is equally
+      // harmless for a best-effort cleanup.
+    }
+  }
 }
 
 /** Sync Claude Code's commands into <claudeDir>/commands/thatch/ (claudeDir is ~/.claude or <project>/.claude). */

package/src/config.ts

@@ -21,17 +21,30 @@ export const chatPrefsSchema = z.strictObject({
   autoRegister: z.boolean().optional(),
 });
 
+/** Channel preferences for one automatic alert event (pause / done / error). */
+export const alertEventPrefsSchema = z.strictObject({
+  mode: z.enum(["both", "banner", "voice", "none"]).optional(),
+});
+
+export const alertsPrefsSchema = z.strictObject({
+  pause: alertEventPrefsSchema.optional(),
+  done: alertEventPrefsSchema.optional(),
+  error: alertEventPrefsSchema.optional(),
+});
+
 export const configSchema = z.strictObject({
   notifications: notificationPrefsSchema.optional(),
   chat: chatPrefsSchema.optional(),
+  alerts: alertsPrefsSchema.optional(),
 });
 
 export type NotificationPrefs = z.infer<typeof notificationPrefsSchema>;
 export type ChatPrefs = z.infer<typeof chatPrefsSchema>;
+export type AlertsPrefs = z.infer<typeof alertsPrefsSchema>;
 export type Config = z.infer<typeof configSchema>;
 
 /** Sections in presentation order. config_get / config_set iterate this. */
-export const CONFIG_SECTIONS = ["notifications", "chat"] as const;
+export const CONFIG_SECTIONS = ["notifications", "chat", "alerts"] as const;
 export type ConfigSection = (typeof CONFIG_SECTIONS)[number];
 
 /**
@@ -102,6 +115,11 @@ export function mergeChatPrefs(current: ChatPrefs | undefined, patch: ChatPrefs)
   return { ...current, ...patch };
 }
 
+/** Field-level merge for one section: omitted fields keep their values. */
+export function mergeAlertsPrefs(current: AlertsPrefs | undefined, patch: AlertsPrefs): AlertsPrefs {
+  return { ...current, ...patch };
+}
+
 /**
  * Whether cross-session chat is on. Unset means on - chat is the default,
  * and the toggle exists for users who want the feature entirely dark: every
@@ -134,3 +152,16 @@ export function notificationDefaults(): { mode: "both" | "banner" | "voice" | "n
   }
   return { mode: "both" };
 }
+
+/** The automatic alert events, in the order config_get renders them. */
+export type AlertEventKind = "pause" | "done" | "error";
+export const ALERT_EVENT_KINDS: AlertEventKind[] = ["pause", "done", "error"];
+
+/**
+ * Channel for one automatic alert event (pause / done / error). Unset means
+ * banner: the alerts exist to reach a user who walked away, so voice is
+ * opt-in per event rather than bundled with the notify_user default.
+ */
+export function alertMode(config: Config, kind: AlertEventKind): "both" | "banner" | "voice" | "none" {
+  return config.alerts?.[kind]?.mode ?? "banner";
+}

package/src/db.ts

@@ -55,12 +55,67 @@ export interface DedupCandidate {
  * stored as BLOBs. Similarity search is brute-force cosine in JS.
  */
 export class ThatchDB {
-  #db: Database;
-  #predictions: PredictionEngine;
-  #behaviors: BehaviorEngine;
-  #chat: ChatStore;
+  #path: string;
+  #handle: Database | null = null;
+  #predictionsStore!: PredictionEngine;
+  #behaviorsStore!: BehaviorEngine;
+  #chatStore!: ChatStore;
 
   constructor(path: string) {
+    this.#path = path;
+    this.#open();
+  }
+
+  /**
+   * Connection accessor. Every read goes through here, so a handle closed by
+   * dispose() (a v2 plugin reload tears down the old activation while tool
+   * calls may still be in flight) transparently reopens on the next touch
+   * instead of surfacing bun:sqlite's "Cannot use a closed database". WAL
+   * journaling plus busy_timeout make the extra connection safe - the chat
+   * subsystem already runs as several concurrent connections by design.
+   *
+   * OWNERSHIP RULE: reopen serves READS and in-flight callers only. After a
+   * reload, the RELOADED instance owns the runtime_state journal rows, so
+   * post-dispose journal writes must no-op - they are guarded by the
+   * disposed flag at their call sites in src/runtime.ts, checked BEFORE any
+   * db access reaches this accessor. Do not move that guard in here: this
+   * method cannot distinguish a legitimate in-flight caller from a stale
+   * writer.
+   *
+   * Reopen caveat: a `:memory:` database has no file behind it, so a
+   * close-then-use cycle on one yields a brand-new EMPTY database. No
+   * production path does that (:memory: is test-only and tests never use the
+   * instance after close), but keep it that way - use a tmp-file db if a
+   * test needs close-then-use.
+   */
+  get #db(): Database {
+    if (this.#handle === null) this.#open();
+    return this.#handle!;
+  }
+
+  // The engine facades get the same treatment as #db: every accessor
+  // ensures an open connection first, so delegation routes through the
+  // facade REBUILT by the reopen rather than the stale one. Without this,
+  // a post-close chat call would reach the old ChatStore's captured handle
+  // and throw "Cannot use a closed database" even though ThatchDB itself
+  // reopened.
+  get #predictions(): PredictionEngine {
+    if (this.#handle === null) this.#open();
+    return this.#predictionsStore;
+  }
+
+  get #behaviors(): BehaviorEngine {
+    if (this.#handle === null) this.#open();
+    return this.#behaviorsStore;
+  }
+
+  get #chat(): ChatStore {
+    if (this.#handle === null) this.#open();
+    return this.#chatStore;
+  }
+
+  #open(): void {
+    const path = this.#path;
     // bun:sqlite creates the file but not its parent directory. On a fresh
     // machine the default path (~/.config/thatch/thatch.db) has no dir yet, so
     // create it here - otherwise every command fails with SQLITE_CANTOPEN.
@@ -68,18 +123,23 @@ export class ThatchDB {
     if (path !== ":memory:" && !path.startsWith("file:")) {
       mkdirSync(dirname(path), { recursive: true });
     }
-    this.#db = new Database(path, { create: true });
-    this.#db.run("PRAGMA journal_mode = WAL");
-    this.#db.run("PRAGMA busy_timeout = 5000");
+    const db = new Database(path, { create: true });
+    db.run("PRAGMA journal_mode = WAL");
+    db.run("PRAGMA busy_timeout = 5000");
     // Enforce FK constraints per connection. The prediction tables use
     // ON DELETE CASCADE for edges and provenance; enabling this pragma
     // ensures those cascades fire. Also enforces the entries table's
     // existing FK to stores(name), which was declarative but unenforced
     // before this branch.
-    this.#db.run("PRAGMA foreign_keys = ON");
-    this.#predictions = new PredictionEngine(this.#db);
-    this.#behaviors = new BehaviorEngine(this.#db);
-    this.#chat = new ChatStore(this.#db);
+    db.run("PRAGMA foreign_keys = ON");
+    this.#handle = db;
+    // The engine facades hold the Database handle they were constructed
+    // with, so a reopened connection rebuilds them. They are stateless
+    // views over SQLite - all durable state lives in the tables - so
+    // reconstruction is lossless.
+    this.#predictionsStore = new PredictionEngine(db);
+    this.#behaviorsStore = new BehaviorEngine(db);
+    this.#chatStore = new ChatStore(db);
     this.#initSchema();
   }
 
@@ -297,6 +357,18 @@ export class ThatchDB {
       )
     `);
 
+    // Reaped auto-registered rows leave their name-to-session binding here,
+    // so the SAME session can reclaim its name when it re-registers (a
+    // crash-and-resume must not churn the identity). Names are still never
+    // reissued to a DIFFERENT session: a claim only ever resolves for the
+    // session id it was recorded with.
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS chat_name_claims (
+        name       TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL
+      )
+    `);
+
     // Explicit leaves (chat_unregister). Suppresses auto-registration so
     // the next idle event cannot silently re-register the session; cleared
     // when the session explicitly rejoins via chat_register. Survives the
@@ -322,6 +394,24 @@ export class ThatchDB {
       )
     `);
 
+    // Volatile plugin-runtime state, persisted so a v2 plugin reload (the
+    // host rebuilds the location graph and re-runs setup) or a process
+    // restart can rehydrate instead of silently dropping it. The writer's
+    // pid is the discriminator: a row written by the CURRENT process means
+    // "reload - keep and rehydrate"; a row from another (dead) pid means
+    // "restart - prune unless the session was resumed".
+    this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS runtime_state (
+        kind       TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        directory  TEXT NOT NULL DEFAULT '',
+        value      TEXT NOT NULL,
+        pid        INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        PRIMARY KEY (kind, session_id)
+      )
+    `);
+
     this.#migrateColumns();
     this.#migrateChatNameCollation();
     this.#migrateChatTopic();
@@ -330,6 +420,14 @@ export class ThatchDB {
     this.#migrateChatAuto();
     this.#migrateChatWorktree();
     this.#migrateChatHostPid();
+    this.#migrateRuntimeStateDirectory();
+  }
+
+  #migrateRuntimeStateDirectory(): void {
+    const cols = (this.#db.query("PRAGMA table_info(runtime_state)").all() as any[]).map((r) => r.name);
+    if (cols.length > 0 && !cols.includes("directory")) {
+      this.#db.run("ALTER TABLE runtime_state ADD COLUMN directory TEXT NOT NULL DEFAULT ''");
+    }
   }
 
   // chat_sessions tables created before the auto column lack it; the ALTER
@@ -961,6 +1059,48 @@ export class ThatchDB {
     return this.#chat.unregister(sessionID);
   }
 
+  /**
+   * Persist one runtime-state record (upsert by kind+session). `directory`
+   * is the writing instance's location: one v2 serve hosts one plugin
+   * instance per directory sharing this db, and rehydration must be
+   * instance-scoped, not process-scoped.
+   */
+  runtimeStatePut(kind: string, sessionId: string, value: unknown, directory: string, pid: number = process.pid) {
+    this.#db
+      .query(
+        `INSERT INTO runtime_state (kind, session_id, directory, value, pid) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (kind, session_id) DO UPDATE SET directory = excluded.directory, value = excluded.value, pid = excluded.pid, created_at = excluded.created_at`,
+      )
+      .run(kind, sessionId ?? "", directory ?? "", JSON.stringify(value), pid);
+  }
+
+  /** Drop one runtime-state record. */
+  runtimeStateDelete(kind: string, sessionId: string) {
+    this.#db.query(`DELETE FROM runtime_state WHERE kind = ? AND session_id = ?`).run(kind, sessionId);
+  }
+
+  /** Every runtime-state record, oldest first (rehydration source). */
+  runtimeStateAll(): { kind: string; sessionID: string; directory: string; value: unknown; pid: number }[] {
+    return this.#db
+      .query(`SELECT kind, session_id, directory, value, pid FROM runtime_state ORDER BY created_at, session_id`)
+      .all()
+      .map((row: any) => {
+        let value: unknown;
+        try {
+          value = JSON.parse(row.value);
+        } catch {
+          value = null;
+        }
+        return {
+          kind: row.kind as string,
+          sessionID: row.session_id as string,
+          directory: (row.directory ?? "") as string,
+          value,
+          pid: row.pid as number,
+        };
+      });
+  }
+
   listChatSessions() {
     return this.#chat.list();
   }
@@ -1089,7 +1229,12 @@ export class ThatchDB {
   }
 
   close(): void {
-    this.#db.close();
+    // Drops the current handle only. A later use reopens (see the #db
+    // accessor) - the MCP server and CLI call this on process shutdown,
+    // where nothing follows; the opencode plugin's dispose calls it on
+    // reload, where straggler in-flight tool calls must survive.
+    this.#handle?.close();
+    this.#handle = null;
   }
 }
 

package/src/embeddings.ts

@@ -159,6 +159,49 @@ export interface BgeEmbeddingModelOptions {
   idleTtlMs?: number;
 }
 
+/**
+ * Process-wide model pool, keyed by db path. A v2 serve hosts one plugin
+ * instance per location and each would otherwise keep its own ONNX model
+ * resident; the pool refcounts so N instances share one model and it is
+ * disposed only when the last holder releases (the model's ONNX sessions
+ * must be explicitly closed before process exit - Bun's NAPI finalizers
+ * panic otherwise, see BgeEmbeddingModel.dispose).
+ */
+export class SharedModelPool {
+  #entries = new Map<string, { model: BgeEmbeddingModel; refs: number }>();
+
+  acquire(dbPath: string, modelName: string): BgeEmbeddingModel {
+    const entry = this.#entries.get(dbPath);
+    if (entry) {
+      entry.refs += 1;
+      return entry.model;
+    }
+    const created = { model: new BgeEmbeddingModel(modelName), refs: 1 };
+    this.#entries.set(dbPath, created);
+    return created.model;
+  }
+
+  /**
+   * Release one reference. Resolves when the model's ONNX sessions are
+   * released (at zero refs) - the caller MUST await it before its process
+   * can exit, or Bun's NAPI finalizers panic on teardown.
+   */
+  async release(dbPath: string): Promise<void> {
+    const entry = this.#entries.get(dbPath);
+    if (!entry) return;
+    entry.refs -= 1;
+    if (entry.refs <= 0) {
+      this.#entries.delete(dbPath);
+      await entry.model.dispose();
+    }
+  }
+
+  /** Test/introspection: number of live (held) models. */
+  get size(): number {
+    return this.#entries.size;
+  }
+}
+
 /**
  * Lazy-loads an embedding model via @huggingface/transformers.
  * Model files (~34 MB for the default) are downloaded once and cached by HF Hub.

package/src/extraction.ts

@@ -59,6 +59,58 @@ function truncate(text: string, maxLen: number): string {
   return text.slice(0, maxLen) + "...";
 }
 
+/** The scan result for a Code Mode `execute` call - see unwrapExecuteThatchCalls. */
+export interface ExecuteUnwrap {
+  /** Distinct thatch_* tool names the code invokes, in first-appearance order. */
+  tools: string[];
+  /** Whether the code passes `overwrite: true` to a memory_remember call. */
+  overwrite: boolean;
+  /**
+   * The session_id a wrapped extraction_done call passes, when present -
+   * the sub-agent naming the parent whose accepted entries it completed.
+   */
+  sessionID?: string;
+}
+
+/**
+ * Meta tools: bookkeeping and dispatch, never real work. The extraction
+ * buffer excludes them because buffering the pipeline's own traffic feeds
+ * the nudge with its own exhaust (the dispatch/ack loops, September 2026);
+ * the alert classifier excludes them because a round made of only these
+ * did nothing the user asked for. "task" is v1's dispatch tool, "subagent"
+ * v2's, "agent" the MCP-path spelling - match all three, never one name.
+ */
+export function isMetaToolName(tool: string): boolean {
+  const t = tool.toLowerCase();
+  return t.startsWith("thatch_") || t === "skill" || t === "task" || t === "agent" || t === "subagent";
+}
+
+/**
+ * Detect thatch_* tool invocations wrapped inside a Code Mode `execute`
+ * call's code (`tools.thatch_extraction_done({session_id: "..."})` - dot
+ * and bracket forms both count; the bracket form
+ * `tools["thatch_extraction_done"]` used to slip past the unwrap and
+ * re-open the dispatch/ack loop). The extraction buffer matches on TOOL
+ * NAME, so without unwrapping, the pipeline's own ack/drain traffic
+ * re-enters the buffer as extractable interactions: each extraction run
+ * queues the next one and the nudge never runs out of self-generated
+ * material (observed as an infinite dispatch/ack loop, September 2026).
+ * Returns an empty tool list when the args are not execute-shaped or the
+ * code invokes no thatch tools - such calls buffer as normal, because they
+ * did real non-thatch work.
+ */
+export function unwrapExecuteThatchCalls(args: unknown): ExecuteUnwrap {
+  const code = (args as Record<string, unknown> | undefined)?.code;
+  if (typeof code !== "string" || !code.includes("thatch_")) return { tools: [], overwrite: false };
+  const tools: string[] = [];
+  for (const match of code.matchAll(/tools\.thatch_([a-z_]+)|tools\[\s*["']thatch_([a-z_]+)["']\s*\]/g)) {
+    const name = `thatch_${match[1] ?? match[2]}`;
+    if (!tools.includes(name)) tools.push(name);
+  }
+  const doneCall = code.match(/thatch_extraction_done["']?\]?\s*\(\s*\{[^}]*?\bsession_id:\s*["']([^"']+)["']/);
+  return { tools, overwrite: /\boverwrite\s*:\s*true\b/.test(code), sessionID: doneCall?.[1] };
+}
+
 /**
  * Serialize a list of tool interactions into the JSON payload the
  * thatch-fact-extractor skill expects. Shared by the opencode plugin path
@@ -84,6 +136,27 @@ export function buildExtractionPayload(
   });
 }
 
+/**
+ * Persistence hook: called after every buffer/accepted mutation with the
+ * session's current state (undefined = the list is gone - drop the record).
+ * The runtime wires this to the runtime_state journal so a v2 plugin reload
+ * or process restart can rehydrate the buffer instead of losing it.
+ */
+export type ExtractionJournal = (
+  kind: "buffer" | "accepted",
+  sessionID: string,
+  value: ToolInteraction[] | undefined,
+) => void;
+
+/**
+ * How long accepted entries wait for a completion signal before
+ * requeueStaleAccepted gives up waiting and requeues them. Generous - the
+ * extractor sub-agent can legitimately run for many minutes. The point is
+ * bounding the linger when the completion signal never comes: a crashed
+ * extractor, or a v2 dispatch whose completion ack never names the parent.
+ */
+export const ACCEPTED_STALE_MS = 15 * 60_000;
+
 /**
  * Per-session in-memory ring buffer used by the opencode plugin path. Claude
  * Code's MCP server has no equivalent plugin lifecycle, so its CLI subcommands
@@ -92,13 +165,36 @@ export function buildExtractionPayload(
 export class ExtractionPipeline {
   #buffers = new Map<string, ToolInteraction[]>();
   #accepted = new Map<string, ToolInteraction[]>();
+  /** When the session's buffer was accepted - drives requeueStaleAccepted. */
+  #acceptedAt = new Map<string, number>();
   #maxBuffer = 20;
+  #journal?: ExtractionJournal;
+
+  constructor(journal?: ExtractionJournal) {
+    this.#journal = journal;
+  }
+
+  /** Restore persisted state (same-process reload rehydration). */
+  hydrate(buffers: ToolInteraction[], accepted: ToolInteraction[]): void {
+    for (const ix of buffers) {
+      const buf = this.#buffers.get(ix.sessionID) ?? [];
+      buf.push(ix);
+      this.#buffers.set(ix.sessionID, buf);
+    }
+    for (const ix of accepted) {
+      const buf = this.#accepted.get(ix.sessionID) ?? [];
+      buf.push(ix);
+      this.#accepted.set(ix.sessionID, buf);
+      if (!this.#acceptedAt.has(ix.sessionID)) this.#acceptedAt.set(ix.sessionID, Date.now());
+    }
+  }
 
   /** Record a tool execution for later extraction. */
   push(interaction: ToolInteraction): void {
     const buf = this.#buffers.get(interaction.sessionID) ?? [];
     buf.push(interaction);
     this.#buffers.set(interaction.sessionID, buf.slice(-this.#maxBuffer));
+    this.#journal?.("buffer", interaction.sessionID, this.#buffers.get(interaction.sessionID));
   }
 
   /** Returns the session's buffered interactions without clearing them. */
@@ -109,6 +205,7 @@ export class ExtractionPipeline {
   /** Clears the session's buffer. Called when the agent writes a memory. */
   consume(sessionID: string): void {
     this.#buffers.delete(sessionID);
+    this.#journal?.("buffer", sessionID, undefined);
   }
 
   /**
@@ -124,11 +221,103 @@ export class ExtractionPipeline {
     this.#buffers.delete(sessionID);
     const existing = this.#accepted.get(sessionID) ?? [];
     this.#accepted.set(sessionID, [...existing, ...buf]);
+    this.#acceptedAt.set(sessionID, Date.now());
+    this.#journal?.("buffer", sessionID, this.#buffers.get(sessionID));
+    this.#journal?.("accepted", sessionID, this.#accepted.get(sessionID));
   }
 
   /** Drop accepted entries: the extractor finished (save or no-save). */
   completeAccepted(sessionID: string): void {
     this.#accepted.delete(sessionID);
+    this.#acceptedAt.delete(sessionID);
+    this.#journal?.("accepted", sessionID, undefined);
+  }
+
+  #claims = new Map<string, { target: string; entries: ToolInteraction[] }>();
+
+  /**
+   * Claim the session's pending + previously-accepted entries for a fetcher
+   * (the extractor sub-agent fetching its payload). The entries stay in the
+   * accepted holding area; the claim records WHICH fetcher they were
+   * delivered to, so that fetcher's completion signal consumes only its own
+   * delivery. Without this, any child's completion dropped the whole
+   * accepted set - a sibling sub-agent going idle at the wrong moment
+   * silently discarded another extractor's in-flight payload (the
+   * accept-then-racing-completion loss, observed September 2026).
+   *
+   * Entries are claimed by reference identity: later accepts append new
+   * arrays, so a stale claim never reaches entries claimed after it.
+   */
+  claim(sessionID: string, fetcherID: string): ToolInteraction[] {
+    this.accept(sessionID);
+    const accepted = this.#accepted.get(sessionID) ?? [];
+    this.#claims.set(fetcherID, { target: sessionID, entries: accepted });
+    return accepted;
+  }
+
+  /**
+   * Consume only the fetcher's claimed entries. Returns false when the
+   * fetcher holds no claim - a sibling that never fetched, or a fetch that
+   * never happened. Callers must NOT fall back to whole-set completion on
+   * the idle path: a fetcher that never fetched processed nothing, and
+   * dropping the set would lose another extractor's claimed payload.
+   */
+  completeClaimed(fetcherID: string): boolean {
+    const claim = this.#claims.get(fetcherID);
+    if (!claim) return false;
+    this.#claims.delete(fetcherID);
+    const accepted = this.#accepted.get(claim.target);
+    if (accepted) {
+      const claimed = new Set(claim.entries);
+      const rest = accepted.filter((ix) => !claimed.has(ix));
+      if (rest.length > 0) {
+        this.#accepted.set(claim.target, rest);
+        this.#journal?.("accepted", claim.target, rest);
+      } else {
+        this.#accepted.delete(claim.target);
+        this.#acceptedAt.delete(claim.target);
+        this.#journal?.("accepted", claim.target, undefined);
+      }
+    }
+    return true;
+  }
+
+  /** Forget a fetcher's claim (its session was deleted or cleaned up). */
+  dropClaim(fetcherID: string): void {
+    this.#claims.delete(fetcherID);
+  }
+
+  /**
+   * Requeue only the fetcher's claimed entries back to pending: its session
+   * errored, so the delivery was never processed. Returns false when the
+   * fetcher holds no claim - a task-kind child that never fetched processed
+   * nothing, and requeueing the whole accepted set here would yank another
+   * extractor's in-flight claim back to pending for duplicate extraction.
+   * Callers decide whether a claim-less error falls back to whole-set
+   * requeue (extraction children: yes - the error is a strong immediate
+   * death signal; task children: no).
+   */
+  requeueClaimed(fetcherID: string): boolean {
+    const claim = this.#claims.get(fetcherID);
+    if (!claim) return false;
+    this.#claims.delete(fetcherID);
+    const accepted = this.#accepted.get(claim.target);
+    if (accepted) {
+      const claimed = new Set(claim.entries);
+      const rest = accepted.filter((ix) => !claimed.has(ix));
+      if (rest.length > 0) {
+        this.#accepted.set(claim.target, rest);
+        this.#journal?.("accepted", claim.target, rest);
+      } else {
+        this.#accepted.delete(claim.target);
+        this.#acceptedAt.delete(claim.target);
+        this.#journal?.("accepted", claim.target, undefined);
+      }
+    }
+    const buf = this.#buffers.get(claim.target) ?? [];
+    this.#buffers.set(claim.target, [...claim.entries, ...buf]);
+    this.#journal?.("buffer", claim.target, this.#buffers.get(claim.target));
+    return true;
   }
 
   /**
@@ -142,8 +331,27 @@ export class ExtractionPipeline {
     const accepted = this.#accepted.get(sessionID);
     if (!accepted || accepted.length === 0) return;
     this.#accepted.delete(sessionID);
+    this.#acceptedAt.delete(sessionID);
     const buf = this.#buffers.get(sessionID) ?? [];
     this.#buffers.set(sessionID, [...accepted, ...buf]);
+    this.#journal?.("buffer", sessionID, this.#buffers.get(sessionID));
+    this.#journal?.("accepted", sessionID, undefined);
+  }
+
+  /**
+   * 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.
+   */
+  requeueStaleAccepted(maxAgeMs = ACCEPTED_STALE_MS): string[] {
+    const stale = [...this.#acceptedAt.entries()]
+      .filter(([, acceptedAt]) => Date.now() - acceptedAt > maxAgeMs)
+      .map(([sessionID]) => sessionID);
+    for (const sessionID of stale) this.requeueAccepted(sessionID);
+    return stale;
   }
 
   /** Returns the session's accepted (held) interactions. Test/introspection. */
@@ -166,8 +374,10 @@ export class ExtractionPipeline {
     const remaining = buf.filter((ix) => !old.has(ix));
     if (remaining.length === 0) {
       this.#buffers.delete(sessionID);
+      this.#journal?.("buffer", sessionID, undefined);
     } else {
       this.#buffers.set(sessionID, remaining);
+      this.#journal?.("buffer", sessionID, remaining);
     }
   }