@staix/agent-mem 0.19.0 → 0.20.0

package/src/hooks.ts

@@ -15,7 +15,7 @@ import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memor
 import { HOOK_EVENTS, HOOK_INPUT_BYTES, HOOK_CONTEXT_BYTES, HOOK_OUTPUT_BYTES, isHookTranscriptProgress, type HookTranscriptProgress } from "./hook-contract.ts";
 export { HOOK_EVENTS, HOOK_INPUT_BYTES, HOOK_CONTEXT_BYTES, HOOK_OUTPUT_BYTES, type HookEvent } from "./hook-contract.ts";
 // Leave 10ms of the external 150ms R2 budget for teardown and the metrics write.
-const HANDLER_MS = 140;
+export const HANDLER_MS = 140;
 // A timed-out child must be reaped and metrics flushed inside the unchanged handler/R2 budgets.
 // ponytail: reserve measured native teardown variance; an asynchronous hard-deadline transport
 // through storage/cleanup is the upgrade, not a longer external deadline.
@@ -68,14 +68,17 @@ async function before<T>(work: Promise<T>, deadline: number): Promise<T | undefi
 }
 const publicBefore = async (policy: MemoryPolicy, value: unknown, deadline: number) => await before(policy.screen(value), deadline) === true;
 
-async function boundedOutput(stream: ReadableStream<Uint8Array>, onRss?: (value: unknown) => void, onTranscript?: (value: unknown) => void): Promise<string | undefined> {
+async function boundedOutput(stream: ReadableStream<Uint8Array>, onRss?: (value: unknown) => void, onTranscript?: (value: unknown) => void, register?: (cancel: () => void) => void, onDrain?: (value: unknown) => void): Promise<string | undefined> {
   const reader = stream.getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
+  // #226: after a bounded reap the parent abandons this pipe; cancelling it leaves no pending read holding the event loop.
+  register?.(() => { reader.cancel().catch(() => {}); });
   let length = 0, pending = "", body = "";
   const line = (text: string) => {
     if (!text) return;
-    const value = JSON.parse(text) as { rss?: unknown; transcript?: unknown };
+    const value = JSON.parse(text) as { rss?: unknown; transcript?: unknown; drain?: unknown };
     if (onRss && Object.hasOwn(value, "rss")) onRss(value.rss);
     else if (onTranscript && Object.hasOwn(value, "transcript")) onTranscript(value.transcript);
+    else if (onDrain && Object.hasOwn(value, "drain")) onDrain(value.drain);
     else { if (body) throw new Error("worker output bound"); body = text; }
   };
   try {
@@ -106,73 +109,120 @@ async function parentProject(options: HookOptions, base: string, deadline: numbe
   return { cwd, scope, project, receipt, usage };
 }
 
+/** #226: after SIGKILL the parent waits at most this long for the owned worker's exit and output. A worker stuck in
+ * uninterruptible I/O (fsync) can outlive the hook; the kill is already sent, its pipe is cancelled and its handle unref'd,
+ * so nothing keeps this process alive and nothing stays resident. R1 judges it after a fixed 2 s post-exit window. */
+const REAP_BOUND_MS = 10;
+async function boundedWait<T>(work: Promise<T>): Promise<{ value?: T; late: boolean }> {
+  let timer: ReturnType<typeof setTimeout> | undefined, late = false;
+  const value = await Promise.race([work, new Promise<undefined>(resolve => { timer = setTimeout(() => { late = true; resolve(undefined); }, REAP_BOUND_MS); })]);
+  if (timer) clearTimeout(timer);
+  return late ? { late } : { value: value as T, late };
+}
+/** Owned children killed but still alive when the hook returned; recorded in the hook metric. */
+let abandonedChildren = 0;
+/** Transcript hooks whose worker was killed before its drain finished; their staged records stay durable and pending. */
+let drainSkipped = 0;
+/** #226 instrumentation: the last worker drain's start (ms after hook start) and committed record count. */
+let lastDrain: { startMs: number; drained: number } | undefined;
+/** Hook start on the performance clock, set by the entry points, so a worker can report times relative to it. */
+let hookStartedAt = performance.now();
+
 /** Only capture work uses a short-lived owned child; native handles remain in this CLI.
+ * #226 (ruling b): a transcript hook boots that one worker at hook start, in parallel with native metadata. The worker
+ * scans as soon as its first stdin line (scan options) arrives and drains after the second (the native receipt). At the
+ * deadline the parent kills it and waits at most REAP_BOUND_MS; a kill skips that call's drain (counted, never a drop).
  * Host callbacks cannot cross this boundary; a host needing them calls sessionStartBrief in-process instead. */
 async function hookWorker(options: HookOptions, base: string, deadline: number, pending: PendingHookCapture, event: string, transcript?: unknown): Promise<{ context: string; rssKB: number; rawRssKB: number; captured: boolean; valid: boolean; rssSources?: HookRssSources; transcript?: HookTranscriptProgress }> {
   const workDeadline = deadline - WORKER_CLEANUP_MS;
   if (options.policy?.host || workDeadline - performance.now() < 5) return { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false };
-  const metadata = await parentProject(options, base, workDeadline);
-  if (!metadata.receipt && transcript === undefined || workDeadline - performance.now() < 5) return { context: unavailable, ...metadata.usage, captured: false, valid: false, ...(transcript !== undefined ? { transcript: { stopReason: "deadline" as const } } : {}) };
-  const result = { context: unavailable, ...metadata.usage, captured: false, valid: false,
-    rssSources: combineRssSources(metadata.usage.rssSources), transcript: undefined as HookTranscriptProgress | undefined };
-  let owned: ReturnType<typeof Bun.spawn> | undefined, exited = false;
-  try {
-    const configuredBrief = loadAmemConfig(base, repoConfigRoot(options.cwd)).config.briefBytes;
-    const maxTokens = Math.min(HOOK_CONTEXT_BYTES, configuredBrief ?? HOOK_CONTEXT_BYTES, Math.max(1, options.maxTokens ?? HOOK_CONTEXT_BYTES));
-    // The worker reads the configuration itself (same base, same cwd), so it screens with exactly the policy the parent did.
-    const payload = JSON.stringify({ cwd: options.cwd, base, current: pending.name, event, identity: metadata.receipt, transcript, maxTokens, ownedGroup: true, deadlineAt: performance.timeOrigin + workDeadline,
-      policy: { denyPaths: options.policy?.denyPaths, piiPatterns: options.policy?.piiPatterns } });
+  const early = transcript !== undefined;
+  const policy = { denyPaths: options.policy?.denyPaths, piiPatterns: options.policy?.piiPatterns };
+  let owned: Bun.Subprocess<"pipe", "pipe", "ignore"> | undefined, exited = false, killed = false, cancelOutput: (() => void) | undefined;
+  let tracker: HookWorkerRss | undefined, output: Promise<string | undefined> | undefined, exit: Promise<number> | undefined;
+  const result = { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false, rssSources: emptyRssSources(), transcript: undefined as HookTranscriptProgress | undefined };
+  const drainProgress: { startMs?: number; drained?: number } = {};
+  const spawn = () => {
     const child = Bun.spawn([process.execPath, "--smol", fileURLToPath(new URL("./session-brief-worker.ts", import.meta.url))],
-      { cwd: options.cwd, env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AMEM_HOME: base }, detached: true, stdin: Buffer.from(payload), stdout: "pipe", stderr: "ignore" });
+      { cwd: options.cwd, env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AMEM_HOME: base }, detached: true, stdin: "pipe", stdout: "pipe", stderr: "ignore" });
     owned = child;
-    result.rssSources.unavailable++;
-    const exit = child.exited.then(code => { exited = true; return code; });
-    const tracker = new HookWorkerRss(child.pid);
-    const output = boundedOutput(child.stdout, value => tracker.frame(value), value => {
+    exit = child.exited.then(code => { exited = true; return code; });
+    tracker = new HookWorkerRss(child.pid);
+    output = boundedOutput(child.stdout, value => tracker!.frame(value), value => {
       if (!isHookTranscriptProgress(value)) throw new Error("worker transcript progress bound");
       if (value.offset !== undefined && result.transcript?.offset !== undefined && value.offset < result.transcript.offset) throw new Error("worker transcript progress regressed");
-      result.transcript = { ...result.transcript, ...value };
+      // A reported scan fault stays reported: a later worker deadline frame cannot turn it into accepted progress (#221).
+      result.transcript = { ...result.transcript, ...value, ...(result.transcript?.stopReason === "unavailable" ? { stopReason: "unavailable" as const } : {}) };
+    }, cancel => { cancelOutput = cancel; }, value => {
+      // #226 instrumentation: bounded numeric drain progress; anything else is ignored, never trusted.
+      const row = value as { startMs?: unknown; drained?: unknown } | null;
+      if (row && typeof row.startMs === "number" && Number.isFinite(row.startMs) && row.startMs >= 0 && row.startMs < 10_000) drainProgress.startMs = row.startMs;
+      if (row && Number.isSafeInteger(row.drained) && (row.drained as number) >= 0 && (row.drained as number) <= 1024) drainProgress.drained = row.drained as number;
     });
-    const stop = () => {
-      if (exited) return;
-      tracker.captureLive();
-      // The still-live leader is the detached process we just spawned, so its group is ours.
-      // The capture-only worker owns no native helper; those handles were reaped in this parent.
-      try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* Already exited. */ } }
-    };
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    try {
-      const answer = await Promise.race([
-        Promise.all([exit, output]),
-        new Promise<undefined>(resolve => { timer = setTimeout(() => { if (transcript !== undefined) result.transcript ??= { stopReason: "deadline" }; stop(); resolve(undefined); }, Math.max(1, workDeadline - performance.now())); }),
-      ]);
-      if (!answer || !answer[1]) return result;
-      const parsed = JSON.parse(answer[1]) as { context?: unknown; captured?: unknown; valid?: unknown; complete?: unknown; rssKB?: unknown; rssTelemetryValid?: unknown };
-      if (parsed.complete !== true) return result;
-      if (parsed.rssTelemetryValid !== true) tracker.invalidate();
-      if (typeof parsed.rssKB === "number" && Number.isSafeInteger(parsed.rssKB) && parsed.rssKB > 0) result.rssKB = parsed.rssKB;
-      if (typeof parsed.context === "string" && Buffer.byteLength(parsed.context) <= maxTokens) result.context = parsed.context;
-      result.captured = parsed.captured === true; result.valid = parsed.valid === true;
-      return result;
-    } catch { return result; }
-    finally {
-      if (timer) clearTimeout(timer);
-      stop();
-      await exit;
-      // Bun subprocess usage is bytes; process.resourceUsage below is KiB.
-      const workerRawKB = (child.resourceUsage()?.maxRSS ?? 0) / 1024;
-      result.rawRssKB = metadata.usage.rawRssKB + workerRawKB;
-      if (await output === undefined) tracker.invalidate();
-      const accounting = tracker.finish(workerRawKB);
-      result.rssKB = metadata.usage.rssKB + accounting.rssKB; result.rssSources = combineRssSources(metadata.usage.rssSources, accounting.rssSources);
+    return child;
+  };
+  const send = (line: object) => { try { owned!.stdin.write(JSON.stringify(line) + "\n"); owned!.stdin.flush(); } catch { /* A dead worker reports nothing. */ } };
+  const close = () => { try { owned?.stdin.end(); } catch { /* Already closed. */ } };
+  const stop = () => {
+    if (!owned || exited) return;
+    tracker!.captureLive();
+    killed = true;
+    // The still-live leader is the detached process we just spawned, so its group is ours.
+    // The capture-only worker owns no native helper; those handles were reaped in this parent.
+    try { process.kill(-owned.pid, "SIGKILL"); } catch { try { owned.kill("SIGKILL"); } catch { /* Already exited. */ } }
+  };
+  let timer: ReturnType<typeof setTimeout> | undefined, metadata: Awaited<ReturnType<typeof parentProject>> | undefined;
+  try {
+    if (early) {
+      spawn();
+      send({ ownedGroup: true, scan: { cwd: options.cwd, base, transcript, policy, deadlineAt: performance.timeOrigin + workDeadline } });
     }
+    const configuredBrief = loadAmemConfig(base, repoConfigRoot(options.cwd)).config.briefBytes;
+    const maxTokens = Math.min(HOOK_CONTEXT_BYTES, configuredBrief ?? HOOK_CONTEXT_BYTES, Math.max(1, options.maxTokens ?? HOOK_CONTEXT_BYTES));
+    metadata = await parentProject(options, base, workDeadline);
+    result.rssKB = metadata.usage.rssKB; result.rawRssKB = metadata.usage.rawRssKB; result.rssSources = combineRssSources(metadata.usage.rssSources);
+    if (!early && (!metadata.receipt || workDeadline - performance.now() < 5)) return result;
+    if (!owned) spawn();
+    result.rssSources.unavailable++;
+    // The worker reads the configuration itself (same base, same cwd), so it screens with exactly the policy the parent did.
+    // Without a receipt the worker still finishes the scan and reports it, but drains nothing.
+    send({ cwd: options.cwd, base, current: pending.name, event, identity: metadata.receipt, maxTokens, ownedGroup: true, deadlineAt: performance.timeOrigin + workDeadline, hookStartAt: performance.timeOrigin + hookStartedAt, policy });
+    close();
+    const answer = await Promise.race([
+      Promise.all([exit!, output!]),
+      new Promise<undefined>(resolve => { timer = setTimeout(() => { stop(); resolve(undefined); }, Math.max(1, workDeadline - performance.now())); }),
+    ]);
+    if (!answer || !answer[1]) return result;
+    const parsed = JSON.parse(answer[1]) as { context?: unknown; captured?: unknown; valid?: unknown; complete?: unknown; rssKB?: unknown; rssTelemetryValid?: unknown };
+    if (parsed.complete !== true) return result;
+    if (parsed.rssTelemetryValid !== true) tracker!.invalidate();
+    if (typeof parsed.context === "string" && Buffer.byteLength(parsed.context) <= maxTokens) result.context = parsed.context;
+    result.captured = parsed.captured === true; result.valid = parsed.valid === true;
+    return result;
   } catch { result.valid = false; return result; }
   finally {
-    // Even setup or accounting failure after spawn cannot leave an owned image live.
+    if (timer) clearTimeout(timer);
+    close();
     if (owned) {
-      if (!exited) try { process.kill(-owned.pid, "SIGKILL"); } catch { try { owned.kill("SIGKILL"); } catch { /* Already gone. */ } }
-      await owned.exited;
-    }
+      stop();
+      // #226: bounded reap; a worker stuck in uninterruptible I/O is abandoned after REAP_BOUND_MS, never awaited.
+      const reaped = exited || !(await boundedWait(exit!)).late;
+      const body = reaped ? await boundedWait(output!) : { late: true };
+      if (!reaped || body.late) { cancelOutput?.(); owned.unref(); }
+      if (!reaped) abandonedChildren++;
+      // Bun subprocess usage is bytes; process.resourceUsage is KiB. Not reaped: the last live sample is the RSS (ruling Q2).
+      const workerRawKB = reaped ? (owned.resourceUsage()?.maxRSS ?? 0) / 1024 : 0;
+      if (reaped ? body.late || body.value === undefined : !tracker!.hasLiveSample()) tracker!.invalidate();
+      const accounting = tracker!.finish(workerRawKB);
+      const usage = metadata?.usage ?? { rssKB: 0, rawRssKB: 0, rssSources: emptyRssSources() };
+      result.rssKB = usage.rssKB + accounting.rssKB; result.rawRssKB = usage.rawRssKB + workerRawKB; result.rssSources = combineRssSources(usage.rssSources, accounting.rssSources);
+      if (drainProgress.startMs !== undefined) lastDrain = { startMs: drainProgress.startMs, drained: drainProgress.drained ?? 0 };
+      if (early && killed) {
+        // #221: a kill without accepted progress is a deadline stop; a kill also skips this call's drain (ruling b).
+        if (result.transcript?.offset === undefined && result.transcript?.stopReason !== "unavailable") result.transcript = { stopReason: "deadline" };
+        if (!result.valid) drainSkipped++;
+      }
+    } else if (early) result.transcript ??= { stopReason: "deadline" };
   }
 }
 
@@ -245,7 +295,12 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
 async function captureAndWork(event: string, input: unknown, options: HookOptions, base: string, deadline: number) {
   if (event === "SessionStart") return sessionInParent(input, options, base, deadline);
   const transcript = (event === "Stop" || event === "SessionEnd") && input !== null && typeof input === "object" && "transcript_path" in input && typeof input.transcript_path === "string" ? input : undefined;
-  const work = (pending: PendingHookCapture) => hookWorker({ ...options, cwd: pending.cwd }, base, deadline, pending, event, transcript);
+  // #221: a transcript-bearing hook that ends without worker progress reports `deadline` only on positive evidence:
+  // the remaining time, measured at that exit, is below the worker's own start threshold. Policy, floor or invalid-input
+  // exits keep reporting nothing, so they cannot pass for bounded progress.
+  const deadlineEvidence = () => transcript !== undefined && deadline - WORKER_CLEANUP_MS - performance.now() < 5;
+  const withDeadline = <T extends { transcript?: HookTranscriptProgress }>(value: T): T => value.transcript === undefined && deadlineEvidence() ? { ...value, transcript: { stopReason: "deadline" } } : value;
+  const work = async (pending: PendingHookCapture) => withDeadline(await hookWorker({ ...options, cwd: pending.cwd }, base, deadline, pending, event, transcript));
   let result: Awaited<ReturnType<typeof work>> | undefined;
   let pending: PendingHookCapture | undefined;
   try { pending = await stageHookCapture(event, input, { ...options, base, deferAtCapacity: true }); }
@@ -261,7 +316,11 @@ async function captureAndWork(event: string, input: unknown, options: HookOption
       return { ...result, pending: false, dropped: true };
     }
   }
-  if (!pending) return result ? { ...result, pending: false } : undefined;
+  if (!pending) {
+    if (result) return { ...result, pending: false };
+    // Staging declined (policy, floor, invalid input) or ran out of time: only measured time makes it a deadline stop.
+    return deadlineEvidence() ? { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false, pending: false, transcript: { stopReason: "deadline" as const } } : undefined;
+  }
   result ??= await work(pending);
   return { ...result, pending: !result.captured };
 }
@@ -270,6 +329,7 @@ async function captureAndWork(event: string, input: unknown, options: HookOption
 export async function runHook(event: string, input: unknown, options: HookOptions, host?: HookHostPorts): Promise<HookReceipt> {
   const now = performance.now(), started = options.startedAt !== undefined && Number.isFinite(options.startedAt) && options.startedAt <= now ? options.startedAt : now;
   const deadline = started + handlerMs(host);
+  hookStartedAt = started;
   let base: string | undefined, captured = false, childRssKB = 0, childRawRssKB = 0, pending = false, dropped = false;
   let childSources = emptyRssSources();
   let transcriptProgress: HookTranscriptProgress | undefined;
@@ -291,13 +351,14 @@ export async function runHook(event: string, input: unknown, options: HookOption
   finally {
     if (base) try { const self = hookRssReading(); appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - started,
       rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
-      ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
+      ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
   }
 }
 
 /** Bounded stdin and a fixed overall handler budget; failures produce no native decision and exit successfully. */
 export async function hookMain(args: readonly string[], startedAt = performance.now(), host?: HookHostPorts): Promise<string> {
   const deadlineMs = handlerMs(host);
+  hookStartedAt = startedAt;
   let cleanup: (() => Promise<void>) | undefined;
   let childRssKB = 0, childRawRssKB = 0, dropped = false;
   let childSources = emptyRssSources();
@@ -341,7 +402,7 @@ export async function hookMain(args: readonly string[], startedAt = performance.
       const self = hookRssReading();
       appendMetrics(canonicalPath(memoryHome()), [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - startedAt,
         rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
-        ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]);
+        ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]);
     } catch { /* Invalid input and unavailable homes still fail open. */ }
   }
 }

package/src/memory/doctor.ts

@@ -19,6 +19,7 @@ import { aliasedKeys, shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
 import { readSetupDrift } from "../setup-drift.ts";
+import { readHookSpoolStatus } from "../hook-spool.ts";
 
 /**
  * F15, `amem doctor`: one report over the memory home. It writes nothing into the home. Every check that needs a store (the notes, the brief, the index proof) runs on a
@@ -63,6 +64,8 @@ export interface DoctorReport {
     duplicates: Section; stale: Section; candidates: Section; capture: Section; brief: Section; index: Section; readers: Section; policy: Section; cadence: Section;
     /** Added after v1 shipped (#132); additive, so the schema stays amem.doctor/v1. */
     drops: Section;
+    /** #217, additive: bounded read-only home-wide hook backlog inventory. */
+    spool?: Section;
     /** #188, additive: present only when the project's curated logs hold forget or prune operations. Informational; status is always ok. */
     masked?: Section;
     /** #202, additive: applied native setup registrations checked against the shared path resolver. */
@@ -363,6 +366,22 @@ function dropsSection(options: DoctorOptions): Section {
     ...(total ? { hint: "capture rows were dropped recently (see counts by reason); amem doctor --json keeps the numbers" } : {}) };
 }
 
+/** Bounded read-only inventory and classification; no replay, claim or retirement. */
+function spoolSection(options: DoctorOptions): Section {
+  try {
+    const inventory = readHookSpoolStatus(options.home);
+    const tiers = [inventory.active, inventory.reserve];
+    const full = tiers.some(tier => tier.files >= tier.maxFiles || tier.bytes >= tier.maxBytes);
+    const near = tiers.some(tier => tier.files >= tier.maxFiles * 0.9 || tier.bytes >= tier.maxBytes * 0.9);
+    return { ...inventory, status: !inventory.complete ? "unavailable" : full || near ? "attention" : "ok",
+      coverage: inventory.complete ? "complete" : "partial",
+      classificationCoverage: inventory.kinds.complete ? "complete" : "partial",
+      fill: full ? "full" : near ? "nearly_full" : !inventory.complete ? "unknown" : tiers.some(tier => tier.files > 0) ? "pending" : "empty",
+      ...(!inventory.complete ? { reason: "hook spool inventory is partial; reported file and byte counts are lower bounds" } : {}),
+      ...(full || near ? { hint: "pending hook spool needs attention: capture can be dropped when both tiers fill; supported orphan recovery is pending" } : {}) };
+  } catch { return unavailable("hook spool could not be read safely"); }
+}
+
 /** F16: which CLIs ingest at SessionEnd (setup receipts), and the person-owned sync cadence. amem registers no sync hook (a hook may not do network work). */
 function cadenceSection(options: DoctorOptions): Section {
   const ingest: Record<string, string> = {};
@@ -444,7 +463,7 @@ function guardScratch(): { adopt: (dir: string) => void; release: () => void } {
 export const DOCTOR_GIT_TIMEOUT_MS = 5_000;
 export function doctorReport(options: DoctorOptions): Promise<DoctorReport> {
   // Doctor reads every surface below, live or through a scratch copy: a floor on any of them refuses the whole report before anything is read (#199 AC5).
-  for (const surface of ["curated", "capture", "candidates", "work-lists"] as const) assertFormatFloor(options.home, surface);
+  for (const surface of ["curated", "capture", "candidates", "work-lists", "hook-spool"] as const) assertFormatFloor(options.home, surface);
   return withGitTimeout(DOCTOR_GIT_TIMEOUT_MS, () => runDoctor(options));
 }
 async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
@@ -497,7 +516,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let sections: DoctorReport["sections"];
   try {
     await tick();
-    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), setup, ...maskedSection(curated) };
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), spool: spoolSection(options), setup, ...maskedSection(curated) };
     await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
   } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
@@ -507,6 +526,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
 const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
   duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
   index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence", drops: "recent capture drops",
+  spool: "pending hook spool",
   setup: "native setup registrations",
   masked: "forgotten or pruned entries (informational)",
 };
@@ -528,6 +548,16 @@ function sectionDetail(name: string, detail: Record<string, unknown>, s: Style):
     const counts = Object.entries((detail.counts ?? {}) as Record<string, number>);
     return [counts.length ? `${counts.map(([reason, n]) => `${reason.replaceAll("_", " ")} ${n}`).join(", ")} (recent metrics tail)` : "none in the recent metrics tail"].map(line => detail.malformedLines ? `${line}; ${detail.malformedLines} malformed lines skipped` : line);
   }
+  if (name === "spool") {
+    if (!detail.active || !detail.reserve) return [];
+    const tiers = ["active", "reserve"].map(name => {
+      const tier = detail[name] as { files: number; bytes: number; maxFiles: number; maxBytes: number };
+      return `${name} ${tier.files}/${tier.maxFiles} files, ${tier.bytes}/${tier.maxBytes} bytes`;
+    });
+    const kinds = detail.kinds as { native: number; summaries: number; unclassified: number; complete: boolean };
+    return [`${detail.fill}; ${tiers.join("; ")}; claimed ${detail.claimed}; oldest ${detail.oldestAt ?? "none observed"}; coverage ${detail.coverage}${detail.complete ? "" : " (counts are lower bounds)"}`,
+      `native ${kinds.native}, summaries ${kinds.summaries}, unclassified ${kinds.unclassified}; classification ${detail.classificationCoverage}${kinds.complete ? "" : " (native and summary counts are lower bounds)"}`];
+  }
   if (name === "setup" && Array.isArray(detail.entries)) {
     return (detail.entries as { target?: unknown; file?: unknown; entry?: unknown; reason?: unknown; expectedFile?: unknown }[]).map(item =>
       singleLine(`${item.target} ${item.file}${item.expectedFile ? ` -> ${item.expectedFile}` : ""} ${item.entry}: ${item.reason}`));

package/src/memory/metrics.ts

@@ -1,9 +1,10 @@
 import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import type { HookRssSources } from "../hook-resources.ts";
+import type { HookTranscriptStopReason } from "../hook-contract.ts";
 import { join } from "node:path";
 
 /** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
-export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: "cap" | "deadline" | "spool_full"; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: HookTranscriptStopReason; /** #226: owned children killed but still alive when the hook returned (bounded reap). */ abandonedChildren?: number; /** #226: a killed worker skipped this call's drain; staged records stay pending (not a capture drop). */ drainSkipped?: number; /** #226: when the worker drain started (ms after hook start) and how many records it committed. */ drainStartMs?: number; drained?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
 const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
 
 export function metricsPath(base: string): string {
@@ -37,8 +38,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
-const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
+export type CaptureDropReason = "summary_capacity" | "scope_capacity" | "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
+const DROP_REASONS: readonly CaptureDropReason[] = ["summary_capacity", "scope_capacity", "spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

package/src/memory/public-prune-view.ts

@@ -49,14 +49,18 @@ export function waitForPublicPruneWriter(home: string, absoluteDeadline?: number
     const deadline = Math.min(absoluteDeadline ?? Infinity, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
     const intentFile = join(home, PUBLIC_PRUNE_INTENT), lockFile = join(home, "profile.lock");
     if (!lstatSync(intentFile, { throwIfNoEntry: false }) && !lstatSync(lockFile, { throwIfNoEntry: false })) return;
+    // #225: a cooperating writer that finishes unlinks its intent, then its lock. If that lands between this reader's
+    // open and fstat, the fd's link count is 0. Only that is the normal disappearance (ENOENT): bytes read through the fd
+    // are discarded and the bounded loop re-resolves the path from scratch. Any other link count still refuses.
+    const unlinked = (stat: Stats): void => { if (stat.nlink === 0) throw Object.assign(new Error("publication unlinked while open"), { code: "ENOENT" }); };
     const small = (file: string, limit: number): Record<string, unknown> => {
       const before = lstatSync(file); privateStat(before); guard(before.size > 0 && before.size <= limit);
       const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
       try {
-        const opened = fstatSync(fd); privateStat(opened); guard(opened.size > 0 && opened.size <= limit);
+        const opened = fstatSync(fd); unlinked(opened); privateStat(opened); guard(opened.size > 0 && opened.size <= limit);
         const bytes = Buffer.alloc(opened.size + 1); let count = 0;
         while (count < bytes.length) { const read = readSync(fd, bytes, count, bytes.length - count, count); if (!read) break; count += read; }
-        const after = fstatSync(fd); privateStat(after); guard(count === opened.size && same(opened, after));
+        const after = fstatSync(fd); unlinked(after); privateStat(after); guard(count === opened.size && same(opened, after));
         const parsed: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, count))); guard(object(parsed)); return parsed;
       } finally { closeSync(fd); }
     };

package/src/session-brief-worker.ts

@@ -6,35 +6,45 @@ import { hookRssReading, hookPeakRssKB } from "./hook-resources.ts";
 import { rssSourceCode } from "./hook-rss-wire.ts";
 import { resolveAlias } from "./memory/aliases.ts";
 import { HOOK_EVENTS, HOOK_INPUT_BYTES, type HookTranscriptProgress } from "./hook-contract.ts";
-import { drainHookCaptures, hookCaptureScope } from "./hook-spool.ts";
+import { drainHookCaptures, hookCaptureScope, hookReplayBudget } from "./hook-spool.ts";
+/** Existing allowance for the scan's own cursor commit; the parent also retains its cleanup reserve. */
+const SCAN_COMMIT_MS = 20;
 
-async function readOptions(): Promise<string> {
-  const reader = Bun.stdin.stream().getReader(), chunks: Uint8Array[] = []; let bytes = 0;
-  try {
+/** #226: options arrive as newline-delimited JSON. A transcript hook first sends the scan options, then (after native
+ * metadata) the drain options; other hooks send only the drain options. Total input stays bounded. */
+function optionLines(): () => Promise<string | undefined> {
+  const reader = Bun.stdin.stream().getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
+  let pending = "", bytes = 0, done = false;
+  return async () => {
     for (;;) {
-      const next = await reader.read(); if (next.done) break;
+      const at = pending.indexOf("\n");
+      if (at >= 0) { const line = pending.slice(0, at); pending = pending.slice(at + 1); return line; }
+      if (done) { const rest = pending; pending = ""; return rest || undefined; }
+      const next = await reader.read();
+      if (next.done) { done = true; pending += decoder.decode(); continue; }
       bytes += next.value.byteLength;
-      // Native input is at most64KiB; leave bounded room for fixed host options and policy literals.
-      if (bytes > HOOK_INPUT_BYTES + 32 * 1024) throw new Error("input bound");
-      chunks.push(next.value);
+      // Native input is at most 64 KiB, sent at most twice (scan, then drain); leave bounded room for fixed options.
+      if (bytes > 2 * HOOK_INPUT_BYTES + 32 * 1024) throw new Error("input bound");
+      pending += decoder.decode(next.value, { stream: true });
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
-  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+  };
 }
 
 // Fixed package helper, launched and reaped by each native hook; never registered or resident.
 if (import.meta.main) {
-  let owned = false;
-  let rssTelemetryValid = true;
+  let owned = false, rssTelemetryValid = true;
+  let lastProgress: HookTranscriptProgress | undefined;
   const frame = (rss: number[]) => { try { writeSync(1, JSON.stringify({ rss }) + "\n"); } catch { rssTelemetryValid = false; } };
-  const progress = (transcript: HookTranscriptProgress) => { try { writeSync(1, JSON.stringify({ transcript }) + "\n"); } catch { rssTelemetryValid = false; } };
+  const progress = (transcript: HookTranscriptProgress) => {
+    lastProgress = { ...lastProgress, ...transcript, ...(lastProgress?.stopReason === "unavailable" ? { stopReason: "unavailable" as const } : {}) };
+    try { writeSync(1, JSON.stringify({ transcript: lastProgress }) + "\n"); } catch { rssTelemetryValid = false; }
+  };
+  const drain = (value: { startMs?: number; drained: number }) => { try { writeSync(1, JSON.stringify({ drain: value }) + "\n"); } catch { rssTelemetryValid = false; } };
   frame([0]);
-  const stop = (): never => {
+  const stop: () => never = () => {
     if (!rssTelemetryValid) frame([4]);
     const self = hookRssReading(); frame([3, self.kb, self.rawKB, rssSourceCode(self)]);
-    // This leader is still alive in the detached group created by hookWorker.
-    // Native Git is owned and reaped by the CLI parent, never by this worker.
-    if (owned) try { process.kill(-process.pid, "SIGKILL"); } catch { /* No group exists in a direct, non-owned invocation. */ }
+    if (owned) try { process.kill(-process.pid, "SIGKILL"); } catch { /* A direct unowned invocation has no group. */ }
     process.exit(0);
   };
   const emit = async (result: unknown) => {
@@ -43,45 +53,86 @@ if (import.meta.main) {
     await Bun.stdout.write(body.slice(0, -1) + `,"rssKB":${rssKB}}\n`);
     stop();
   };
+  // Ordinary hooks preload only the store, as before. They must not pay for a transcript module they never use.
+  let captureReady = false;
+  const captureModule = import("./memory/capture.ts");
+  captureModule.then(() => { captureReady = true; }, () => { /* Reported when the final drain awaits it. */ });
+  const next = optionLines(), now = () => performance.timeOrigin + performance.now();
+  let store: CaptureStore | undefined;
   try {
-    const options = JSON.parse(await readOptions()) as BriefOptions & { current: string; event: string; identity?: unknown; transcript?: unknown; deadlineAt: number; ownedGroup: boolean };
-    if (!Number.isFinite(options.deadlineAt) || options.ownedGroup !== true) process.exit(0);
+    const line = await next();
+    if (line === undefined) stop();
+    const first = JSON.parse(line) as Record<string, unknown>;
+    type Scan = { cwd: string; base: string; transcript: unknown; policy?: BriefOptions["policy"]; deadlineAt: number };
+    type DrainOptions = BriefOptions & { current: string; event: string; identity?: unknown; deadlineAt: number; ownedGroup: boolean; hookStartAt?: number };
+    const scan = first.scan as Scan | undefined;
+    const deadlineAt = scan?.deadlineAt ?? first.deadlineAt;
+    if (!Number.isFinite(deadlineAt) || first.ownedGroup !== true) stop();
     owned = true;
-    const remaining = () => options.deadlineAt - (performance.timeOrigin + performance.now());
-    const deadlineStop = () => { if (options.transcript !== undefined) progress({ stopReason: "deadline" }); stop(); };
-    if (remaining() <= 0) deadlineStop();
-    setTimeout(deadlineStop, remaining()).unref();
-    const event = options.event;
-    if (!(HOOK_EVENTS as readonly string[]).includes(event)) stop();
-    const expectedScope = hookCaptureScope(options.cwd, options.base!);
-    // A receipt is single-use parent IPC. This worker must never launch a native helper.
-    if (event === "SessionStart") stop();
-    let project: string | undefined;
-    try { project = resolveAlias(options.base!, acceptHookProjectReceipt(options.identity, { cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining })); } catch { /* Independently bound transcript intake can still proceed. */ }
-    if ((event === "Stop" || event === "SessionEnd") && options.transcript !== undefined
-      && (project !== undefined || expectedScope !== undefined && hookCaptureScope(options.cwd, options.base!) === expectedScope)) {
-      try {
-        const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
-        const scanned = await scanHookTranscriptTail(options.transcript, { cwd: options.cwd, base: options.base!, policy: options.policy,
-          deadline: Math.min(performance.now() + remaining() - 20, performance.now() + 60) });
-        if (scanned) progress(scanned);
-      } catch { /* Ordinary durable capture is independent. */ }
-    }
-    if (project === undefined) stop();
-    let captured = false;
-    // An empty current name selects bounded full-tier recovery; SessionStart stays in the parent.
-    if (expectedScope !== undefined) {
-      const { CaptureStore } = await import("./memory/capture.ts");
-      let store: CaptureStore | undefined;
-      try {
-        const drained = await drainHookCaptures({ ...options, base: options.base!, project: project!, expectedScope, timeRemaining: remaining }, (input, receipt) => {
-          store ??= new CaptureStore({ memoryDir: options.base!, project: project!, busyTimeoutMs: 0, cwd: options.cwd });
-          return store.append(input, { receipt });
-        });
-        captured = drained.captured.includes(options.current);
-      } finally { store?.close(); }
-    }
-    if (hookCaptureScope(options.cwd, options.base!) !== expectedScope) stop();
+    const end = deadlineAt as number;
+    if (now() >= end) { if (scan) progress({ stopReason: "deadline" }); stop(); }
+    setTimeout(() => { if (scan) progress({ stopReason: "deadline" }); stop(); }, end - now()).unref();
+
+    // Read the native receipt while scan setup runs. Publication callbacks await it only when replay can proceed.
+    const drainLine = scan ? next() : Promise.resolve(line);
+    const ready = (async () => {
+      const text = await drainLine;
+      if (text === undefined) return undefined;
+      const options = JSON.parse(text) as DrainOptions;
+      if (options.ownedGroup !== true || options.deadlineAt !== end || !(HOOK_EVENTS as readonly string[]).includes(options.event) || options.event === "SessionStart") return undefined;
+      const expectedScope = hookCaptureScope(options.cwd, options.base!);
+      let project: string | undefined;
+    try { project = resolveAlias(options.base!, acceptHookProjectReceipt(options.identity, { cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: () => end - now() })); } catch { /* A bound scan may still stage without a project. */ }
+      return { options, expectedScope, project };
+    })();
+    let receiptReady = false;
+    ready.then(() => { receiptReady = true; }, () => { /* The final drain reports failure inside the owned helper. */ });
+    const budget = hookReplayBudget();
+    let drainedCount = 0, captured = false, drainStarted = false;
+    const replay = async (until: number, waitForReady = true) => {
+      // Scanning must not wait on native metadata or cold store imports between summary lines.
+      // The final replay may await them; publication/backpressure callbacks only use ready resources.
+      if (!waitForReady && (!receiptReady || !captureReady)) return false;
+      if (!budget.files || !budget.bytes || until - now() < 8) return false;
+      const context = await ready;
+      if (!context?.project || context.expectedScope === undefined || Math.min(end, until) - now() < 8) return false;
+      const { options, expectedScope, project } = context;
+      const { CaptureStore } = await captureModule;
+      const remaining = () => Math.min(end, until) - now();
+      if (remaining() < 8) return false;
+      if (!drainStarted) {
+        drain({ startMs: Math.round(now() - (options.hookStartAt ?? end)), drained: drainedCount });
+        drainStarted = true;
+      }
+      const drained = await drainHookCaptures({ ...options, base: options.base!, project, expectedScope, timeRemaining: remaining, replayBudget: budget }, (input, receipt) => {
+        store ??= new CaptureStore({ memoryDir: options.base!, project, busyTimeoutMs: 0, cwd: options.cwd });
+        const appended = store.append(input, { receipt });
+        drain({ drained: ++drainedCount }); // DB commit or durable capture-spool acknowledgement, as in the existing contract.
+        return appended;
+      });
+      captured ||= drained.captured.includes(options.current);
+      return drained.captured.length > 0;
+    };
+    let context: Awaited<typeof ready>;
+    try {
+      if (scan && hookCaptureScope(scan.cwd, scan.base) !== undefined) {
+        const scanEnd = end - SCAN_COMMIT_MS;
+        if (scanEnd - now() < 5) progress({ stopReason: "deadline" });
+        else try {
+          const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
+          const scanned = await scanHookTranscriptTail(scan.transcript, {
+            cwd: scan.cwd, base: scan.base, policy: scan.policy, deadline: performance.now() + (scanEnd - now()),
+            // Same existing oldest-first drain and one shared budget, never a new 32-file allowance per publication.
+            onPublication: async () => { await replay(scanEnd, false); },
+            onBackpressure: () => replay(scanEnd, false),
+          });
+          if (scanned) progress(scanned);
+        } catch { progress({ stopReason: "unavailable" }); }
+      }
+      context = await ready;
+      await replay(end); // Newly staged summaries get their final commit opportunity in this hook too.
+    } finally { store?.close(); }
+    if (!context?.project || hookCaptureScope(context.options.cwd, context.options.base!) !== context.expectedScope) stop();
     await emit({ context: "", captured, valid: true });
   } catch { if (owned) stop(); process.exitCode = 1; }
 }