@remnic/core 9.69.46 → 9.69.48

package/src/memory-browse.ts

@@ -0,0 +1,316 @@
+/**
+ * Memory-store browse verbs (issue #2978) — deterministic `ls` / `tree` /
+ * `find` over ONE resolved namespace's memory store, so an agent can see
+ * what exists instead of guessing ids at an opaque search box.
+ *
+ * Scope rules (all existing contracts, no new ones):
+ *   - Every call resolves through the caller's `resolveReadableNamespace`
+ *     (read/write path symmetry) and ONE storage instance — browse never
+ *     enumerates across namespaces.
+ *   - Only the recall corpus is browsable: a path's top segment must be a
+ *     `RECALL_FALLBACK_DIRS` category AND survive
+ *     `isGenericRecallExcludedPath`. Derived stores (`artifacts/`,
+ *     `meetings/` records, wearables day stores, `state/`, ...) are
+ *     indistinguishable from missing paths — `not_found`, never listed.
+ *   - Support-passport private memories are filtered exactly like
+ *     `memoryBrowse` (the paginated list): their names never appear.
+ *   - Output is deterministically sorted (plain code-point order, no
+ *     locale) and entry-capped so a huge store cannot blow the response.
+ *
+ * `ponytail:` the index is rebuilt from `readAllMemories()` per call —
+ * O(corpus) per browse. Fine at agent cadence; swap for a cached directory
+ * index if browsing ever sits on a hot path.
+ */
+
+import { toMemoryPathRel } from "./memory-lifecycle-ledger-utils.js";
+import { normalizeProjectionPreview } from "./memory-projection-format.js";
+import { isGenericRecallExcludedPath } from "./orchestration/generic-recall-paths.js";
+import { isSupportPassportPrivateMemory } from "./support-passport/card-projection.js";
+import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+import type { MemoryFile } from "./types.js";
+
+/** Browse reads touch only these storage members. */
+export interface MemoryBrowseStorage {
+  readonly dir: string;
+  readAllMemories(): Promise<MemoryFile[]>;
+}
+
+/** Injected seams; the service supplies live wiring, tests supply doubles. */
+export interface MemoryBrowseDeps {
+  readonly resolveReadableNamespace: (namespace: string | undefined, principal?: string) => string;
+  readonly getStorage: (namespace: string) => Promise<MemoryBrowseStorage>;
+}
+
+export type BrowseVerb = "ls" | "tree" | "find";
+
+export interface MemoryStoreBrowseRequest {
+  readonly verb: BrowseVerb;
+  /** ls/tree: directory relative to the store root ("" or "/" = root). */
+  readonly path?: string;
+  /** tree: expansion depth, 1..MAX_TREE_DEPTH (default 1). */
+  readonly depth?: number;
+  /** find: glob (`*` wildcard) or substring matched against path and name. */
+  readonly pattern?: string;
+  readonly namespace?: string;
+  readonly authenticatedPrincipal?: string;
+}
+
+export interface MemoryBrowseEntry {
+  /** Store-relative path with forward slashes; dirs carry no trailing slash. */
+  readonly path: string;
+  readonly kind: "dir" | "file";
+  readonly name: string;
+  /** Files: first content line (180-char preview). Dirs: empty. */
+  readonly description: string;
+  /** Dirs: recursive memory count beneath. Files: 1. */
+  readonly count: number;
+  /** 0-based depth relative to the browse root (tree nests; ls/find are 0). */
+  readonly depth: number;
+}
+
+export type MemoryBrowseError = "invalid_path" | "not_found" | "invalid_depth" | "invalid_pattern";
+
+export type MemoryStoreBrowseResult =
+  | {
+      ok: true;
+      verb: BrowseVerb;
+      namespace: string;
+      path: string;
+      total: number;
+      entries: MemoryBrowseEntry[];
+      truncated: boolean;
+      rendered: string;
+    }
+  | {
+      ok: false;
+      verb: BrowseVerb;
+      path: string;
+      error: MemoryBrowseError;
+      message: string;
+      rendered: string;
+    };
+
+export const MAX_LS_ENTRIES = 200;
+export const MAX_TREE_ENTRIES = 400;
+export const MAX_TREE_DEPTH = 4;
+export const MAX_FIND_ENTRIES = 200;
+const MAX_PATH_CHARS = 512;
+const MAX_PATTERN_CHARS = 256;
+
+const BROWSABLE_ROOTS: Record<string, true> = Object.fromEntries(RECALL_FALLBACK_DIRS.map((dir) => [dir, true]));
+
+/** The recall-corpus visibility rule shared by every browse code path. */
+function isBrowsableMemoryPath(relPath: string): boolean {
+  if (!relPath.endsWith(".md")) return false;
+  const top = relPath.split("/")[0] ?? "";
+  return BROWSABLE_ROOTS[top] === true && !isGenericRecallExcludedPath(relPath);
+}
+
+/**
+ * Normalize a caller-supplied store path. Returns "" for the root. Throws
+ * `Error` on absolute paths, `..`/`.` segments, backslashes, control
+ * characters, or oversize input — never reinterpreted (pattern 39).
+ */
+export function sanitizeBrowsePath(raw: string | undefined): string {
+  const trimmed = (raw ?? "").trim();
+  if (trimmed === "" || trimmed === "/") return "";
+  if (trimmed.length > MAX_PATH_CHARS) throw new Error("path is too long");
+  if (trimmed.includes("\\")) throw new Error("path must use '/' separators");
+  const segments = trimmed.split("/");
+  for (const segment of segments) {
+    if (segment === "") throw new Error("path has an empty segment");
+    if (segment === "." || segment === "..") throw new Error("path must not contain '.' or '..' segments");
+    for (const ch of segment) {
+      const code = ch.charCodeAt(0);
+      if (code < 0x20 || code === 0x7f) throw new Error("path has control characters");
+    }
+  }
+  return segments.join("/");
+}
+
+/** Escape every regex metacharacter in a glob segment. */
+function segmentRegex(segment: string): RegExp {
+  const source = `^${segment.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`;
+  return new RegExp(source, "i");
+}
+
+/**
+ * `*` glob (one segment per pattern segment, `find -name` semantics — `*`
+ * never crosses `/`) or case-insensitive substring over path and name.
+ */
+export function browsePatternMatches(pattern: string, relPath: string): boolean {
+  const segments = relPath.split("/");
+  const name = segments[segments.length - 1] ?? "";
+  const patternSegments = pattern.split("/");
+  if (patternSegments.length === 1) {
+    const single = patternSegments[0]!;
+    if (single.includes("*")) return segmentRegex(single).test(name);
+    const needle = single.toLowerCase();
+    return relPath.toLowerCase().includes(needle) || name.toLowerCase().includes(needle);
+  }
+  if (patternSegments.length !== segments.length) return false;
+  return patternSegments.every((segment, index) => segmentRegex(segment).test(segments[index]!));
+}
+
+interface DirNode {
+  readonly subdirs: Map<string, DirNode>;
+  readonly files: Map<string, MemoryFile>;
+  count: number;
+}
+
+function emptyNode(): DirNode {
+  return { subdirs: new Map(), files: new Map(), count: 0 };
+}
+
+/** Directory index over the browsable corpus: root "" holds category dirs. */
+function buildIndex(memories: readonly MemoryFile[], dir: string): DirNode {
+  const root = emptyNode();
+  for (const memory of memories) {
+    const rel = toMemoryPathRel(dir, memory.path);
+    if (!isBrowsableMemoryPath(rel)) continue;
+    const segments = rel.split("/");
+    let node = root;
+    node.count += 1;
+    for (let index = 0; index < segments.length - 1; index += 1) {
+      const name = segments[index]!;
+      let child = node.subdirs.get(name);
+      if (child === undefined) {
+        child = emptyNode();
+        node.subdirs.set(name, child);
+      }
+      node = child;
+      node.count += 1;
+    }
+    node.files.set(segments[segments.length - 1]!, memory);
+  }
+  return root;
+}
+
+function byPath(left: { path: string }, right: { path: string }): number {
+  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+
+function dirEntries(node: DirNode, dirPath: string): MemoryBrowseEntry[] {
+  const prefix = dirPath === "" ? "" : `${dirPath}/`;
+  const entries: MemoryBrowseEntry[] = [];
+  for (const [name, child] of node.subdirs) {
+    entries.push({ path: `${prefix}${name}`, kind: "dir", name, description: "", count: child.count, depth: 0 });
+  }
+  for (const [name, memory] of node.files) {
+    entries.push({
+      path: `${prefix}${name}`,
+      kind: "file",
+      name,
+      description: normalizeProjectionPreview(memory.content),
+      count: 1,
+      depth: 0,
+    });
+  }
+  return entries.sort(byPath);
+}
+
+function renderEntries(verb: BrowseVerb, namespace: string, browsePath: string, entries: readonly MemoryBrowseEntry[]): string {
+  const lines = [`${verb} ${namespace}:${browsePath === "" ? "/" : browsePath}`];
+  for (const entry of entries) {
+    const indent = "  ".repeat(entry.depth);
+    if (entry.kind === "dir") {
+      lines.push(`${indent}${entry.path}/ (${entry.count} memories)`);
+    } else {
+      const description = entry.description.length > 0 ? ` — ${entry.description}` : "";
+      lines.push(`${indent}${entry.path}${description}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function refusal(verb: BrowseVerb, browsePath: string, error: MemoryBrowseError, message: string): MemoryStoreBrowseResult {
+  return { ok: false, verb, path: browsePath, error, message, rendered: `browse ${verb} failed: ${error} — ${message}` };
+}
+
+/** Run one browse verb. Malformed input throws `Error`; typed refusals return in-band. */
+export async function runMemoryBrowse(
+  deps: MemoryBrowseDeps,
+  request: MemoryStoreBrowseRequest,
+): Promise<MemoryStoreBrowseResult> {
+  const namespace = deps.resolveReadableNamespace(request.namespace, request.authenticatedPrincipal);
+  const storage = await deps.getStorage(namespace);
+  const memories = (await storage.readAllMemories()).filter((memory) => !isSupportPassportPrivateMemory(memory));
+
+  if (request.verb === "find") {
+    const pattern = (request.pattern ?? "").trim();
+    if (pattern.length === 0) return refusal(request.verb, "", "invalid_pattern", "pattern is required");
+    if (pattern.length > MAX_PATTERN_CHARS) {
+      return refusal(request.verb, "", "invalid_pattern", "pattern is too long");
+    }
+    const hits: MemoryBrowseEntry[] = [];
+    let truncated = false;
+    let total = 0;
+    for (const memory of memories) {
+      const rel = toMemoryPathRel(storage.dir, memory.path);
+      if (!isBrowsableMemoryPath(rel)) continue;
+      if (!browsePatternMatches(pattern, rel)) continue;
+      total += 1;
+      if (hits.length >= MAX_FIND_ENTRIES) {
+        truncated = true;
+        break;
+      }
+      hits.push({
+        path: rel,
+        kind: "file",
+        name: rel.split("/").pop() ?? rel,
+        description: normalizeProjectionPreview(memory.content),
+        count: 1,
+        depth: 0,
+      });
+    }
+    hits.sort(byPath);
+    return { ok: true, verb: "find", namespace, path: "", total, entries: hits, truncated, rendered: renderEntries("find", namespace, "", hits) };
+  }
+
+  let browsePath: string;
+  try {
+    browsePath = sanitizeBrowsePath(request.path);
+  } catch (err) {
+    return refusal(request.verb, request.path ?? "", "invalid_path", err instanceof Error ? err.message : String(err));
+  }
+  const root = buildIndex(memories, storage.dir);
+  let node: DirNode | undefined = root;
+  for (const segment of browsePath === "" ? [] : browsePath.split("/")) {
+    node = node?.subdirs.get(segment);
+    if (node === undefined) break;
+  }
+  // Invisible-by-design stores resolve as not_found, indistinguishable from
+  // a missing path: the index only ever contains browsable corpus paths.
+  if (node === undefined) {
+    return refusal(request.verb, browsePath, "not_found", `no browsable store path: ${browsePath}`);
+  }
+
+  if (request.verb === "ls") {
+    const all = dirEntries(node, browsePath);
+    const truncated = all.length > MAX_LS_ENTRIES;
+    const entries = all.slice(0, MAX_LS_ENTRIES);
+    return { ok: true, verb: "ls", namespace, path: browsePath, total: all.length, entries, truncated, rendered: renderEntries("ls", namespace, browsePath, entries) };
+  }
+
+  if (request.depth !== undefined && (!Number.isInteger(request.depth) || request.depth < 1 || request.depth > MAX_TREE_DEPTH)) {
+    return refusal(request.verb, browsePath, "invalid_depth", `depth must be an integer between 1 and ${MAX_TREE_DEPTH}`);
+  }
+  const depth = request.depth ?? 1;
+  const entries: MemoryBrowseEntry[] = [];
+  let truncated = false;
+  const walk = (current: DirNode, currentPath: string, currentDepth: number): void => {
+    for (const entry of dirEntries(current, currentPath)) {
+      if (entries.length >= MAX_TREE_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      entries.push({ ...entry, depth: currentDepth });
+      if (entry.kind === "dir" && currentDepth < depth - 1) {
+        walk(current.subdirs.get(entry.name)!, entry.path, currentDepth + 1);
+        if (truncated) return;
+      }
+    }
+  };
+  walk(node, browsePath, 0);
+  return { ok: true, verb: "tree", namespace, path: browsePath, total: entries.length, entries, truncated, rendered: renderEntries("tree", namespace, browsePath, entries) };
+}

package/src/provenance.ts

@@ -652,11 +652,11 @@ function casefold(s: string): string {
  * this as a verified match and record a source without offsets (cursor
  * thread Ocver — "Normalized match drops verified provenance").
  */
-type LocateQuoteResult =
+export type LocateQuoteResult =
   | { matched: false }
   | { matched: true; offsets?: { charStart: number; charEnd: number } };
 
-function locateQuoteOffsets(quote: string, text: string): LocateQuoteResult {
+export function locateQuoteOffsets(quote: string, text: string): LocateQuoteResult {
   // 1. Exact substring match (handles unicode, curly quotes, emoji verbatim).
   const exactIdx = text.indexOf(quote);
   if (exactIdx >= 0) {
@@ -769,7 +769,7 @@ function locateQuoteOffsets(quote: string, text: string): LocateQuoteResult {
  * original meaning (chatgpt-codex-connector thread 4xA — limiting role-prefix
  * stripping to actual prompt labels).
  */
-function stripLeadingRolePrefix(quote: string): string {
+export function stripLeadingRolePrefix(quote: string): string {
   return quote.replace(/^\s*\[(?:context\s+)?(?:user|assistant)\]\s+/i, "");
 }
 

package/src/recall-context-composition.test.ts

@@ -2,6 +2,9 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  boundRecallContextComposition,
+  composeMissingMemoryContext,
+  composeRecallContext,
   formatCuriosityFooter,
   renderMemoryContextPrompt,
   selectCuriosityQuestion,
@@ -88,3 +91,66 @@ test("renderMemoryContextPrompt caps context before its footer deterministically
   assert.ok(rendered);
   assert.equal(rendered.body, "ab\n\n---\n\nfooter");
 });
+
+test("#2972 healthy recall carries no degradation marker", () => {
+  const composition = boundRecallContextComposition({
+    context: "A remembered deployment decision.",
+    maxChars: 512,
+  });
+
+  assert.equal("degradation" in composition, false);
+  assert.ok(!JSON.stringify(composition).includes("degradation"));
+});
+
+test("#2972 budget-clipped context is marked degraded, not silently cut", () => {
+  const composition = boundRecallContextComposition({
+    context: "x".repeat(100),
+    maxChars: 20,
+  });
+
+  assert.equal(composition.degradation?.state, "degraded");
+  assert.equal(composition.degradation?.reason, "budget-clipped");
+  assert.equal(composition.degradation?.budget?.fullChars, 100);
+  assert.ok(
+    (composition.degradation?.budget?.deliveredChars ?? 0) <
+      (composition.degradation?.budget?.fullChars ?? 0),
+  );
+});
+
+test("#2972 a fitting compact context is preferred over clipping the tail", () => {
+  const composition = boundRecallContextComposition({
+    context: "full-form entry one\n\nfull-form entry two",
+    compactContext: "entry one\nentry two",
+    maxChars: 30,
+  });
+
+  assert.equal(composition.context, "entry one\nentry two");
+  assert.equal(composition.degradation?.state, "degraded");
+  assert.equal(composition.degradation?.reason, "budget-compacted");
+  assert.equal(composition.degradation?.budget?.deliveredChars, 19);
+});
+
+test("#2972 a compact form that is not shallower than the full context is ignored", () => {
+  const composition = boundRecallContextComposition({
+    context: "x".repeat(50),
+    compactContext: "y".repeat(60),
+    maxChars: 10,
+  });
+
+  assert.equal(composition.degradation?.reason, "budget-clipped");
+});
+
+test("#2972 backend failure yields an explicit missing note, never an empty string", () => {
+  const composition = composeMissingMemoryContext({ detail: "backend_unavailable" });
+  const body = composeRecallContext(composition);
+
+  assert.ok(body.length > 0);
+  assert.match(body, /memory context unavailable/i);
+  assert.equal(composition.degradation?.state, "missing");
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.equal(composition.degradation?.detail, "backend_unavailable");
+
+  const rendered = renderMemoryContextPrompt({ ...composition, maxChars: 512 });
+  assert.ok(rendered);
+  assert.match(rendered.body, /memory context unavailable/i);
+});

package/src/recall-context-composition.ts

@@ -35,6 +35,33 @@ const TRIM_MARKER = "\n\n...(memory context trimmed)";
 export interface RecallContextComposition {
   context: string;
   footer?: string;
+  /**
+   * Machine-readable degradation marker (#2972). Absent on a healthy
+   * recall so the healthy wire shape stays byte-stable. Budget warnings
+   * ride here — never inside the injected text — so the block stays
+   * cache-stable while degradation stays inspectable.
+   */
+  degradation?: RecallContextDegradation;
+}
+
+export type RecallDegradationState = "complete" | "degraded" | "missing";
+
+export type RecallDegradationReason =
+  | "budget-clipped"
+  | "budget-compacted"
+  | "backend-unavailable";
+
+export interface RecallContextDegradation {
+  state: RecallDegradationState;
+  reason: RecallDegradationReason;
+  /** Operator-facing detail (e.g. a SearchDegradation code). */
+  detail?: string;
+  /** Budget accounting, present on budget-driven degradation. */
+  budget?: {
+    contextBudget: number;
+    fullChars: number;
+    deliveredChars: number;
+  };
 }
 
 export interface CuriosityQuestion {
@@ -53,6 +80,14 @@ export interface RenderedMemoryContextPrompt {
 
 export interface RenderMemoryContextPromptInput extends RecallContextComposition {
   maxChars: number;
+  /**
+   * Pre-rendered shallow form of every entry (#2972). When the full
+   * context exceeds budget, a fitting compact form is delivered instead
+   * of clipping the tail — breadth-complete-but-shallow over
+   * deep-but-amputated. Ignored unless strictly shorter than the full
+   * context and within budget.
+   */
+  compactContext?: string;
 }
 
 function trimText(value: string | undefined): string {
@@ -96,14 +131,77 @@ export function boundRecallContextComposition({
   context: rawContext,
   footer: rawFooter,
   maxChars,
+  compactContext: rawCompactContext,
 }: RenderMemoryContextPromptInput): RecallContextComposition {
   if (!Number.isFinite(maxChars) || maxChars <= 0) return { context: "" };
 
   const limit = Math.floor(maxChars);
   const footer = trimText(rawFooter);
-  const context = truncateToBudget(trimText(rawContext), contextBudgetForFooter(limit, footer));
+  const contextBudget = contextBudgetForFooter(limit, footer);
+  const fullContext = trimText(rawContext);
+  let context = fullContext;
+  let degradation: RecallContextDegradation | undefined;
+  if (fullContext.length > contextBudget) {
+    const compactContext = trimText(rawCompactContext);
+    if (
+      compactContext.length > 0 &&
+      compactContext.length <= contextBudget &&
+      compactContext.length < fullContext.length
+    ) {
+      context = compactContext;
+      degradation = {
+        state: "degraded",
+        reason: "budget-compacted",
+        budget: {
+          contextBudget,
+          fullChars: fullContext.length,
+          deliveredChars: compactContext.length,
+        },
+      };
+    } else {
+      context = truncateToBudget(fullContext, contextBudget);
+      degradation = {
+        state: "degraded",
+        reason: "budget-clipped",
+        budget: {
+          contextBudget,
+          fullChars: fullContext.length,
+          deliveredChars: context.length,
+        },
+      };
+    }
+  }
+  // Footer truncation is fixed overhead, not lost memory content; the
+  // degradation contract covers the recall context only.
   const boundedFooter = footer.length > limit ? truncateToBudget(footer, limit) : footer;
-  return { context, ...(boundedFooter ? { footer: boundedFooter } : {}) };
+  return {
+    context,
+    ...(boundedFooter ? { footer: boundedFooter } : {}),
+    ...(degradation ? { degradation } : {}),
+  };
+}
+
+export const MEMORY_CONTEXT_UNAVAILABLE_NOTE =
+  "Memory context unavailable for this turn: recall failed. " +
+  "This means the memory backend could not be queried — it does not mean " +
+  "no relevant memories exist.";
+
+/**
+ * Missing state (#2972): a failed recall path composes this INSTEAD of an
+ * empty or silently truncated context, so "backend failed" is never
+ * indistinguishable from "no relevant memories" (the injection-side twin
+ * of Review-Prevention rule 22). Replace the bounded composition with
+ * this result on failure; do not run it back through bounding.
+ */
+export function composeMissingMemoryContext(input: { detail?: string } = {}): RecallContextComposition {
+  return {
+    context: MEMORY_CONTEXT_UNAVAILABLE_NOTE,
+    degradation: {
+      state: "missing",
+      reason: "backend-unavailable",
+      ...(input.detail ? { detail: input.detail } : {}),
+    },
+  };
 }
 export function composeRecallContext(composition: RecallContextComposition): string {
   const context = trimText(composition.context);
@@ -117,11 +215,13 @@ export function renderMemoryContextPrompt({
   context: rawContext,
   footer: rawFooter,
   maxChars,
+  compactContext: rawCompactContext,
 }: RenderMemoryContextPromptInput): RenderedMemoryContextPrompt | null {
   const bounded = boundRecallContextComposition({
     context: rawContext,
     footer: rawFooter,
     maxChars,
+    compactContext: rawCompactContext,
   });
   const body = composeRecallContext(bounded);
   if (body.length === 0) return null;

package/src/reconcile/manifest.test.ts

@@ -39,6 +39,33 @@ test("peer manifest revision includes the citation-template fingerprint", () =>
   assert.equal(peerManifestRevision("{{source}}"), custom);
 });
 
+test("buildReconcileManifest stops scheduling read batches once the signal aborts (#2954)", async () => {
+  const controller = new AbortController();
+  let reads = 0;
+  const stub = Buffer.from("stub");
+  // 120 files = three 50-file read batches; the abort lands inside batch 1.
+  const files = Array.from({ length: 120 }, (_, i) => ({
+    path: `facts/batch-abort-${i}.md`,
+    sha256: createHash("sha256").update(String(i)).digest("hex"),
+  }));
+  await assert.rejects(
+    buildReconcileManifest({
+      files,
+      parseMemory: parseFrontmatter,
+      signal: controller.signal,
+      readFile: async () => {
+        reads += 1;
+        if (reads === 1) controller.abort();
+        return stub;
+      },
+    }),
+    (error: unknown) => (error as Error)?.name === "AbortError"
+  );
+  // Batch 1 was already in flight when the abort landed, so exactly its 50
+  // reads ran; batches 2 and 3 must never be scheduled.
+  assert.equal(reads, 50);
+});
+
 test("reconcile manifest keeps file identity separate from canonical semantic identity", async () => {
   const content = "The deployment uses a durable queue with an enrichment suffix.";
   const semanticHash = ContentHashIndex.computeHash("The deployment uses a durable queue.");

package/src/reconcile/manifest.ts

@@ -82,6 +82,9 @@ export interface BuildReconcileManifestOptions {
   parseMemory: ReconcileMemoryParser;
   cachedFiles?: Iterable<ReconcileManifestFile>;
   citationTemplate?: string;
+  /** Cancellation (#2954): checked between read batches so an aborted run
+   * stops scheduling new file reads instead of walking the whole corpus. */
+  signal?: AbortSignal;
 }
 
 const SHA256_PATTERN = /^[a-f0-9]{64}$/i;
@@ -287,6 +290,10 @@ export async function buildReconcileManifest(options: BuildReconcileManifestOpti
     }
   }
   for (let i = 0; i < uncached.length; i += MANIFEST_BUILD_BATCH_SIZE) {
+    // Between batches, not within one: an abort mid-batch lets the in-flight
+    // reads settle (their own fetch signal does the aborting) and stops the
+    // NEXT batch from ever being scheduled.
+    options.signal?.throwIfAborted();
     const batch = uncached.slice(i, i + MANIFEST_BUILD_BATCH_SIZE);
     const results = await Promise.all(
       batch.map(({ file }) =>