@stigmer/runner 3.1.3 → 3.1.4

package/src/shared/filereview/__tests__/cas-substrate.test.ts

@@ -24,6 +24,7 @@ import {
   casBlobKey,
   casBlobReader,
   casManifestKey,
+  classifyCasChange,
   loadCasManifest,
   restoreCasToBaseline,
   snapshotCasChangeSet,
@@ -436,3 +437,68 @@ describe("digest independence from capture class", () => {
     expect(files.map((f) => f.pathAfter)).toEqual(["a", "m", "z"]);
   });
 });
+
+// The single classification authority for a CAS before/after pair. Both the
+// turn-boundary capture (buildCasCapturedFile, exercised via snapshotCasChangeSet)
+// and the mid-run progress producer (cas-progress) route through it, so these
+// cases lock the shape the strip and the reviewed set share.
+describe("classifyCasChange (pure)", () => {
+  const buf = (s: string): Buffer => Buffer.from(s, "utf8");
+
+  it("classifies ADD from a null before and blanks the before path", () => {
+    const c = classifyCasChange("new.ts", null, buf("a\nb\nc\n"))!;
+    expect(c.kind).toBe(FileChangeKind.ADD);
+    expect(c.pathBefore).toBe("");
+    expect(c.pathAfter).toBe("new.ts");
+    expect(c.isBinary).toBe(false);
+    expect(c.lineCounts).toEqual({ linesAdded: 3, linesRemoved: 0 });
+  });
+
+  it("classifies DELETE from a null after and blanks the after path", () => {
+    const c = classifyCasChange("gone.ts", buf("x\ny\n"), null)!;
+    expect(c.kind).toBe(FileChangeKind.DELETE);
+    expect(c.pathBefore).toBe("gone.ts");
+    expect(c.pathAfter).toBe("");
+    expect(c.lineCounts).toEqual({ linesAdded: 0, linesRemoved: 2 });
+  });
+
+  it("classifies MODIFY from two present sides", () => {
+    const c = classifyCasChange("m.ts", buf("a\n"), buf("a\nb\n"))!;
+    expect(c.kind).toBe(FileChangeKind.MODIFY);
+    expect(c.pathBefore).toBe("m.ts");
+    expect(c.pathAfter).toBe("m.ts");
+    expect(c.lineCounts).toEqual({ linesAdded: 1, linesRemoved: 0 });
+  });
+
+  it("returns undefined for both-null and for a no-op touch (unchanged bytes)", () => {
+    expect(classifyCasChange("p", null, null)).toBeUndefined();
+    expect(classifyCasChange("p", buf("same\n"), buf("same\n"))).toBeUndefined();
+  });
+
+  it("marks a binary side and withholds line counts", () => {
+    const bin = Buffer.from([0, 1, 2, 0, 255, 0]);
+    const c = classifyCasChange("blob.bin", null, bin)!;
+    expect(c.kind).toBe(FileChangeKind.ADD);
+    expect(c.isBinary).toBe(true);
+    expect(c.lineCounts).toBeUndefined();
+  });
+
+  it("is the authority snapshotCasChangeSet uses (parity guard)", async () => {
+    const { storage } = makeFakeStorage();
+    const before = bytes("one\ntwo\n");
+    const after = bytes("one\ntwo\nthree\n");
+    const { manifest } = await snapshotCasChangeSet({
+      storage, executionId: EXEC, changeSetId: CHANGE_SET,
+      captures: [{ path: "m.ts", before, after, captureClass: IGNORED }],
+    });
+    const file = manifest.files[0];
+    const direct = classifyCasChange("m.ts", Buffer.from(before), Buffer.from(after))!;
+    // The captured file's display classification is exactly what the shared
+    // classifier produces — no second authority that could drift.
+    expect(file.kind).toBe(direct.kind);
+    expect(file.pathBefore).toBe(direct.pathBefore);
+    expect(file.pathAfter).toBe(direct.pathAfter);
+    expect(file.diffComplete).toBe(!direct.isBinary);
+    expect(file.lineCounts).toEqual(direct.lineCounts);
+  });
+});

package/src/shared/filereview/__tests__/command-provenance.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Unit tests for the shared DD-28 qualification rule
+ * ({@link qualifyTurnCommandProvenance}) — the harness-agnostic core both the
+ * Cursor and deep-agent adapters delegate to.
+ *
+ * These exercise the rule in isolation over synthetic `turnToolCalls` (the
+ * harness supplies the scoping + consent resolvers); each harness's own mapping
+ * is covered by its adapter suite. The rule: a turn qualifies only when every
+ * mutation-capable call it executed was a shell command with a provable consent
+ * source (direct / lease / auto_approve_all), and every uncertainty fails closed.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ApprovalAction,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { qualifyTurnCommandProvenance, findLeaseConsentId } from "../command-provenance.js";
+
+function toolCall(overrides: MessageInitShape<typeof ToolCallSchema>): ToolCall {
+  return create(ToolCallSchema, {
+    id: "call-1",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+function aiMessageWith(toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls });
+}
+
+// Default resolvers for the common "no direct consent, every listed call ran"
+// case — individual tests override as needed.
+const executedAlways = (): boolean => true;
+const noDirectConsent = (): undefined => undefined;
+
+function shell(id: string, cmd = "seq 1 5 > out.txt"): ToolCall {
+  return toolCall({ id, name: "shell", args: { command: cmd } });
+}
+
+describe("qualifyTurnCommandProvenance", () => {
+  it("cites the direct consent id the resolver returns", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: (t) => (t.id === "shell-1" ? "consent-row" : undefined),
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("falls back to the APPROVE_ALL lease row when there is no direct consent", () => {
+    const leaseRow = toolCall({
+      id: "lease-row",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const leased = shell("shell-leased");
+    const messages = [aiMessageWith([leaseRow]), aiMessageWith([leased])];
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [leased],
+      messages,
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+
+  it("flags auto_approve_all when only the global bypass authorized the command", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: true,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual([]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(true);
+  });
+
+  it("prefers direct consent over auto_approve_all when both are available", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: true,
+    });
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("fails closed on a file-tool call (mixed turn)", () => {
+    const tc = shell("shell-1");
+    const edit = toolCall({ id: "edit-1", name: "edit", args: { path: "a.txt" } });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, edit],
+      messages: [aiMessageWith([tc, edit])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an MCP tool", () => {
+    const tc = shell("shell-1");
+    const mcp = toolCall({ id: "mcp-1", name: "apply_resource", mcpServerSlug: "planton" });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, mcp],
+      messages: [aiMessageWith([tc, mcp])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on a sub-agent delegation (task -> SUBAGENT kind)", () => {
+    const tc = shell("shell-1");
+    const task = toolCall({ id: "task-1", name: "task", args: { prompt: "go" } });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, task],
+      messages: [aiMessageWith([tc, task])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an unrecognized tool name", () => {
+    const tc = shell("shell-1");
+    const unknown = toolCall({ id: "u-1", name: "mystery_tool" });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, unknown],
+      messages: [aiMessageWith([tc, unknown])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an executed command with no provable consent source", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("returns undefined when no command executed (only a pending shell)", () => {
+    const pending = shell("shell-pending");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [pending],
+      messages: [aiMessageWith([pending])],
+      isExecutedCommand: () => false, // pending / denied — never executed
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("skips read-only tools and hidden collapsed rows, then qualifies", () => {
+    const read = toolCall({ id: "read-1", name: "read", args: { path: "a.txt" } });
+    const hidden = toolCall({
+      id: "hidden-1",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_SKIPPED,
+      args: undefined,
+    });
+    const executed = shell("shell-executed");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [read, hidden, executed],
+      messages: [aiMessageWith([read, hidden, executed])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: (t) => (t.id === "shell-executed" ? "consent-row" : undefined),
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+  });
+
+  it("dedupes consent ids across multiple commands citing the same lease", () => {
+    const leaseRow = toolCall({
+      id: "lease-row",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const a = shell("shell-a");
+    const b = shell("shell-b");
+    const messages = [aiMessageWith([leaseRow]), aiMessageWith([a, b])];
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [a, b],
+      messages,
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+});
+
+describe("findLeaseConsentId", () => {
+  it("returns the earliest APPROVE_ALL row of the tool's category", () => {
+    const first = toolCall({ id: "lease-1", name: "shell", approvalAction: ApprovalAction.APPROVE_ALL });
+    const second = toolCall({ id: "lease-2", name: "bash", approvalAction: ApprovalAction.APPROVE_ALL });
+    const messages = [aiMessageWith([first]), aiMessageWith([second])];
+    expect(findLeaseConsentId(messages, "execute")).toBe("lease-1");
+  });
+
+  it("returns undefined when no APPROVE_ALL lease exists for the category", () => {
+    const writeApproveAll = toolCall({
+      id: "w-1",
+      name: "write",
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const messages = [aiMessageWith([writeApproveAll])];
+    // A write-category lease does not authorize a shell command.
+    expect(findLeaseConsentId(messages, "shell")).toBeUndefined();
+  });
+
+  it("returns undefined for a non-gated (read-only) tool name", () => {
+    const messages = [aiMessageWith([shell("s")])];
+    expect(findLeaseConsentId(messages, "read")).toBeUndefined();
+  });
+});

package/src/shared/filereview/__tests__/progress.test.ts

@@ -20,12 +20,18 @@ import {
   snapshotBaseline,
   dropCaptureRefs,
   type GitProgressEntry,
-  type ProgressDelta,
+  type GitProgressDelta,
 } from "../git-substrate.js";
 import {
   buildFileChangeProgress,
+  createGitProgressSubstrate,
+  createHybridProgressSubstrate,
   PROGRESS_MAX_ENTRIES,
   shouldCaptureProgress,
+  type ProgressCapture,
+  type ProgressDelta,
+  type ProgressEntry,
+  type ProgressSubstrate,
 } from "../progress.js";
 
 const execFileAsync = promisify(execFile);
@@ -49,7 +55,7 @@ async function writeBytes(rel: string, bytes: Uint8Array): Promise<void> {
   await writeFile(join(repo, rel), bytes);
 }
 
-function entryFor(delta: ProgressDelta, path: string): GitProgressEntry | undefined {
+function entryFor(delta: GitProgressDelta, path: string): GitProgressEntry | undefined {
   return delta.entries.find((e) => e.pathAfter === path || e.pathBefore === path);
 }
 
@@ -157,23 +163,28 @@ describe("captureProgressDelta (real git repo)", () => {
 });
 
 describe("buildFileChangeProgress (pure)", () => {
-  function delta(entries: GitProgressEntry[]): ProgressDelta {
-    return { afterTree: "tree-sha", entries };
+  function delta(entries: ProgressEntry[], totalFilesChanged?: number): ProgressDelta {
+    return totalFilesChanged === undefined ? { entries } : { entries, totalFilesChanged };
   }
-  function entry(path: string, added: number, removed: number): GitProgressEntry {
+  function entry(
+    path: string,
+    added: number,
+    removed: number,
+    kind: FileChangeKind = FileChangeKind.MODIFY,
+  ): ProgressEntry {
     return {
-      pathBefore: path,
+      pathBefore: kind === FileChangeKind.ADD ? "" : path,
       pathAfter: path,
-      changeType: FileChangeType.MODIFY,
+      kind,
       linesAdded: added,
       linesRemoved: removed,
     };
   }
 
-  it("sums aggregate counts and maps kind", () => {
+  it("sums aggregate counts and carries the per-entry kind through unchanged", () => {
     const progress = buildFileChangeProgress(
       delta([
-        { pathBefore: "", pathAfter: "a.ts", changeType: FileChangeType.CREATE, linesAdded: 5, linesRemoved: 0 },
+        entry("a.ts", 5, 0, FileChangeKind.ADD),
         entry("b.ts", 2, 3),
       ]),
       CHANGE_SET_ID,
@@ -187,6 +198,18 @@ describe("buildFileChangeProgress (pure)", () => {
     expect(progress.capturedAt).not.toBe("");
   });
 
+  it("reports totalFilesChanged when a substrate capped its reads, else the entry count", () => {
+    // git substrate leaves totalFilesChanged undefined -> filesChanged = entries.length.
+    const gitLike = buildFileChangeProgress(delta([entry("a.ts", 1, 0)]), CHANGE_SET_ID);
+    expect(gitLike.filesChanged).toBe(1);
+
+    // cas substrate read only a bounded prefix -> filesChanged reflects the honest
+    // total even though fewer entries were emitted.
+    const casLike = buildFileChangeProgress(delta([entry("a.ts", 1, 0)], 7), CHANGE_SET_ID);
+    expect(casLike.filesChanged).toBe(7);
+    expect(casLike.entries).toHaveLength(1);
+  });
+
   it("zeroes counts for secret-like paths (path visible, magnitude withheld)", () => {
     const progress = buildFileChangeProgress(
       delta([entry(".env", 10, 2), entry("app.ts", 4, 1)]),
@@ -203,7 +226,7 @@ describe("buildFileChangeProgress (pure)", () => {
   });
 
   it("caps entries but keeps files_changed and totals honest over all files", () => {
-    const entries: GitProgressEntry[] = [];
+    const entries: ProgressEntry[] = [];
     for (let i = 0; i < PROGRESS_MAX_ENTRIES + 25; i++) {
       entries.push(entry(`f${i}.ts`, 1, 1));
     }
@@ -234,3 +257,82 @@ describe("shouldCaptureProgress (pure)", () => {
     expect(shouldCaptureProgress(1000, 3001, 2000)).toBe(true);
   });
 });
+
+describe("createGitProgressSubstrate (real git repo)", () => {
+  it("reports changed:true then reuses the cached full delta on an unchanged tree", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+    const sub = createGitProgressSubstrate({
+      workspaceRoot: repo,
+      executionId: EXEC_ID,
+      baselineTree: baseline,
+    });
+
+    await write("src/new.ts", "a\nb\n");
+    const first = await sub.capture();
+    expect(first.changed).toBe(true);
+    expect(first.delta.entries.length).toBeGreaterThan(0);
+
+    // Nothing moved since the last capture: the tree-sha short-circuits, but the
+    // full delta is still returned (changed:false) so a hybrid can merge it.
+    const second = await sub.capture();
+    expect(second.changed).toBe(false);
+    expect(second.delta.entries).toEqual(first.delta.entries);
+  });
+});
+
+/** A fake substrate returning a fixed capture — for merge/short-circuit logic. */
+function fakeSubstrate(capture: ProgressCapture): ProgressSubstrate {
+  return { capture: () => Promise.resolve(capture) };
+}
+
+function progressEntry(path: string): ProgressEntry {
+  return { pathBefore: "", pathAfter: path, kind: FileChangeKind.ADD, linesAdded: 1, linesRemoved: 0 };
+}
+
+describe("createHybridProgressSubstrate", () => {
+  it("concatenates disjoint git + cas slices and sums the honest totals", async () => {
+    const git = fakeSubstrate({
+      delta: { entries: [progressEntry("tracked.ts")] }, // git: total = entries.length
+      changed: true,
+    });
+    const cas = fakeSubstrate({
+      delta: { entries: [progressEntry(".env.local")], totalFilesChanged: 3 }, // cas capped
+      changed: true,
+    });
+    const hybrid = createHybridProgressSubstrate(git, cas);
+
+    const { delta, changed } = await hybrid.capture();
+    expect(changed).toBe(true);
+    expect(delta.entries.map((e) => e.pathAfter)).toEqual(["tracked.ts", ".env.local"]);
+    // 1 (git entries) + 3 (cas honest total) = 4.
+    expect(delta.totalFilesChanged).toBe(4);
+  });
+
+  it("still emits the full git slice when only the cas slice changed", async () => {
+    // Git unchanged returns its cached full delta with changed:false; the hybrid
+    // must keep it (a `ProgressDelta | undefined` contract would have dropped it).
+    const git = fakeSubstrate({
+      delta: { entries: [progressEntry("tracked.ts")] },
+      changed: false,
+    });
+    const cas = fakeSubstrate({
+      delta: { entries: [progressEntry("build/out.js")], totalFilesChanged: 1 },
+      changed: true,
+    });
+    const hybrid = createHybridProgressSubstrate(git, cas);
+
+    const { delta, changed } = await hybrid.capture();
+    expect(changed).toBe(true);
+    expect(delta.entries.map((e) => e.pathAfter)).toEqual(["tracked.ts", "build/out.js"]);
+    expect(delta.totalFilesChanged).toBe(2);
+  });
+
+  it("reports changed:false only when NEITHER slice moved", async () => {
+    const git = fakeSubstrate({ delta: { entries: [] }, changed: false });
+    const cas = fakeSubstrate({ delta: { entries: [], totalFilesChanged: 0 }, changed: false });
+    const hybrid = createHybridProgressSubstrate(git, cas);
+
+    const { changed } = await hybrid.capture();
+    expect(changed).toBe(false);
+  });
+});

package/src/shared/filereview/cas-progress.ts

@@ -0,0 +1,170 @@
+/**
+ * Mid-run progress substrate for the CAS (content-addressed) domain — the
+ * non-git and gitignored half of DD-33. The git substrate ({@link ./progress.js}
+ * `createGitProgressSubstrate`) covers git-tracked changes cheaply via
+ * `--numstat`; this covers the paths git cannot see, sourced from the same
+ * per-turn observer the turn-boundary CAS capture reads:
+ *  - a non-git workspace: EVERY tool-mediated write (the whole change set), and
+ *  - a git tree's gitignored writes (the CAS half of a HYBRID turn).
+ *
+ * COST MODEL (why this is not as cheap as git)
+ * --------------------------------------------
+ * `git --numstat` yields exact `+N −M` with zero byte reads; CAS has no such free
+ * lunch — kind, no-op exclusion, and counts all need the after-bytes. So we bound
+ * the work: only the sorted read-PREFIX (up to {@link PROGRESS_MAX_ENTRIES}) has
+ * its after-bytes read and counted; the tail contributes to `totalFilesChanged`
+ * (the honest count) only. `files_changed` is therefore net-exact for a normal
+ * turn (≤ the budget) and an upper bound beyond it — matching git where git is
+ * free, diverging only where the substrate cannot be. A `size+mtime` signature
+ * (the stats are collected anyway) short-circuits an unchanged capture.
+ *
+ * CONSISTENCY & SECRET SAFETY
+ * ---------------------------
+ * Counts come from {@link classifyCasChange} — the SAME classifier the reviewed
+ * set uses — so the strip and the change set never disagree. Secret-like paths
+ * are excluded up front via {@link partitionIgnoredPathsBySecret} (and zeroed
+ * again in `buildFileChangeProgress` as a backstop); no file bodies are ever
+ * carried on the wire. Only tool-mediated writes are observed, exactly the scope
+ * of the non-git / HYBRID turn-boundary capture — no new divergence.
+ *
+ * @since File-Change HITL Redesign (non-git + hybrid mid-run progress / DD-33)
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyCasChange } from "./cas-substrate.js";
+import { LINE_COUNT_MAX_BYTES } from "./line-counts.js";
+import {
+  PROGRESS_MAX_ENTRIES,
+  type ProgressCapture,
+  type ProgressDelta,
+  type ProgressEntry,
+  type ProgressSubstrate,
+} from "./progress.js";
+import { partitionIgnoredPathsBySecret } from "./secret-paths.js";
+
+/**
+ * A snapshot of the turn's CAS-observed paths, read on each capture:
+ *  - `before`: first-touched paths' pre-turn bytes (`null` = the path did not
+ *    exist before → an ADD). The KEYS are the touched-path set.
+ *  - `blockedSecretPaths`: paths the gate hard-blocked as secret-like — excluded
+ *    from capture.
+ *
+ * Deep-agent supplies a synchronous copy of its live `CasCaptureObserver`; Cursor
+ * supplies a reader over the hook's on-disk sidecar. The reader MUST return an
+ * atomic snapshot (copy the live map before any await) so a concurrent sub-agent
+ * write cannot mutate it mid-capture.
+ */
+export interface CasTouchedSnapshot {
+  readonly before: ReadonlyMap<string, Uint8Array | null>;
+  readonly blockedSecretPaths: ReadonlySet<string>;
+}
+
+/** Produces a {@link CasTouchedSnapshot} for one capture. */
+export type CasTouchedReader = () => CasTouchedSnapshot | Promise<CasTouchedSnapshot>;
+
+/**
+ * The CAS progress substrate. Reads the touched set on each capture, computes
+ * kind + `+N −M` for the bounded read-prefix via {@link classifyCasChange}, and
+ * reports `totalFilesChanged` over the full capturable set. Owns a `size+mtime`
+ * signature so an unchanged capture returns `changed:false` (the cached delta is
+ * reused, letting the hybrid still merge it with a changed git slice).
+ */
+export function createCasProgressSubstrate(opts: {
+  readonly workspaceRoot: string;
+  readonly read: CasTouchedReader;
+  /** Read budget / display cap; defaults to {@link PROGRESS_MAX_ENTRIES}. Injectable for tests. */
+  readonly maxEntries?: number;
+}): ProgressSubstrate {
+  const maxEntries = opts.maxEntries ?? PROGRESS_MAX_ENTRIES;
+  let cachedFull: ProgressDelta = { entries: [], totalFilesChanged: 0 };
+  let lastSignature: string | undefined;
+
+  return {
+    async capture(): Promise<ProgressCapture> {
+      const snapshot = await opts.read();
+      const { capturablePaths } = partitionIgnoredPathsBySecret(
+        snapshot.before.keys(),
+        snapshot.blockedSecretPaths,
+      );
+      // Deterministic order so the read prefix and entry order are stable.
+      const sorted = [...capturablePaths].sort();
+      const prefix = sorted.slice(0, maxEntries);
+
+      const entries: ProgressEntry[] = [];
+      // The signature keys on the capturable count (catches a new touch) plus the
+      // read prefix's size+mtime (catches a content edit to a shown file). A
+      // change to an UNshown tail file has no display effect, so it is not keyed.
+      const sigParts: string[] = [`${capturablePaths.length}`];
+
+      for (const relPath of prefix) {
+        const abs = join(opts.workspaceRoot, relPath);
+        const st = await statOrNull(abs);
+        sigParts.push(`${relPath}\u0000${st ? `${st.size}:${st.mtimeMs}` : "\u2205"}`);
+
+        const beforeBytes = snapshot.before.get(relPath) ?? null;
+        const beforeBuf = beforeBytes === null ? null : Buffer.from(beforeBytes);
+
+        // Oversized after: derive the kind without reading (bound the I/O) and
+        // leave counts at zero — the same "no stat" shape a binary/oversized side
+        // takes in the reviewed set. A same-size no-op cannot be excluded here; an
+        // accepted overstatement only for very large files.
+        if (st && st.size > LINE_COUNT_MAX_BYTES) {
+          const kind = beforeBuf === null ? FileChangeKind.ADD : FileChangeKind.MODIFY;
+          entries.push({
+            pathBefore: kind === FileChangeKind.ADD ? "" : relPath,
+            pathAfter: relPath,
+            kind,
+            linesAdded: 0,
+            linesRemoved: 0,
+          });
+          continue;
+        }
+
+        const afterBytes = st ? await readFileOrNull(abs) : null;
+        const afterBuf = afterBytes === null ? null : Buffer.from(afterBytes);
+        const cls = classifyCasChange(relPath, beforeBuf, afterBuf);
+        if (!cls) continue; // no-op (unchanged touch) or both sides absent
+        entries.push({
+          pathBefore: cls.pathBefore,
+          pathAfter: cls.pathAfter,
+          kind: cls.kind,
+          linesAdded: cls.lineCounts?.linesAdded ?? 0,
+          linesRemoved: cls.lineCounts?.linesRemoved ?? 0,
+        });
+      }
+
+      // Honest total: the capturable set minus the no-ops detected in the read
+      // prefix. Net-exact for a turn within the read budget; an upper bound beyond
+      // it (tail no-ops are not read, so cannot be excluded).
+      const prefixNoOps = prefix.length - entries.length;
+      const totalFilesChanged = capturablePaths.length - prefixNoOps;
+
+      const signature = sigParts.join("|");
+      if (signature === lastSignature) {
+        return { delta: cachedFull, changed: false };
+      }
+      lastSignature = signature;
+      cachedFull = { entries, totalFilesChanged };
+      return { delta: cachedFull, changed: true };
+    },
+  };
+}
+
+async function statOrNull(abs: string): Promise<{ size: number; mtimeMs: number } | null> {
+  try {
+    const s = await stat(abs);
+    return { size: s.size, mtimeMs: s.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+async function readFileOrNull(abs: string): Promise<Uint8Array | null> {
+  try {
+    return await readFile(abs);
+  } catch {
+    return null;
+  }
+}