@bitkyc08/opencodex 2.65.0-preview.20260925 → 2.66.0-preview.20260925

package/src/responses/freeform-wrapper-scan.ts

@@ -19,7 +19,8 @@
 //   `raw`    no wrapper can apply, because the text is not an object or because it is one that
 //            `JSON.parse` will reject. Completion returns the buffer, so streaming it agrees.
 //   `hold`   undecided. A key that has not arrived yet can still change the answer, so nothing
-//            is published until the object parses and completion's own rule decides.
+//            is published until the object closes — where the scan itself already holds the
+//            member table completion's own rule consults, so no parse of the buffer is needed.
 //
 // The bound matters as much as the classification. A scan that walks the whole buffer on every
 // delta is quadratic in the argument size, so classification gives up after
@@ -53,7 +54,7 @@ const HOLD = -1;
 const NEVER = -2;
 
 export type FreeformWrapperScan =
-  | { kind: "hold"; parse: boolean }
+  | { kind: "hold" }
   | { kind: "raw" }
   | { kind: "input"; valueStart: number };
 
@@ -192,38 +193,36 @@ function scanValue(text: string, from: number): number {
 /**
  * Which wrapper the completed text will unwrap to, as far as this prefix can say.
  *
- * Fallback keys are deliberately not recognized here. They only unwrap when exactly one of them
- * carries a string, and a second one can still arrive, so no prefix decides them — which makes
- * them indistinguishable from any other undecided object and lets one HOLD cover both.
+ * `fallbackKeys` is the tool's alternate-field vocabulary — `freeformFallbackKeys`, the same
+ * list `unwrapFreeformToolInput` filters against. No open prefix can decide a fallback key,
+ * because it unwraps only as the SINGLE string field and a second one can still arrive; so the
+ * scan keeps a table of the members it has already walked and consults it once, at the close.
  */
-export function scanFreeformWrapper(text: string): FreeformWrapperScan {
+export function scanFreeformWrapper(text: string, fallbackKeys: readonly string[]): FreeformWrapperScan {
   // One clamp rather than a budget threaded through every helper. Every helper already holds
   // when it runs off the end of what it can see, so a buffer whose classification needs more
   // than this holds for exactly the right reason, and no scan can cost more than this many
   // characters however large the arguments grow. Indices into the clamp are indices into the
   // full text, because the clamp is a prefix of it.
-  const bounded = text.length > MAX_FREEFORM_WRAPPER_SCAN_CHARS
-    ? text.slice(0, MAX_FREEFORM_WRAPPER_SCAN_CHARS)
-    : text;
-  // `parse` is true only where this scan actually SAW the object close. Every other hold ran
-  // out of buffer or out of budget, and in both cases asking `JSON.parse` is work with no
-  // possible payoff: the first is provably incomplete, and the second would re-read a growing
-  // buffer on every delta that happens to end in a brace — repeated braces inside a long
-  // unterminated string are enough to make that quadratic. Holding a budget-exhausted prefix
-  // costs nothing that matters, because the value it would release arrives in the same instant
-  // as the authoritative completion that follows it.
-  const hold = (): FreeformWrapperScan => ({ kind: "hold", parse: false });
+  const wholeText = text.length <= MAX_FREEFORM_WRAPPER_SCAN_CHARS;
+  const bounded = wholeText ? text : text.slice(0, MAX_FREEFORM_WRAPPER_SCAN_CHARS);
+  const hold = (): FreeformWrapperScan => ({ kind: "hold" });
   const open = skipWhitespace(bounded, 0);
   if (open === HOLD) return hold();
   // Not an object, so no wrapper rule reaches it: arrays, scalars and ordinary bodies all
   // complete as themselves.
   if (bounded[open] !== "{") return { kind: "raw" };
 
+  // Every top-level member is recorded as the scan passes it, last occurrence winning — the
+  // keep-last rule `JSON.parse` applies to duplicate keys. When the object closes, this table
+  // answers the only question completion asks of it — which members carried strings — so the
+  // closed object classifies directly instead of reparsing a buffer the scan just walked.
+  const members = new Map<string, { stringValue: boolean; valueStart: number }>();
   let i = open + 1;
   for (;;) {
     const at = skipWhitespace(bounded, i);
     if (at === HOLD) return hold();
-    if (bounded[at] === "}") return afterTopLevelClose(bounded, at + 1);
+    if (bounded[at] === "}") return afterTopLevelClose(bounded, at + 1, members, fallbackKeys, wholeText);
     if (bounded[at] !== '"') return { kind: "raw" };
 
     const nameEnd = scanString(bounded, at);
@@ -254,6 +253,7 @@ export function scanFreeformWrapper(text: string): FreeformWrapperScan {
         : { kind: "raw" };
     }
 
+    members.set(name, { stringValue: bounded[valueAt] === '"', valueStart: valueAt + 1 });
     const valueEnd = scanValue(bounded, valueAt);
     if (valueEnd === HOLD) return hold();
     if (valueEnd === NEVER) return { kind: "raw" };
@@ -261,19 +261,46 @@ export function scanFreeformWrapper(text: string): FreeformWrapperScan {
     const next = skipWhitespace(bounded, valueEnd);
     if (next === HOLD) return hold();
     if (bounded[next] === ",") {
-      i = next + 1;
+      // A comma promises another member, so the next non-whitespace character must open a
+      // member name. `{"code":"cmd",}` is not a completed object — `JSON.parse` rejects the
+      // trailing comma — and treating its `}` as the close would unwrap a preview completion
+      // hands back unchanged. Nested members already reject this through `scanMemberKey`;
+      // the top level has to ask the same question itself.
+      const member = skipWhitespace(bounded, next + 1);
+      if (member === HOLD) return hold();
+      if (bounded[member] !== '"') return { kind: "raw" };
+      i = member;
       continue;
     }
-    if (bounded[next] === "}") return afterTopLevelClose(bounded, next + 1);
+    if (bounded[next] === "}") return afterTopLevelClose(bounded, next + 1, members, fallbackKeys, wholeText);
     return { kind: "raw" };
   }
 }
 
 /**
  * The object closed without a canonical key. Only whitespace may follow one that parses, so
- * anything else makes the text raw; otherwise the completed parse decides between a fallback
- * wrapper and no wrapper at all.
+ * anything else makes the text raw. Whitespace to the end IS legal, but the member table
+ * already says which way completion goes on it: exactly one string-valued fallback field is
+ * the wrapper's value, and any other member shape streams the raw text — byte-exact through
+ * whatever trailing whitespace arrived, where a reparsed growing buffer was quadratic work on
+ * every whitespace delta and a held one swallowed the whitespace bytes entirely.
  */
-function afterTopLevelClose(text: string, from: number): FreeformWrapperScan {
-  return skipWhitespace(text, from) === HOLD ? { kind: "hold", parse: true } : { kind: "raw" };
+function afterTopLevelClose(
+  text: string,
+  from: number,
+  members: ReadonlyMap<string, { stringValue: boolean; valueStart: number }>,
+  fallbackKeys: readonly string[],
+  wholeText: boolean,
+): FreeformWrapperScan {
+  const trailing = skipWhitespace(text, from);
+  if (trailing !== HOLD) return { kind: "raw" };
+  // A clamped prefix ends inside this whitespace, so what follows is unseen: hold rather than
+  // guess at a tail that could still invalidate the close. When the whole text fit, the object
+  // plus its trailing whitespace is complete — and its members decide it without a parse.
+  if (!wholeText) return { kind: "hold" };
+  const candidates = fallbackKeys.filter(key => members.get(key)?.stringValue === true);
+  if (candidates.length === 1) {
+    return { kind: "input", valueStart: members.get(candidates[0]!)!.valueStart };
+  }
+  return { kind: "raw" };
 }

package/src/responses/progressive-freeform-input.ts

@@ -1,4 +1,4 @@
-import { unwrapFreeformToolInput } from "./apply-patch-envelope";
+import { freeformFallbackKeys } from "./apply-patch-envelope";
 import { JSON_ESCAPES, scanFreeformWrapper } from "./freeform-wrapper-scan";
 
 /**
@@ -92,11 +92,12 @@ function decodeJsonStringPrefix(body: string): string | null {
  * damage is what is available without giving up progressive streaming, and the args are
  * unusable in that case whichever representation wins.
  *
- * A fallback key is not decidable. It only unwraps when it is the SINGLE string field, and a
- * second key can still arrive — so a value emitted early would have to be taken back. That is
- * the rewind this holds instead: stream nothing until the object closes, then publish the one
- * repaired body. The routed passthrough in `responses-custom-tool-repair.ts` already holds
- * any object prefix for the same reason (#5047).
+ * A fallback key decides only at the object's close. It unwraps as the SINGLE string field,
+ * and a second key can still arrive while the object is open — so a value emitted early would
+ * have to be taken back. The scan therefore keeps a member table and consults it at the
+ * close, publishing the wrapped value (or the raw text) without ever reparsing the buffer.
+ * The routed passthrough in `responses-custom-tool-repair.ts` already holds any object prefix
+ * for the same reason (#5047).
  *
  * An object that has not reached a canonical key YET is in exactly that position, and used to
  * be treated as raw because it did not match the literal `{"input":"`. It holds now: `input`
@@ -106,7 +107,7 @@ function decodeJsonStringPrefix(body: string): string | null {
  * not holding was publishing bytes the completed item removes.
  */
 export function progressiveFreeformInput(args: string, toolName: string): string | null {
-  const scan = scanFreeformWrapper(args);
+  const scan = scanFreeformWrapper(args, freeformFallbackKeys(toolName));
   if (scan.kind === "input") {
     const decoded = decodeJsonStringPrefix(args.slice(scan.valueStart));
     if (decoded === null) return null;
@@ -114,17 +115,10 @@ export function progressiveFreeformInput(args: string, toolName: string): string
   }
   if (scan.kind === "raw") return mayBecomeFencedBody(args, toolName) ? null : args;
 
-  // Undecided: some wrapper may still apply, and only the completed object says which one.
-  // The parse runs exactly where the scan SAW the object close, so it reads a buffer the scan
-  // already walked and its cost is bounded by the same clamp. A hold from either limit stays
-  // held: an incomplete object has nothing to parse, and re-reading a budget-exhausted buffer
-  // on every delta is quadratic work for a delta that would arrive in the same instant as the
-  // authoritative completion behind it.
-  if (!scan.parse) return null;
-  try {
-    JSON.parse(args);
-  } catch {
-    return null;
-  }
-  return unwrapFreeformToolInput(args, toolName);
+  // Undecided: an incomplete object, or a close whose tail is clamped out of view. Both stay
+  // held — the first is provably incomplete, and re-walking a budget-exhausted buffer on every
+  // delta is work for a preview that arrives in the same instant as the authoritative
+  // completion behind it. A closed object the scan could see whole never reaches here: its
+  // member table already resolved it to `input` or `raw`.
+  return null;
 }

package/src/responses/spill-store.ts

@@ -13,6 +13,7 @@ import {
   readFileSync,
   unlinkSync,
   writeSync,
+  type Stats,
 } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
@@ -34,6 +35,20 @@ export const RESPONSE_SPILL_DIR_NAME = "responses-state-spill";
 export const RESPONSE_SPILL_ORPHAN_GRACE_MS = 15 * 60_000;
 export const RESPONSE_SPILL_SCAN_MAX = 4_096;
 export const RESPONSE_SPILL_CLEANUP_MAX = 512;
+// The liveness-tick sweep runs synchronously on the serving event loop every
+// 60 s, so it gets a tighter bound than the startup pass that blocks one call.
+export const PERIODIC_SPILL_SWEEP_OPTS = {
+  scanMax: 512,
+  cleanupMax: 64,
+  deadlineMs: 25,
+} as const;
+
+/** Open directory iterator the next liveness-tick sweep resumes from; null
+ *  after a full pass, an iteration error, or a directory change. Holding the
+ *  real iterator (instead of an offset re-skipped from a fresh opendir) keeps
+ *  each tick's cost bounded by its own budget, so a slow enumeration cannot
+ *  pin the cursor at the same prefix forever. */
+let periodicSweepCursor: { dir: string; scan: SpillDirScan } | null = null;
 
 const RESPONSE_SPILL_PUBLISH_RETRIES = 64;
 const OWNED_SPILL_NAME = /^([A-Za-z0-9._-]{1,80})\.([0-9a-f]{12})\.([0-9a-f]{24})\.(\d+)\.(\d+)\.spill\.json$/;
@@ -95,6 +110,8 @@ export interface ResponseSpillCleanupResult {
   removed: number;
   failed: number;
   bytesRemoved: number;
+  /** The scan reached the end of the directory. */
+  exhausted?: boolean;
 }
 
 export interface ResponseSpillIoForTest {
@@ -750,53 +767,153 @@ export function deleteResponseSpill(ref: ResponseSpillRef): void {
   } catch { /* best effort */ }
 }
 
-export function recoverOrphanedResponseSpills(
-  referencedFileNames: ReadonlySet<string>,
-  dir = responseSpillDirectory(),
-  opts?: { graceMs?: number },
-): ResponseSpillCleanupResult {
-  const result: ResponseSpillCleanupResult = { scanned: 0, removed: 0, failed: 0, bytesRemoved: 0 };
-  const graceMs = opts?.graceMs ?? RESPONSE_SPILL_ORPHAN_GRACE_MS;
-  // ONE loop serves both the real directory handle and the injected test seam
-  // (review C2-2: two duplicated loops let the test prove only its own copy).
-  // The reader is called strictly AFTER the scan-cap check, so entry
-  // SCAN_MAX+1 is never requested from either source.
+type SpillDirNameKind = "spill" | "temp";
+
+/** Directory-iteration plumbing shared by reclaim and the dry-run inspector.
+ *  ONE loop serves both the real directory handle and the injected test seam
+ *  (review C2-2: two duplicated loops let the test prove only its own copy).
+ *  Callers must request the next name strictly AFTER their scan-cap check, so
+ *  entry SCAN_MAX+1 is never requested from either source. */
+interface SpillDirScan { nextName: () => string | null; close: () => void }
+
+function openSpillDirScan(dir: string): SpillDirScan | null {
   let handle: ReturnType<typeof opendirSync> | null = null;
   const injected = spillIoForTest?.readdirEntry;
   if (!injected) {
-    try { handle = opendirSync(dir); } catch { return result; }
+    try { handle = opendirSync(dir); } catch { return null; }
   }
-  const nextName = (): string | null => {
-    if (injected) return injected();
-    const entry = handle!.readSync();
-    return entry ? entry.name : null;
+  return {
+    nextName: () => {
+      if (injected) return injected();
+      const entry = handle!.readSync();
+      return entry ? entry.name : null;
+    },
+    close: () => { try { handle?.closeSync(); } catch { /* best effort */ } },
+  };
+}
+
+/** Orphan predicate, name half: a spill-shaped name nobody references. Shared by
+ *  reclaim and the dry-run inspector so the report and the unlink cannot disagree. */
+function orphanSpillNameKind(name: string, referencedFileNames: ReadonlySet<string>): SpillDirNameKind | null {
+  if (referencedFileNames.has(name)) return null;
+  if (OWNED_SPILL_NAME.test(name)) return "spill";
+  if (OWNED_SPILL_TEMP_NAME.test(name)) return "temp";
+  return null;
+}
+
+/** Orphan predicate, stat half: a regular file (never a symlink) past the grace window. */
+function spillEntryPastGrace(stat: Stats, graceMs: number): boolean {
+  return stat.isFile() && !stat.isSymbolicLink() && Date.now() - stat.mtimeMs >= graceMs;
+}
+
+export interface ResponseSpillDirInspection {
+  scanned: number;
+  /** The walk stopped at RESPONSE_SPILL_SCAN_MAX, so every count describes a
+   *  prefix of the directory and the real totals are higher. */
+  truncated: boolean;
+  /** Every regular file present, spill-shaped or not — the honest disk total. */
+  files: number;
+  bytes: number;
+  /** Regular files named in the caller's referenced set. */
+  ownedFiles: number;
+  ownedBytes: number;
+  /** Spill/temp-shaped regular files unreferenced and past the orphan grace. */
+  orphanFiles: number;
+  orphanBytes: number;
+}
+
+/**
+ * Dry-run counterpart of recoverOrphanedResponseSpills: same directory walk and
+ * the same orphan predicate, but it counts and never unlinks. It stats every
+ * entry (bounded by RESPONSE_SPILL_SCAN_MAX) because `bytes` is the disk total
+ * an operator sizes the directory by — reclaim only stats orphan candidates.
+ */
+export function inspectResponseSpillDir(
+  referencedFileNames: ReadonlySet<string>,
+  dir = responseSpillDirectory(),
+  opts?: { graceMs?: number },
+): ResponseSpillDirInspection {
+  const result: ResponseSpillDirInspection = {
+    scanned: 0, truncated: false, files: 0, bytes: 0,
+    ownedFiles: 0, ownedBytes: 0, orphanFiles: 0, orphanBytes: 0,
   };
+  const graceMs = opts?.graceMs ?? RESPONSE_SPILL_ORPHAN_GRACE_MS;
+  const scan = openSpillDirScan(dir);
+  if (!scan) return result;
   try {
     while (result.scanned < RESPONSE_SPILL_SCAN_MAX) {
-      const name = nextName();
+      const name = scan.nextName();
       if (name === null) break;
       result.scanned += 1;
-      if (result.removed + result.failed >= RESPONSE_SPILL_CLEANUP_MAX) break;
-      const spillMatch = OWNED_SPILL_NAME.exec(name);
-      const isOwnedTemp = OWNED_SPILL_TEMP_NAME.test(name);
-      if ((!spillMatch && !isOwnedTemp) || referencedFileNames.has(name)) continue;
       const path = join(dir, name);
-      let stat: ReturnType<typeof lstatSync>;
+      let stat: Stats;
       try { stat = lstatSync(path); } catch { continue; }
-      if (!stat.isFile() || stat.isSymbolicLink() || Date.now() - stat.mtimeMs < graceMs) continue;
-      try {
-        // Orphaned publish temps get the full ephemeral release; stable
-        // orphaned spills keep destination-keyed timeout memos.
-        if (isOwnedTemp) unlinkEphemeral(path);
-        else unlink(path);
-        result.removed += 1;
-        result.bytesRemoved += stat.size;
-      } catch {
-        result.failed += 1;
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      result.files += 1;
+      result.bytes += stat.size;
+      if (referencedFileNames.has(name)) {
+        result.ownedFiles += 1;
+        result.ownedBytes += stat.size;
+      } else if (orphanSpillNameKind(name, referencedFileNames) !== null && spillEntryPastGrace(stat, graceMs)) {
+        result.orphanFiles += 1;
+        result.orphanBytes += stat.size;
       }
     }
   } finally {
-    try { handle?.closeSync(); } catch { /* best effort */ }
+    scan.close();
+  }
+  result.truncated = result.scanned >= RESPONSE_SPILL_SCAN_MAX;
+  return result;
+}
+
+export function recoverOrphanedResponseSpills(
+  referencedFileNames: ReadonlySet<string>,
+  dir = responseSpillDirectory(),
+  opts?: { graceMs?: number; scanMax?: number; cleanupMax?: number; deadlineMs?: number },
+): ResponseSpillCleanupResult {
+  const scan = openSpillDirScan(dir);
+  if (!scan) return { scanned: 0, removed: 0, failed: 0, bytesRemoved: 0 };
+  try {
+    return reclaimFromSpillDirScan(scan, referencedFileNames, dir, opts);
+  } finally {
+    scan.close();
+  }
+}
+
+/** Reclaim loop over an already-open scan. It never reads a name it will not
+ *  process, so a caller that keeps the scan open resumes at the first entry the
+ *  previous call left untouched. Throws only if the iterator itself throws. */
+function reclaimFromSpillDirScan(
+  scan: SpillDirScan,
+  referencedFileNames: ReadonlySet<string>,
+  dir: string,
+  opts?: { graceMs?: number; scanMax?: number; cleanupMax?: number; deadlineMs?: number },
+): ResponseSpillCleanupResult {
+  const result: ResponseSpillCleanupResult = { scanned: 0, removed: 0, failed: 0, bytesRemoved: 0 };
+  const graceMs = opts?.graceMs ?? RESPONSE_SPILL_ORPHAN_GRACE_MS;
+  const scanMax = opts?.scanMax ?? RESPONSE_SPILL_SCAN_MAX;
+  const cleanupMax = opts?.cleanupMax ?? RESPONSE_SPILL_CLEANUP_MAX;
+  const deadline = opts?.deadlineMs === undefined ? Infinity : Date.now() + opts.deadlineMs;
+  while (result.scanned < scanMax && result.removed + result.failed < cleanupMax && Date.now() < deadline) {
+    const name = scan.nextName();
+    if (name === null) { result.exhausted = true; break; }
+    result.scanned += 1;
+    const orphanKind = orphanSpillNameKind(name, referencedFileNames);
+    if (orphanKind === null) continue;
+    const path = join(dir, name);
+    let stat: Stats;
+    try { stat = lstatSync(path); } catch { continue; }
+    if (!spillEntryPastGrace(stat, graceMs)) continue;
+    try {
+      // Orphaned publish temps get the full ephemeral release; stable
+      // orphaned spills keep destination-keyed timeout memos.
+      if (orphanKind === "temp") unlinkEphemeral(path);
+      else unlink(path);
+      result.removed += 1;
+      result.bytesRemoved += stat.size;
+    } catch {
+      result.failed += 1;
+    }
   }
   return result;
 }
@@ -804,3 +921,40 @@ export function recoverOrphanedResponseSpills(
 export function responseSpillExistsForTests(ref: ResponseSpillRef): boolean {
   return validSpillRef(ref) && existsSync(join(responseSpillDirectory(), ref.fileName));
 }
+
+/**
+ * Bounded liveness-tick reclaim that resumes where the previous tick stopped,
+ * so orphans behind the first `scanMax` owned entries are still reached. The
+ * directory iterator stays open between ticks; it is dropped at end of
+ * directory, on an iteration error, or when the spill directory changes.
+ */
+export function sweepOrphanedResponseSpillsPeriodically(
+  referencedFileNames: ReadonlySet<string>,
+  dir = responseSpillDirectory(),
+): ResponseSpillCleanupResult {
+  if (periodicSweepCursor && periodicSweepCursor.dir !== dir) closePeriodicSweepCursor();
+  if (!periodicSweepCursor) {
+    const scan = openSpillDirScan(dir);
+    if (!scan) return { scanned: 0, removed: 0, failed: 0, bytesRemoved: 0 };
+    periodicSweepCursor = { dir, scan };
+  }
+  let result: ResponseSpillCleanupResult;
+  try {
+    result = reclaimFromSpillDirScan(periodicSweepCursor.scan, referencedFileNames, dir, PERIODIC_SPILL_SWEEP_OPTS);
+  } catch {
+    closePeriodicSweepCursor();
+    return { scanned: 0, removed: 0, failed: 0, bytesRemoved: 0 };
+  }
+  // A full pass restarts from a fresh listing so files created mid-pass are seen.
+  if (result.exhausted) closePeriodicSweepCursor();
+  return result;
+}
+
+function closePeriodicSweepCursor(): void {
+  periodicSweepCursor?.scan.close();
+  periodicSweepCursor = null;
+}
+
+export function resetPeriodicSpillSweepCursorForTests(): void {
+  closePeriodicSweepCursor();
+}

package/src/responses/state/snapshot-select.ts

@@ -0,0 +1,49 @@
+import type { StoredResponseState } from "../state";
+
+/**
+ * Pick the snapshot entries that fit the byte budgets, in `states` order.
+ *
+ * Bounded stubs and tombstones are selected before residents: they are the
+ * only durable references a spill file has, and demotion is oldest-first, so a
+ * single newest-first pass would let resident payloads consume the whole
+ * budget ahead of them. Residents then fill what remains, newest-first so the
+ * most recent chains survive both legacy snapshot caps.
+ */
+export function selectSnapshotEntries(
+  states: ReadonlyMap<string, StoredResponseState>,
+  totalMaxBytes: number,
+  residentEntryMaxBytes: number,
+): Array<[string, unknown]> {
+  const ordered = [...states].reverse();
+  const persisted = new Map<string, [string, unknown]>();
+  let total = 0;
+  // UTF-8 bytes, not UTF-16 code units: multibyte items otherwise slip past
+  // both snapshot caps at up to 2x the intended size.
+  const sizeOf = (entry: [string, unknown]): number => Buffer.byteLength(JSON.stringify(entry), "utf8");
+  for (const [id, state] of ordered) {
+    if (state.kind === "resident") continue;
+    const { sizeBytes: _sizeBytes, ...smallState } = state;
+    const entry: [string, unknown] = [id, smallState];
+    const size = sizeOf(entry);
+    if (total + size > totalMaxBytes) continue;
+    total += size;
+    persisted.set(id, entry);
+  }
+  for (const [id, state] of ordered) {
+    if (state.kind !== "resident") continue;
+    const { sizeBytes: _sizeBytes, kind: _kind, ...resident } = state;
+    const entry: [string, unknown] = [id, resident];
+    const size = sizeOf(entry);
+    if (size > residentEntryMaxBytes) continue;
+    if (total + size > totalMaxBytes) break;
+    total += size;
+    persisted.set(id, entry);
+  }
+  // Emit in map order so reload and count eviction keep the same relative order as `states`.
+  const entries: Array<[string, unknown]> = [];
+  for (const [id] of states) {
+    const kept = persisted.get(id);
+    if (kept) entries.push(kept);
+  }
+  return entries;
+}

package/src/responses/state/spill-inspect.ts

@@ -0,0 +1,46 @@
+import { readFileSync, statSync } from "node:fs";
+import type { ResponseSpillRef } from "../spill-store";
+import type { StoredResponseState } from "../state";
+
+/**
+ * File names still owned by the in-memory store: live "spill" stubs plus
+ * superseded generations queued for unlink only after a durable snapshot
+ * (pendingSpillUnlinks — see replaceSpillEntryAtomically in state.ts).
+ */
+export function collectReferencedSpillFileNames(
+  states: Iterable<StoredResponseState>,
+  pendingUnlinks: Iterable<ResponseSpillRef>,
+): Set<string> {
+  const referenced = new Set<string>();
+  for (const state of states) {
+    if (state.kind === "spill") referenced.add(state.spill.fileName);
+  }
+  for (const ref of pendingUnlinks) referenced.add(ref.fileName);
+  return referenced;
+}
+
+/**
+ * File names a restart would re-own: "spill" stubs inside the persisted
+ * snapshot. This is the only ownership evidence a separate process (ocx
+ * doctor) can see, and it stays authoritative in-process too — a restart
+ * reloads the snapshot before the store drops anything from it.
+ */
+export function snapshotReferencedSpillFileNames(path: string, maxBytes: number): Set<string> {
+  const referenced = new Set<string>();
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size > maxBytes) return referenced;
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as { version?: unknown; states?: unknown };
+    if ((raw.version !== 1 && raw.version !== 2) || !Array.isArray(raw.states)) return referenced;
+    for (const entry of raw.states) {
+      if (!Array.isArray(entry) || entry.length !== 2) continue;
+      const value = entry[1] as { kind?: unknown; spill?: { fileName?: unknown } };
+      if (value?.kind === "spill" && typeof value.spill?.fileName === "string") {
+        referenced.add(value.spill.fileName);
+      }
+    }
+  } catch {
+    /* missing or corrupt snapshot: nothing is referenced */
+  }
+  return referenced;
+}

package/src/responses/state/spill-queue.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { basename } from "node:path";
 import {
   cleanupSupersededResponseSpillPublication,
   createResponseSpillPublicationControl,
@@ -658,6 +659,21 @@ export function spillQueueSupersededSpillFor(id: string): ResponseSpillRef | und
   return pendingResponseSpillById.get(id)?.supersededSpill;
 }
 
+/**
+ * File names an orphan sweep must keep: each queued job's superseded generation,
+ * its in-flight temp, and its destination — all still owned but not yet named by
+ * `states` or `pendingSpillUnlinks`.
+ */
+export function spillQueueReferencedSpillFileNames(): Set<string> {
+  const names = new Set<string>();
+  for (const job of pendingResponseSpills) {
+    if (job.supersededSpill) names.add(job.supersededSpill.fileName);
+    if (job.publicationControl.tempPath) names.add(basename(job.publicationControl.tempPath));
+    if (job.publicationControl.destinationPath) names.add(basename(job.publicationControl.destinationPath));
+  }
+  return names;
+}
+
 /** Test-only: release queued jobs and zero the queue-owned byte accounting. */
 export function resetSpillQueueForTests(): void {
   for (const id of [...pendingResponseSpillById.keys()]) cancelPendingResponseSpill(id);