@staix/agent-mem 0.19.0 → 0.20.0

package/src/hook-spool.ts

@@ -22,12 +22,18 @@ import { HOOK_EVENTS, HOOK_INPUT_BYTES } from "./hook-contract.ts";
 // `hook-` nor `hook-v2-` for it, so they leave it alone. Claude native rows stay format 2, byte for byte, so 0.18.0 keeps draining them.
 const SCHEMA = "agent-mem.hook-capture/v1", FAMILY = "agent-mem.hook-capture", FORMAT = 2, PREFIX = "hook-v2-", FORMAT_V3 = 3, PREFIX_V3 = "hook-v3-";
 const RECORD_BYTES = HOOK_INPUT_BYTES + 8192, MAX_FILES = 256, MAX_BYTES = 2 * 1024 * 1024;
-const DRAIN_FILES = 32, DRAIN_BYTES = 256 * 1024;
+// One hook previously performed one replay of at most 32 files / 256 KiB.
+// Interleaved subpasses share these same ceilings; they do not each get a fresh allowance.
+export const HOOK_REPLAY_MAX_FILES = 32, HOOK_REPLAY_MAX_BYTES = 256 * 1024;
+const DRAIN_FILES = HOOK_REPLAY_MAX_FILES, DRAIN_BYTES = HOOK_REPLAY_MAX_BYTES;
+export interface HookReplayBudget { files: number; bytes: number; seen: Set<string> }
+export const hookReplayBudget = (): HookReplayBudget => ({ files: HOOK_REPLAY_MAX_FILES, bytes: HOOK_REPLAY_MAX_BYTES, seen: new Set() });
 // ponytail: a finite native admission reserve covers deferred replay, not unlimited locked intake.
 // Upgrade: coordinated append-only capacity accounting and observable backpressure at exhaustion.
 const CAPACITY_FILES = 32, CAPACITY_BYTES = 256 * 1024;
 const namePattern = /^(hook-(?:v[23]-)?([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
 const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
+const summaryEvent = (event: string) => ["Title", "Recap", "Compact"].includes(event);
 interface Record { schema: string; format?: number; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
 export interface PendingHookCapture { name: string; cwd: string; receipt: string; deferred?: true; backlog?: true }
 export class HookSpoolFull extends Error { constructor() { super("hook storage full"); } }
@@ -43,7 +49,9 @@ function belowFloor(base: string): boolean {
 function physicalRoot(cwd: string): string {
   const stat = lstatSync(cwd);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("hook root unavailable");
-  return hash(`${stat.dev}:${stat.ino}:${stat.birthtimeMs}`);
+  // macOS can assign a different st_dev after reboot. Keep the directory's inode
+  // and birth time; open-file ownership still compares dev as well as inode.
+  return hash(`${stat.ino}:${stat.birthtimeMs}`);
 }
 
 function privateDirectory(dir: string): void {
@@ -52,23 +60,92 @@ function privateDirectory(dir: string): void {
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("hook storage unavailable");
   chmodSync(dir, 0o700);
 }
-function entries(base: string, capacity = false): { name: string; size: number; modified: number }[] {
+function entries(base: string, capacity = false, coverage?: { complete: boolean }): { name: string; size: number; modified: number; dev: number; ino: number }[] {
+  if (coverage) coverage.complete = false;
   const dir = capacity ? join(directory(base), ".capacity") : directory(base), maximum = capacity ? CAPACITY_FILES : MAX_FILES, stat = lstatSync(dir, { throwIfNoEntry: false });
-  if (!stat) return [];
+  if (!stat) { if (coverage) coverage.complete = true; return []; }
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("hook storage unavailable");
-  const reader = opendirSync(dir), rows: { name: string; size: number; modified: number }[] = [];
+  const reader = opendirSync(dir), rows: { name: string; size: number; modified: number; dev: number; ino: number }[] = [];
   try {
     for (let scanned = 0; scanned <= maximum + 4; scanned++) {
-      const entry = reader.readSync(); if (!entry) return rows;
+      const entry = reader.readSync(); if (!entry) { if (coverage) coverage.complete = true; return rows; }
       if ([".writing", ".quarantine", ".capacity", ".maintenance"].includes(entry.name) && entry.isDirectory()) continue;
       if (rows.length === maximum) return rows;
       const item = lstatSync(join(dir, entry.name), { throwIfNoEntry: false });
-      if (item) rows.push({ name: entry.name, size: item.size, modified: item.mtimeMs });
+      if (item) rows.push({ name: entry.name, size: item.size, modified: item.mtimeMs, dev: item.dev, ino: item.ino });
     }
     return rows;
   } finally { reader.closeSync(); }
 }
 
+/** A bounded diagnostic count of this cwd's active publications (names only, no stat).
+ * Task 110 schedules replay by publication/backpressure progress, not this legacy count. */
+export function hookPendingCount(cwd: string, base: string): number {
+  try {
+    const dir = directory(canonicalPath(base)), wanted = hash(realPath(cwd)), reader = opendirSync(dir);
+    let count = 0;
+    try {
+      for (let scanned = 0; scanned < MAX_FILES; scanned++) {
+        const entry = reader.readSync(); if (!entry) break;
+        const match = namePattern.exec(entry.name);
+        if (match && match[2] === wanted) count++;
+      }
+    } finally { reader.closeSync(); }
+    return count;
+  } catch { return 0; }
+}
+
+/** Read-only bounded metadata inventory. Counts are lower bounds when complete is false. */
+export function readHookSpoolStatus(base: string) {
+  assertFormatFloor(base, "hook-spool");
+  let claimed = 0, oldest = Infinity, complete = true;
+  const publications: { folder: string; name: string; size: number; modified: number }[] = [];
+  const tier = (capacity: boolean) => {
+    const dir = capacity ? join(directory(base), ".capacity") : directory(base);
+    const maxFiles = capacity ? CAPACITY_FILES : MAX_FILES, maxBytes = capacity ? CAPACITY_BYTES : MAX_BYTES;
+    const named = lstatSync(dir, { throwIfNoEntry: false });
+    let files = 0, bytes = 0;
+    if (!named) return { files, bytes, maxFiles, maxBytes };
+    if (!named.isDirectory() || named.isSymbolicLink()) throw new Error("hook storage unavailable");
+    const reader = opendirSync(dir);
+    try {
+      for (let scanned = 0; scanned <= maxFiles + 4; scanned++) {
+        const entry = reader.readSync();
+        if (!entry) return { files, bytes, maxFiles, maxBytes };
+        if (!capacity && [".writing", ".quarantine", ".capacity", ".maintenance"].includes(entry.name) && entry.isDirectory()) continue;
+        if (files === maxFiles) break;
+        const item = lstatSync(join(dir, entry.name), { throwIfNoEntry: false });
+        if (!item) { complete = false; continue; }
+        files++; bytes += item.size; oldest = Math.min(oldest, item.mtimeMs);
+        publications.push({ folder: dir, name: entry.name, size: item.size, modified: item.mtimeMs });
+        if (namePattern.test(entry.name) && entry.name.includes(".draining-")) claimed++;
+      }
+      complete = false;
+      return { files, bytes, maxFiles, maxBytes };
+    } finally { reader.closeSync(); }
+  };
+  const active = tier(false), reserve = tier(true), budget = maintenanceBudget();
+  let native = 0, summaries = 0;
+  for (const row of publications) {
+    const match = namePattern.exec(row.name);
+    if (!match || row.size > RECORD_BYTES) continue;
+    if (!budget.files || row.size > budget.bytes) break;
+    budget.files--; budget.bytes -= row.size;
+    let file: OwnedFile | undefined;
+    try {
+      file = openOwned(join(row.folder, row.name));
+      if (file.initial.size !== row.size || file.initial.mtimeMs !== row.modified) continue;
+      const record = decoded(file);
+      if (!record || record.unknown || hash(record.value.cwd) !== match[2] || (record.value.scope ?? "0".repeat(64)) !== match[3] || record.value.nonce !== match[4]) continue;
+      if (summaryEvent(record.value.capture.event)) summaries++; else native++;
+    } catch { /* Body classification stays unknown; metadata does not become a false zero. */ }
+    finally { if (file) closeSync(file.fd); }
+  }
+  const unclassified = active.files + reserve.files - native - summaries;
+  const kinds = { native, summaries, unclassified, complete: complete && unclassified === 0 };
+  return { active, reserve, claimed, oldestAt: Number.isFinite(oldest) ? new Date(oldest).toISOString() : null, complete, kinds };
+}
+
 /** Validate ordinary Git value syntax even for ignored keys: invalid unused configuration can make
  * native Git refuse the whole file, so ignoring its syntax could falsely certify project resolution. */
 function validateConfigValue(value: string): void {
@@ -139,11 +216,16 @@ function identityConfig(text: string, include?: (path: string, condition?: strin
  * ponytail: strict unsupported Git configuration remains unknown, not guessed. A native historical-origin
  * receipt would broaden that supported subset without relaxing the physical replacement boundary. */
 export function hookCaptureScope(cwd: string, base: string, cacheValidity = false, extraGitConfig?: string): string | undefined {
+  return captureScope(cwd, base, cacheValidity, extraGitConfig, false);
+}
+/** 0.19.0 and older write a device-bound scope. Only its current-boot value is knowable;
+ * never guess an old device or silently rebind a record whose HOME/Git identity changed. */
+function captureScope(cwd: string, base: string, cacheValidity: boolean, extraGitConfig: string | undefined, legacyDevice: boolean): string | undefined {
   try {
     const parts: string[] = [], identity = (file: string) => {
       const stat = lstatSync(file);
       if (!stat.isDirectory()) throw new Error("physical scope unavailable");
-      return `${stat.dev}:${stat.ino}:${stat.birthtimeMs}`;
+      return `${legacyDevice || cacheValidity ? `${stat.dev}:` : ""}${stat.ino}:${stat.birthtimeMs}`;
     };
     const content = (file: string, maximum = 64 * 1024): string => {
       const named = lstatSync(file, { throwIfNoEntry: false });
@@ -365,11 +447,13 @@ function retireClaim(base: string, file: OwnedFile, preserve: boolean, batch?: Q
   return true;
 }
 
-const RETIRE_AFTER_MS = 7 * 24 * 3600_000;
+const RETIRE_AFTER_MS = 7 * 24 * 3600_000, MISSING_CWD_AFTER_MS = 3600_000;
+interface MaintenanceBudget { files: number; bytes: number }
+const maintenanceBudget = (): MaintenanceBudget => ({ files: DRAIN_FILES, bytes: DRAIN_BYTES });
 /** Private numeric maintenance cursor: each invocation inspects a different bounded slice. */
-function retirementCursor(base: string, capacity: boolean, length: number): { start: number; save(n: number): void } {
+function retirementCursor(base: string, capacity: boolean, length: number, pressure = false): { start: number; save(n: number): void } {
   const dir = join(directory(base), ".maintenance"); privateDirectory(dir);
-  const name = join(dir, capacity ? "reserve" : "active");
+  const name = join(dir, `${capacity ? "reserve" : "active"}${pressure ? "-pressure" : ""}`);
   let start = 0, file: OwnedFile | undefined;
   try {
     file = openOwned(name);
@@ -385,62 +469,125 @@ function retirementCursor(base: string, capacity: boolean, length: number): { st
     finally { rmSync(temporary, { force: true }); }
   } };
 }
-/** ponytail: remove undrainable data only after seven days, at
- * most32 files/256KiB per admission. Count loss before deleting bodies. Upgrade:
- * a person-visible durable dead-letter export and coordinated maintenance accounting. */
-function retireUnresolved(base: string, _admittingCwd: string | undefined, inventory: ReturnType<typeof entries>, incomingBytes: number, minimal: boolean, capacity = false, _sharedBatch?: QuarantineBatch): Set<string> {
-  const retired = new Set<string>();
+/** Bounded, counted retirement: missing cwds after one hour, other unresolvable known
+ * scopes after seven days, and fair-share pressure. Newer schemas retain their seven-day
+ * protection. A semantic/physical scope mismatch alone never proves a cwd was replaced.
+ * ponytail: fair shares are cooperative admission, not an atomic multi-process quota.
+ * Upgrade: coordinated byte/file reservations with crash recovery. */
+function retireUnresolved(base: string, admittingCwd: string | undefined, inventory: ReturnType<typeof entries>, incomingBytes: number, minimal: boolean, capacity = false, budget = maintenanceBudget(), scanLimit = DRAIN_FILES): Set<string> {
+  const retired = new Set<string>(), cwdHash = admittingCwd === undefined ? undefined : hash(admittingCwd);
   let count = inventory.length, bytes = inventory.reduce((sum, row) => sum + row.size, 0);
-  const fits = () => count < (capacity ? CAPACITY_FILES : MAX_FILES) && bytes + incomingBytes <= (capacity ? CAPACITY_BYTES : MAX_BYTES);
-  const due = inventory.some(row => Date.now() - row.modified >= RETIRE_AFTER_MS);
-  if (!inventory.length || minimal && fits() && !due) return retired;
+  const maximum = capacity ? CAPACITY_FILES : MAX_FILES, byteMaximum = capacity ? CAPACITY_BYTES : MAX_BYTES, share = maximum / 4;
+  const groups = new Map<string, number>();
+  for (const row of inventory) {
+    const match = namePattern.exec(row.name); if (match) groups.set(match[2]!, (groups.get(match[2]!) ?? 0) + 1);
+  }
+  const quota = () => cwdHash !== undefined && (groups.get(cwdHash) ?? 0) >= share;
+  const pressure = () => cwdHash !== undefined && (quota() || count >= maximum || bytes + incomingBytes > byteMaximum);
+  const due = inventory.some(row => Date.now() - row.modified >= MISSING_CWD_AFTER_MS);
+  const pressured = pressure();
+  if (!inventory.length || minimal && !pressured) return retired;
   const active = [...inventory].sort((a, b) => a.modified - b.modified || a.name.localeCompare(b.name));
   let cursor: ReturnType<typeof retirementCursor>;
-  try { cursor = retirementCursor(base, capacity, active.length); } catch { return retired; }
-  let remaining = DRAIN_BYTES, scanned = 0;
+  try { cursor = retirementCursor(base, capacity, active.length, pressured); } catch { return retired; }
+  let scanned = 0;
   const scopes = new Map<string, string | undefined>();
+  // Pressure first visits the largest share; HOME variants of one cwd share one allowance.
+  const ordered = pressure() ? [...active].sort((a, b) => {
+    const group = (row: typeof a) => namePattern.exec(row.name)?.[2];
+    const score = (row: typeof a) => { const key = group(row); return quota() ? Number(key === cwdHash) * (maximum + 1) : groups.get(key ?? "") ?? 0; };
+    return score(b) - score(a) || a.modified - b.modified || a.name.localeCompare(b.name);
+  }) : active;
+  const candidates = ordered.slice(cursor.start).concat(ordered.slice(0, cursor.start));
+  const held: { file: OwnedFile; row: typeof inventory[number]; group: string }[] = [];
+  let classified = 0, nativeSeen = false;
   try {
-    for (; scanned < Math.min(DRAIN_FILES, active.length); scanned++) {
-      if (minimal && fits() && !due) break;
-      const row = active[(cursor.start + scanned) % active.length]!;
-      const match = namePattern.exec(row.name); if (!match) continue;
-      if (row.size <= RECORD_BYTES && row.size > remaining) break;
+    for (const row of candidates) {
+      if (!budget.files || scanned >= scanLimit || !pressure() && (minimal || pressured && !due)) break;
+      const match = namePattern.exec(row.name); if (!match) { scanned++; continue; }
+      if (row.size <= RECORD_BYTES && row.size > budget.bytes) break;
+      budget.files--; scanned++;
       let file: OwnedFile | undefined;
       try {
         file = openOwned(join(capacity ? join(directory(base), ".capacity") : directory(base), row.name));
         if (file.initial.size !== row.size || file.initial.mtimeMs !== row.modified) continue;
-        if (row.size <= RECORD_BYTES) remaining -= row.size;
+        if (row.size <= RECORD_BYTES) budget.bytes -= row.size;
         const record = decoded(file);
         const valid = record && hash(record.value.cwd) === match[2] && record.value.nonce === match[4] && (record.value.scope ?? "0".repeat(64)) === match[3];
         let reason: CaptureDropReason | undefined;
         if (valid && record.unknown) {
-          // #199: a newer writer's record waits for a reader that knows it, then leaves with a counted reason, never at once.
           if (Date.now() - row.modified < RETIRE_AFTER_MS) continue;
           reason = "unknown_schema_expired";
         } else if (valid) {
-          if (Date.now() - Date.parse(record.value.capture.at) < RETIRE_AFTER_MS) continue;
-          try { const cwd = lstatSync(record.value.cwd); if (!cwd.isDirectory() || cwd.isSymbolicLink()) reason = "cwd_removed"; }
-          catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") reason = "cwd_removed"; }
-          if (!reason) {
+          classified++;
+          const summary = summaryEvent(record.value.capture.event);
+          if (!summary) nativeSeen = true;
+          const age = Date.now() - Date.parse(record.value.capture.at);
+          if (age >= MISSING_CWD_AFTER_MS && Date.now() - row.modified >= MISSING_CWD_AFTER_MS) {
+            try { lstatSync(record.value.cwd); }
+            catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") reason = "cwd_removed"; }
+          }
+          if (!reason && age >= RETIRE_AFTER_MS) {
             if (record.value.scope === null) reason = "scope_unknown";
             else {
               if (!scopes.has(record.value.cwd)) scopes.set(record.value.cwd, hookCaptureScope(record.value.cwd, base));
               const currentScope = scopes.get(record.value.cwd);
               if (currentScope === undefined) reason = "scope_unknown";
-              else if (currentScope !== record.value.scope) reason = "undrainable_expired";
+              else if (currentScope !== record.value.scope && captureScope(record.value.cwd, base, false, undefined, true) !== record.value.scope) reason = "undrainable_expired";
             }
           }
+          if (!reason && pressure()) {
+            if (summary) {
+              // An advanced transcript cursor relies on accepted summaries. Hold their
+              // descriptors only to prove a complete all-summary foreign inventory.
+              if (!quota()) { held.push({ file, row, group: match[2]! }); file = undefined; }
+              continue;
+            }
+            if (!quota() || match[2] === cwdHash) reason = "scope_capacity";
+          }
           if (!reason) continue;
         }
         const claim = claimOwned(base, row.name, file);
         if (!claim || !owns(claim)) continue;
-        // Failure to persist this numeric receipt keeps the body pending, never silently lost.
+        if (reason === "cwd_removed") {
+          try { lstatSync(record!.value.cwd); continue; }
+          catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") continue; }
+        }
+        // Persist the numeric loss receipt BEFORE removing a replayable body.
         if (reason) appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: reason }]);
-        if (retireClaim(base, claim, false)) { retired.add(row.name); count--; bytes -= row.size; }
+        if (retireClaim(base, claim, false)) {
+          retired.add(row.name); count--; bytes -= row.size;
+          groups.set(match[2]!, Math.max(0, (groups.get(match[2]!) ?? 0) - 1));
+        }
       } catch { /* Transient I/O and changed evidence stay pending. */ }
       finally { if (file) closeSync(file.fd); }
     }
-  } finally { try { cursor.save(cursor.start + Math.max(1, scanned)); } catch { /* Derived cursor failure never deletes data. */ } }
+    // ponytail: a cap of summaries from four or more orphaned cwds can still
+    // refuse intake until TTL/replay: 32 files/256 KiB cannot prove native absence
+    // across the whole cap. Upgrade: a bounded derived classification cache.
+    if (pressure() && !quota() && !nativeSeen && classified === inventory.length && held.length === inventory.length
+      && held.every(item => owns(item.file))) {
+      const coverage = { complete: false }, current = entries(base, capacity, coverage);
+      if (coverage.complete && current.length === inventory.length && current.every(row => inventory.some(prior => prior.name === row.name && prior.size === row.size && prior.modified === row.modified))) {
+        const victims = held.filter(item => item.group !== cwdHash).sort((a, b) => (groups.get(b.group) ?? 0) - (groups.get(a.group) ?? 0) || a.row.modified - b.row.modified || a.row.name.localeCompare(b.row.name));
+        for (const victim of victims) {
+          if (!pressure()) break;
+          try {
+            const claim = claimOwned(base, victim.row.name, victim.file);
+            if (!claim || !owns(claim)) continue;
+            appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: "summary_capacity" }]);
+            if (retireClaim(base, claim, false)) {
+              retired.add(victim.row.name); count--; bytes -= victim.row.size;
+              groups.set(victim.group, Math.max(0, (groups.get(victim.group) ?? 0) - 1));
+            }
+          } catch { /* Failed counting or changed ownership preserves the body. */ }
+        }
+      }
+    }
+  } finally {
+    for (const item of held) closeSync(item.file.fd);
+    try { cursor.save(retired.size ? 0 : cursor.start + Math.max(1, scanned)); } catch { /* A derived cursor never acknowledges capture. */ }
+  }
   return retired;
 }
 
@@ -532,32 +679,67 @@ function publishCapture(event: string, capture: NormalizedCaptureFields, options
   if (Buffer.byteLength(bytes) > RECORD_BYTES) throw new Error("hook record bound");
   const dir = directory(base), writing = join(dir, ".writing"); privateDirectory(dir); privateDirectory(writing);
   let destination = dir, deferred = false, backlog = false;
+  const budget = maintenanceBudget(), incomingBytes = Buffer.byteLength(bytes), cwdHash = hash(cwd);
+  const withinShare = (rows: ReturnType<typeof entries>, maximum: number) => rows.filter(row => namePattern.exec(row.name)?.[2] === cwdHash).length < maximum / 4;
+  const name = `${v3 ? PREFIX_V3 : PREFIX}${cwdHash}-${scope ?? "0".repeat(64)}-${nonce}.json`;
+  let activeInventory: ReturnType<typeof entries> | undefined, reserveInventory: ReturnType<typeof entries> | undefined;
+  if (["Title", "Recap", "Compact"].includes(event)) {
+    // Transcript cursor recovery can repeat a deterministic publication. An already
+    // durable identical body needs no new slot, including when a drainer owns it.
+    for (const capacity of [false, true]) {
+      const inventory = entries(base, capacity);
+      if (capacity) reserveInventory = inventory; else activeInventory = inventory;
+      for (const row of inventory) {
+        if (!namePattern.test(row.name) || row.name !== name && !row.name.startsWith(name + ".draining-")) continue;
+        if (!budget.files || row.size > budget.bytes) break;
+        budget.files--; budget.bytes -= row.size;
+        let existing: OwnedFile | undefined;
+        try {
+          existing = openOwned(join(capacity ? join(dir, ".capacity") : dir, row.name));
+          if (existing.initial.size !== incomingBytes) continue;
+          const held = Buffer.alloc(incomingBytes);
+          if (readSync(existing.fd, held, 0, held.length, 0) === held.length && owns(existing) && held.equals(Buffer.from(bytes))) {
+            return { name, cwd, receipt: hash(bytes), backlog: true, ...(capacity ? { deferred: true as const } : {}) };
+          }
+        } catch { /* Changed or unavailable evidence is not acknowledgement. */ }
+        finally { if (existing) closeSync(existing.fd); }
+      }
+    }
+  }
   if (event === "SessionStart") {
     // ponytail: reserve-only admission scans at most 32 metadata entries, not O(1).
     // Never inspect/retire the active tier on the brief deadline. Fixed-slot byte
     // reservations with crash recovery are the upgrade if this bound is too costly.
     destination = join(dir, ".capacity"); privateDirectory(destination);
-    const reserved = entries(base, true);
-    if (reserved.length >= CAPACITY_FILES || reserved.reduce((sum, row) => sum + row.size, 0) + Buffer.byteLength(bytes) > CAPACITY_BYTES) throw new HookSpoolFull();
+    const inventory = entries(base, true);
+    const retired = retireUnresolved(base, cwd, inventory, incomingBytes, true, true, budget);
+    const reserved = inventory.filter(row => !retired.has(row.name));
+    if (!withinShare(reserved, CAPACITY_FILES) || reserved.length >= CAPACITY_FILES || reserved.reduce((sum, row) => sum + row.size, 0) + Buffer.byteLength(bytes) > CAPACITY_BYTES) throw new HookSpoolFull();
     deferred = true; backlog = reserved.length > 0;
   } else {
-    const inventory = entries(base), quarantineBatch: QuarantineBatch = {};
-    const retired = retireUnresolved(base, cwd, inventory, Buffer.byteLength(bytes), false, false, quarantineBatch);
+    const inventory = activeInventory ?? entries(base);
+    if (summaryEvent(event) && (!withinShare(inventory, MAX_FILES) || inventory.length >= MAX_FILES || inventory.reduce((sum, row) => sum + row.size, 0) + incomingBytes > MAX_BYTES)) throw new HookSpoolFull();
+    let reserved = reserveInventory ?? entries(base, true);
+    // Split a nonempty two-tier backlog's inspection budget so neither tier starves.
+    const retired = retireUnresolved(base, cwd, inventory, incomingBytes, false, false, budget, reserved.length ? DRAIN_FILES / 2 : DRAIN_FILES);
     const queued = inventory.filter(row => !retired.has(row.name));
-    let reserved = entries(base, true);
-    // Reserve maintenance must progress even while ordinary admission has space:
-    // SessionStart never retires, so otherwise expired undrainable reserve data pins it.
-    const retiredCapacity = retireUnresolved(base, cwd, reserved, Buffer.byteLength(bytes), true, true, quarantineBatch);
-    reserved = reserved.filter(row => !retiredCapacity.has(row.name));
+    const activeFits = withinShare(queued, MAX_FILES) && queued.length < MAX_FILES && queued.reduce((sum, row) => sum + row.size, 0) + incomingBytes <= MAX_BYTES;
+    // If active admission failed, reserve pressure gets the remaining budget first.
+    if (activeFits) {
+      const retiredCapacity = retireUnresolved(base, undefined, reserved, 0, false, true, budget);
+      reserved = reserved.filter(row => !retiredCapacity.has(row.name));
+    }
     backlog = queued.length > 0 || reserved.length > 0;
-    if (queued.length >= MAX_FILES || queued.reduce((sum, row) => sum + row.size, 0) + Buffer.byteLength(bytes) > MAX_BYTES) {
+    if (!activeFits) {
       if (options.deferAtCapacity !== true) throw new HookSpoolFull();
       destination = join(dir, ".capacity"); privateDirectory(destination);
-      if (reserved.length >= CAPACITY_FILES || reserved.reduce((sum, row) => sum + row.size, 0) + Buffer.byteLength(bytes) > CAPACITY_BYTES) throw new HookSpoolFull();
+      const retiredReserve = retireUnresolved(base, cwd, reserved, incomingBytes, true, true, budget);
+      reserved = reserved.filter(row => !retiredReserve.has(row.name));
+      if (!withinShare(reserved, CAPACITY_FILES) || reserved.length >= CAPACITY_FILES || reserved.reduce((sum, row) => sum + row.size, 0) + Buffer.byteLength(bytes) > CAPACITY_BYTES) throw new HookSpoolFull();
       deferred = true;
     }
   }
-  const name = `${v3 ? PREFIX_V3 : PREFIX}${hash(cwd)}-${scope ?? "0".repeat(64)}-${nonce}.json`, temporary = join(writing, name);
+  const temporary = join(writing, name);
   try { writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" }); renameSync(temporary, join(destination, name)); }
   finally { rmSync(temporary, { force: true }); }
   return { name, cwd, receipt: hash(bytes), ...(deferred ? { deferred: true as const } : {}), ...(backlog ? { backlog: true as const } : {}) };
@@ -572,32 +754,40 @@ export function hookCapturePending(base: string, name: string): boolean {
   } catch { return true; } // Unreadable evidence is pending, never an acknowledgement.
 }
 
-export async function drainHookCaptures(options: Options & { project: string; expectedScope?: string; current?: string; timeRemaining?: () => number },
+export async function drainHookCaptures(options: Options & { project: string; expectedScope?: string; current?: string; timeRemaining?: () => number; replayBudget?: HookReplayBudget },
   append: (input: CaptureInput, receipt: string) => CaptureAppend): Promise<{ captured: string[]; blocked: number }> {
+  const budget = options.replayBudget ?? hookReplayBudget();
+  if (!Number.isSafeInteger(budget.files) || budget.files < 0 || budget.files > HOOK_REPLAY_MAX_FILES
+    || !Number.isSafeInteger(budget.bytes) || budget.bytes < 0 || budget.bytes > HOOK_REPLAY_MAX_BYTES
+    || !(budget.seen instanceof Set) || budget.seen.size > HOOK_REPLAY_MAX_FILES) throw new Error("hook replay budget is invalid; create a fresh hookReplayBudget for this hook");
   const cwd = realPath(options.cwd), base = canonicalPath(options.base), stamp = hookCaptureScope(cwd, base), captured: string[] = [];
   if (belowFloor(base)) return { captured, blocked: 1 };
   if (!stamp || options.expectedScope !== undefined && options.expectedScope !== stamp) return { captured, blocked: 1 };
   // F4: the configured policy applies at drain too. `options.policy` carries it, so the anchored line below (a test diagnostic matches its exact text) stays as it was.
   options = { ...options, policy: configuredPolicyOptions(base, cwd, options.policy) };
   const policy = createStandalonePolicy(options.policy), dir = directory(base);
+  const legacyStamp = captureScope(cwd, base, false, undefined, true);
+  const accepts = (scope: string | null) => scope === stamp || legacyStamp !== undefined && scope === legacyStamp;
   const matching = (rows: ReturnType<typeof entries>, capacity: boolean) => rows.filter(row => {
-    const m = namePattern.exec(row.name); return m && m[2] === hash(cwd) && m[3] === stamp;
+    const m = namePattern.exec(row.name); return m && m[2] === hash(cwd) && accepts(m[3]!);
   }).sort((a, b) => a.modified - b.modified || a.name.localeCompare(b.name)).map(row => ({ ...row, capacity }));
   const rows = [...matching(entries(base, true), true), ...matching(entries(base), false)]
     .sort((a, b) => a.modified - b.modified || a.name.localeCompare(b.name));
-  let remaining = DRAIN_BYTES, blocked = 0;
-  for (const row of rows.slice(0, DRAIN_FILES)) {
+  const identity = (row: typeof rows[number]) => `${namePattern.exec(row.name)![1]}:${row.dev}:${row.ino}`;
+  let remaining = budget.bytes, blocked = 0;
+  for (const row of rows.filter(row => !budget.seen.has(identity(row))).slice(0, budget.files)) {
     if (options.timeRemaining && options.timeRemaining() < 8 || row.size <= RECORD_BYTES && row.size > remaining) break;
     const match = namePattern.exec(row.name)!, name = match[1]!;
+    budget.files--; budget.seen.add(identity(row));
     let file: OwnedFile | undefined;
     try {
       file = openOwned(join(row.capacity ? join(dir, ".capacity") : dir, row.name));
       if (file.initial.size !== row.size || file.initial.mtimeMs !== row.modified) { blocked++; continue; }
       const claim = claimOwned(base, row.name, file);
       if (!claim) { blocked++; continue; }
-      if (claim.initial.size <= RECORD_BYTES) remaining -= claim.initial.size;
+      if (claim.initial.size <= RECORD_BYTES) { remaining -= claim.initial.size; budget.bytes -= claim.initial.size; }
       const record = decoded(claim);
-      if (!record || record.value.cwd !== cwd || record.value.scope !== null && record.value.scope !== stamp || record.value.nonce !== match[4]) {
+      if (!record || record.value.cwd !== cwd || record.value.scope !== match[3] || record.value.nonce !== match[4]) {
         retireClaim(base, claim, false); blocked++; continue;
       }
       // #199: an unknown or newer schema stays claimed and pending (later passes reclaim it) until the TTL, then retires with a counted reason.
@@ -623,7 +813,7 @@ export async function drainHookCaptures(options: Options & { project: string; ex
         ...(c.tool === null ? {} : { tool: c.tool }), ...(c.status === null ? {} : { status: c.status }), excerpt: c.excerpt,
         ...(c.session === undefined ? {} : { session: c.session }), ...(c.subagent === undefined ? {} : { subagent: c.subagent }) };
       if (!await policy.screen(value) || !await policy.screen(input)) { retireClaim(base, claim, true); blocked++; continue; }
-      if (!owns(claim) || hookCaptureScope(cwd, base) !== stamp) { blocked++; continue; }
+      if (!owns(claim) || hookCaptureScope(cwd, base) !== stamp || value.scope === legacyStamp && captureScope(cwd, base, false, undefined, true) !== legacyStamp) { blocked++; continue; }
       append(input, hash(record.bytes));
       if (owns(claim)) { rmSync(claim.file); captured.push(name); }
       else blocked++;
@@ -632,3 +822,29 @@ export async function drainHookCaptures(options: Options & { project: string; ex
   }
   return { captured, blocked };
 }
+
+/**
+ * #217 PR2: the narrow internal surface the CLI-only replay (src/hook-spool-replay.ts) reuses, so replay keeps exactly the
+ * hook path's owned-file, decoder and claim rules. No format or ownership fork; the replay module is never imported by hooks.
+ */
+export const hookSpoolReplayInternals = {
+  namePattern, RECORD_BYTES, MAX_FILES,
+  openOwned: (file: string) => openOwned(file),
+  owns: (file: OwnedFile) => owns(file),
+  decoded: (file: OwnedFile) => decoded(file),
+  belowFloor: (base: string) => belowFloor(base),
+  /** Claim under a caller-chosen deterministic suffix (#217 decision B: hash(plan digest, publication)), never a random one. */
+  claimAs(file: OwnedFile, name: string, suffix: string): OwnedFile | undefined {
+    const match = namePattern.exec(name);
+    if (!match || !/^[a-f0-9]{24}$/.test(suffix) || !owns(file)) return undefined;
+    const claim = join(dirname(file.file), `${match[1]}.draining-${suffix}`);
+    renameSync(file.file, claim);
+    const owned = { ...file, file: claim };
+    return owns(owned) ? owned : undefined;
+  },
+  /** Remove exactly the owned claim, only while it is still the inspected inode. */
+  retireOwned(file: OwnedFile): boolean { if (!owns(file)) return false; rmSync(file.file); return true; },
+};
+export type HookSpoolOwnedFile = OwnedFile;
+/** The 0.19.0-and-older device-bound scope for this cwd, computable only for the current boot (drain accepts it too). */
+export function hookLegacyCaptureScope(cwd: string, base: string): string | undefined { return captureScope(cwd, base, false, undefined, true); }

package/src/hook-transcript.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { configuredPolicyOptions } from "./memory/config.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
-import { HookSpoolFull, stageTranscriptCapture } from "./hook-spool.ts";
+import { HookSpoolFull, stageTranscriptCapture, type PendingHookCapture } from "./hook-spool.ts";
 import { appendMetrics } from "./memory/metrics.ts";
 import type { HookTranscriptProgress } from "./hook-contract.ts";
 
@@ -14,7 +14,13 @@ export const HOOK_TRANSCRIPT_BYTES = 256 * 1024;
 const hash = (value: string) => createHash("sha256").update(value).digest("hex");
 type SummaryEvent = "Title" | "Recap" | "Compact";
 interface Cursor { offset: number; dev: string; ino: string; size: number; title: string; at: string; readStart: number; readAt: string; skipping: number }
-interface Options { cwd: string; base: string; deadline: number; policy?: StandalonePolicyOptions }
+/** `deadline` is the hard end of the scan. With `workBudgetMs`, the line loop gets that budget measured from the end of setup
+ * (policy, cursor database, read), never past `deadline` (#226 task 110: on a slow runner setup ate a fixed window). */
+interface Options { cwd: string; base: string; deadline: number; workBudgetMs?: number; policy?: StandalonePolicyOptions;
+  /** Worker-local replay opportunities; no text crosses these callbacks. */
+  onPublication?: (pending: PendingHookCapture) => Promise<void>;
+  onBackpressure?: () => Promise<boolean>;
+}
 const object = (value: unknown): Record<string, unknown> | undefined => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 const timestamp = (value: unknown) => typeof value === "string" && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : undefined;
 
@@ -127,7 +133,10 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
     const after = fstatSync(fd), live = lstatSync(value.transcript_path);
     if (length !== bytes.length || after.size < stat.size || live.dev !== stat.dev || live.ino !== stat.ino || realPath(value.transcript_path) !== transcript) return;
     let start = 0, stopReason: HookTranscriptProgress["stopReason"];
-    while (start < length && performance.now() < options.deadline) {
+    const workStart = performance.now();
+    // The caller's deadline is read live (a caller may move it); the work budget only adds an earlier end after setup.
+    const due = () => performance.now() >= options.deadline || options.workBudgetMs !== undefined && performance.now() - workStart >= options.workBudgetMs;
+    while (start < length && !due()) {
       const newline = bytes.indexOf(10, start);
       if (cursor.skipping) {
         start = newline < 0 ? length : newline + 1;
@@ -162,9 +171,16 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
               at = (db.query("SELECT at FROM fallback WHERE digest=?").get(digest) as { at: string }).at;
               if (!timestamp(at)) throw new Error("transcript cursor unavailable");
             }
-            const staged = await stageTranscriptCapture({ agent: "claude", event: summary.event, excerpt: summary.text, at, session,
-              ...(summary.subagent || typeof value.agent_id === "string" && value.agent_id.length > 0 ? { subagent: true } : {}) }, { cwd, base, policy: options.policy, deferAtCapacity: true }, summary.event === "Title" ? `title:${cursor.offset + start}` : undefined);
+            const publish = () => stageTranscriptCapture({ agent: "claude", event: summary!.event, excerpt: summary!.text, at, session,
+              ...(summary!.subagent || typeof value.agent_id === "string" && value.agent_id.length > 0 ? { subagent: true } : {}) }, { cwd, base, policy: options.policy, deferAtCapacity: true }, summary!.event === "Title" ? `title:${cursor.offset + start}` : undefined);
+            let staged: PendingHookCapture | undefined;
+            try { staged = await publish(); }
+            catch (error) {
+              if (!(error instanceof HookSpoolFull) || due() || !options.onBackpressure || !await options.onBackpressure() || due()) throw error;
+              staged = await publish(); // Same line/receipt, no second read or cursor advance on backpressure.
+            }
             if (staged && title) cursor.title = title;
+            if (staged) await options.onPublication?.(staged);
           } catch (error) {
             // Advance only through durable/refused rows; a full spool retries this line
             // after the ordinary hook worker drains earlier publications.
@@ -177,7 +193,7 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
       const at = transcriptTimestamp(line); if (at) cursor.at = at;
       start = newline + 1;
     }
-    if (!stopReason && start < length && performance.now() >= options.deadline) stopReason = "deadline";
+    if (!stopReason && start < length && due()) stopReason = "deadline";
     if (!stopReason && cursor.offset + start < stat.size && length === HOOK_TRANSCRIPT_BYTES) stopReason = "cap";
     assertFormatFloor(base, "hook-spool");
     db.query("UPDATE cursor SET offset=?,dev=?,ino=?,size=?,title=?,at=?,skipping=? WHERE id=1").run(cursor.offset + start, String(stat.dev), String(stat.ino), stat.size, cursor.title, cursor.at, cursor.skipping);