@stigmer/runner 3.1.3 → 3.1.4

package/src/activities/execute-deep-agent/index.ts

@@ -52,14 +52,26 @@ import {
 } from "../../shared/filereview/capture.js";
 import {
   captureFileChangeProgress,
+  createGitProgressSubstrate,
+  createHybridProgressSubstrate,
   newProgressCaptureState,
+  type ProgressSubstrate,
 } from "../../shared/filereview/progress.js";
+import {
+  createCasProgressSubstrate,
+  type CasTouchedSnapshot,
+} from "../../shared/filereview/cas-progress.js";
 import { hasCandidateCaptured } from "../../shared/filereview/events.js";
 import { casBlobReader, type CasPathCapture } from "../../shared/filereview/cas-substrate.js";
 import { partitionIgnoredPathsBySecret } from "../../shared/filereview/secret-paths.js";
 import type { CasCaptureObserver } from "./cas-capture-observer.js";
-import { collectSubAgentToolCallIds, withholdSecretContentFromMessages } from "../../shared/tool-row.js";
+import {
+  collectSettledToolCallIds,
+  collectSubAgentToolCallIds,
+  withholdSecretContentFromMessages,
+} from "../../shared/tool-row.js";
 import { stampFlowedFileEditRows, stampFlowedSubAgentFileEditRows } from "./stamp-flowed-rows.js";
+import { deriveTurnCommandProvenance } from "./command-provenance.js";
 
 /** The harness id stamped on the deep-agent's file-review ledger events. */
 const DEEP_AGENT_HARNESS_ID = "deep-agent";
@@ -312,6 +324,12 @@ export function createDeepAgentActivities(config: Config) {
         // seeds prior sub-agents — but computed, not assumed, so it stays correct
         // if that ever changes; see collectSubAgentToolCallIds).
         const priorSubAgentToolCallIds = collectSubAgentToolCallIds(initialStatus.subAgentExecutions);
+        // Snapshot the top-level tool-call ids already SETTLED before this turn's
+        // stream, so the approved-command provenance (DD-28) scopes itself to THIS
+        // turn's executed commands by identity. The deep-agent's approved shell
+        // executes in place at its seeded position, so the Cursor positional scope
+        // would miss it — see execute-deep-agent/command-provenance.ts.
+        const priorSettledToolCallIds = collectSettledToolCallIds(initialStatus.messages);
         if (setup.captureMode) {
           captureBaselineTree = await captureBaselineToLedger({
             status: initialStatus,
@@ -323,14 +341,34 @@ export function createDeepAgentActivities(config: Config) {
           });
         }
 
-        // Per-turn state for mid-run live capture (DD-32): the last progress tree
-        // sha (short-circuit) + last capture time (floor), threaded across the
-        // streaming loop's persists via the beforePersist hook below. The capture
-        // flags are hoisted so the deferred hook does not depend on `setup`
-        // (non-null here, but not narrowable inside a later-invoked closure).
+        // Per-turn state + substrate for mid-run live capture (DD-32 / DD-33). The
+        // floor lives in progressState; the substrate is chosen for this turn's
+        // workspace shape and owns its own short-circuit cache. An atomic snapshot
+        // of the shared observer feeds the CAS/HYBRID substrates — copied
+        // synchronously so a concurrent sub-agent write cannot mutate it mid-read.
         const progressState = newProgressCaptureState();
-        const progressCaptureMode = setup.captureMode;
-        const progressGitWorkspace = setup.gitWorkspace;
+        const casObserver = setup.casObserver;
+        const readObserverTouched = (): CasTouchedSnapshot => ({
+          before: new Map(casObserver.before),
+          blockedSecretPaths: new Set(casObserver.blockedSecretPaths),
+        });
+        // Git tree -> hybrid (numstat for tracked + observer for gitignored);
+        // non-git -> cas over the observer (no baseline tree needed). Undefined
+        // outside capture mode (writes are deny-gated, nothing is captured).
+        const progressSubstrate: ProgressSubstrate | undefined = !setup.captureMode
+          ? undefined
+          : setup.gitWorkspace
+            ? captureBaselineTree
+              ? createHybridProgressSubstrate(
+                  createGitProgressSubstrate({
+                    workspaceRoot: gitRoot,
+                    executionId,
+                    baselineTree: captureBaselineTree,
+                  }),
+                  createCasProgressSubstrate({ workspaceRoot: gitRoot, read: readObserverTouched }),
+                )
+              : undefined
+            : createCasProgressSubstrate({ workspaceRoot: gitRoot, read: readObserverTouched });
 
         const cancellationSignal = Context.current().cancellationSignal;
 
@@ -357,20 +395,18 @@ export function createDeepAgentActivities(config: Config) {
             globalBypass: setup.globalBypass,
           },
           streamVersion: setup.streamVersion,
-          // Mid-run live capture (DD-32): attach file_change_progress before each
-          // scheduled persist. Git capture mode only (a pinned baseline exists);
-          // deep-agent writes no runner-owned gate files into the tree, so no
-          // excludePaths — matching its turn-boundary candidate capture.
+          // Mid-run live capture (DD-32 / DD-33): attach file_change_progress
+          // before each scheduled persist, throttled by the floor inside
+          // captureFileChangeProgress. The substrate (git / non-git CAS / hybrid)
+          // was chosen for this turn above; deep-agent writes no runner-owned gate
+          // files into the tree, so the git slice needs no excludePaths — matching
+          // its turn-boundary candidate capture.
           beforePersist: async (status) => {
-            if (!progressCaptureMode || !progressGitWorkspace || !captureBaselineTree) {
-              return;
-            }
+            if (!progressSubstrate) return;
             await captureFileChangeProgress({
               status,
-              gitRoot,
-              executionId,
               changeSetId,
-              baselineTree: captureBaselineTree,
+              substrate: progressSubstrate,
               state: progressState,
             });
           },
@@ -429,6 +465,25 @@ export function createDeepAgentActivities(config: Config) {
             gitRoot,
             casCaptureClass,
           );
+          // Approved-command turn facts (DD-28): when every mutation-capable call
+          // this turn was a consented shell command, attach the provenance so the
+          // backend can verify the cited consent rows and auto-keep the set
+          // instead of arming a second review gate. Fail-closed: any non-qualifying
+          // turn attaches nothing and reviews manually exactly as before. Attached
+          // only when captureCandidateToLedger actually authors a CANDIDATE.
+          const commandProvenance = deriveTurnCommandProvenance({
+            status: initialStatus,
+            priorSettledToolCallIds,
+            priorSubAgentToolCallIds,
+            globalBypass: setup.globalBypass,
+          });
+          if (commandProvenance) {
+            console.log(
+              `[ExecuteDeepAgent] capture: turn qualifies for approved-command auto-keep ` +
+              `(consent rows: ${commandProvenance.consentToolCallIds.join(",") || "(auto_approve_all)"}); ` +
+              `attaching provenance to candidate (execution=${executionId})`,
+            );
+          }
           await captureCandidateToLedger({
             status: initialStatus,
             gitRoot,
@@ -441,6 +496,7 @@ export function createDeepAgentActivities(config: Config) {
             unreviewablePaths,
             unreviewableCaptureClass: casCaptureClass,
             gitWorkspace: setup.gitWorkspace,
+            commandProvenance,
           });
           // Review is pending iff a CANDIDATE was actually authored (the seam
           // drops no-op captures), so a turn that only touched-then-unchanged an

package/src/activities/execute-deep-agent/status-builder.ts

@@ -24,9 +24,11 @@ import {
   ExecutionPhase,
   MessageType,
   ToolCallStatus,
+  ToolKind,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
 import { classifyTool } from "../../shared/tool-kind.js";
+import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
 import type { ExecutionStatusWriter } from "./execution-status-writer.js";
@@ -348,6 +350,13 @@ export class StatusBuilder {
       // (see v3 builder note). Truncating here would corrupt image base64.
       tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
       tc.result = extractToolResult(event.data);
+
+      // Project a completed to-do write into status.todos — success branch only,
+      // since a failed write_todos never ran its state-mutating Command. Shares
+      // the mapper and rationale documented in V3StatusBuilder.handleToolFinished.
+      if (tc.toolKind === ToolKind.TODO) {
+        applyTodoUpdate(this.state.proto.todos, tc.args?.todos, { merge: false });
+      }
     }
 
     tc.completedAt = utcTimestamp();

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -23,9 +23,11 @@ import {
   ExecutionPhase,
   MessageType,
   ToolCallStatus,
+  ToolKind,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { resolveApprovalMessage as resolveApprovalMsg } from "../../shared/approval-policy.js";
 import { classifyTool } from "../../shared/tool-kind.js";
+import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
 import type { ExecutionStatusWriter } from "./execution-status-writer.js";
@@ -340,6 +342,17 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     this.state.toolStartTimes.delete(callId);
     this.toolArgBuffers.delete(callId);
 
+    // Project a completed to-do write into status.todos. deepagents' write_todos
+    // runs its state-mutating Command when the tool node COMPLETES, so we mirror
+    // it here (not at tool-start) — a call cancelled before finishing correctly
+    // projects nothing. Keyed on the harness-agnostic ToolKind.TODO (stamped at
+    // tool-start) and fed by the same shared mapper the Cursor tracker uses;
+    // deepagents always full-replaces (no merge field). The tool call itself
+    // stays in messages (the client filters ToolKind.TODO from the thread).
+    if (tc.toolKind === ToolKind.TODO) {
+      applyTodoUpdate(this.state.proto.todos, tc.args?.todos, { merge: false });
+    }
+
     this._forceNextUpdate = true;
   }
 

package/src/otel.ts

@@ -125,12 +125,20 @@ export async function startCursorTurnSpan(attrs: {
         [ATTR_SESSION_ID]: attrs.sessionId,
       },
     });
+    // Guard against a double end / a late setTokens: the turn span is ended from
+    // the activity's finally (finishTurnTelemetry), and OTel warns when a span is
+    // ended twice or mutated after end. Making this a no-op keeps the caller free
+    // to end idempotently on every exit path.
+    let ended = false;
     return {
       setTokens(input: number, output: number) {
+        if (ended) return;
         if (input) span.setAttribute(ATTR_LLM_INPUT_TOKENS, input);
         if (output) span.setAttribute(ATTR_LLM_OUTPUT_TOKENS, output);
       },
       end() {
+        if (ended) return;
+        ended = true;
         span.end();
       },
     };

package/src/shared/__tests__/todos.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for applyTodoUpdate — the harness-agnostic to-do map projection
+ * shared by the Cursor TodoTracker and the native v2/v3 status builders.
+ *
+ * These pin the exact mapping contract (status coercion, id synthesis,
+ * created_at preservation, merge vs. full-replace, clear-on-empty, defensive
+ * input handling, dirty return) so no two writers of status.todos can drift.
+ */
+
+import { describe, it, expect } from "vitest";
+import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import { applyTodoUpdate } from "../todos.js";
+
+function emptyMap(): { [key: string]: TodoItem } {
+  return {};
+}
+
+describe("applyTodoUpdate", () => {
+  describe("status mapping", () => {
+    it("maps pending", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "pending" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_PENDING);
+    });
+
+    it("maps in_progress (snake_case)", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "in_progress" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_IN_PROGRESS);
+    });
+
+    it("maps inProgress (camelCase, via toLowerCase)", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "inProgress" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_IN_PROGRESS);
+    });
+
+    it("maps completed", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "completed" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_COMPLETED);
+    });
+
+    it("maps cancelled (Cursor superset)", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "cancelled" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_CANCELLED);
+    });
+
+    it("defaults unknown status to pending", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "bogus" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_PENDING);
+    });
+
+    it("defaults missing status to pending", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A" }], { merge: false });
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_PENDING);
+    });
+  });
+
+  describe("id synthesis", () => {
+    it("uses a provided id", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "t1", content: "A", status: "pending" }], { merge: false });
+      expect(Object.keys(m)).toEqual(["t1"]);
+      expect(m["t1"].id).toBe("t1");
+    });
+
+    it("falls back to todo-<index> when id is absent", () => {
+      const m = emptyMap();
+      applyTodoUpdate(
+        m,
+        [
+          { content: "A", status: "pending" },
+          { content: "B", status: "completed" },
+        ],
+        { merge: false },
+      );
+      expect(Object.keys(m)).toEqual(["todo-0", "todo-1"]);
+    });
+
+    it("falls back to todo-<index> when id is an empty string", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "", content: "A", status: "pending" }], { merge: false });
+      expect(Object.keys(m)).toEqual(["todo-0"]);
+    });
+  });
+
+  describe("timestamps", () => {
+    it("sets created_at from raw.created_at on full-replace", () => {
+      const m = emptyMap();
+      applyTodoUpdate(
+        m,
+        [{ id: "t1", content: "A", status: "pending", created_at: "2026-01-01T00:00:00Z" }],
+        { merge: false, now: "2026-06-06T06:06:06Z" },
+      );
+      expect(m["t1"].createdAt).toBe("2026-01-01T00:00:00Z");
+    });
+
+    it("uses now for created_at when raw.created_at is absent (full-replace)", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "pending" }], {
+        merge: false,
+        now: "2026-06-06T06:06:06Z",
+      });
+      expect(m["todo-0"].createdAt).toBe("2026-06-06T06:06:06Z");
+    });
+
+    it("always bumps updated_at to now", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ content: "A", status: "pending" }], {
+        merge: false,
+        now: "2026-06-06T06:06:06Z",
+      });
+      expect(m["todo-0"].updatedAt).toBe("2026-06-06T06:06:06Z");
+    });
+
+    it("preserves created_at from the prior entry ONLY on merge", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "t1", content: "A", status: "pending" }], {
+        merge: false,
+        now: "2026-01-01T00:00:00Z",
+      });
+      applyTodoUpdate(m, [{ id: "t1", content: "A", status: "completed" }], {
+        merge: true,
+        now: "2026-02-02T00:00:00Z",
+      });
+      expect(m["t1"].createdAt).toBe("2026-01-01T00:00:00Z");
+      expect(m["t1"].updatedAt).toBe("2026-02-02T00:00:00Z");
+      expect(m["t1"].status).toBe(TodoStatus.TODO_COMPLETED);
+    });
+
+    it("does NOT preserve created_at on full-replace of the same id", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "t1", content: "A", status: "pending" }], {
+        merge: false,
+        now: "2026-01-01T00:00:00Z",
+      });
+      applyTodoUpdate(m, [{ id: "t1", content: "A", status: "pending" }], {
+        merge: false,
+        now: "2026-02-02T00:00:00Z",
+      });
+      expect(m["t1"].createdAt).toBe("2026-02-02T00:00:00Z");
+    });
+  });
+
+  describe("merge vs. full-replace", () => {
+    it("full-replace clears prior entries", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      applyTodoUpdate(m, [{ id: "b", content: "B", status: "pending" }], { merge: false });
+      expect(Object.keys(m)).toEqual(["b"]);
+    });
+
+    it("merge preserves other existing entries", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      applyTodoUpdate(m, [{ id: "b", content: "B", status: "pending" }], { merge: true });
+      expect(Object.keys(m).sort()).toEqual(["a", "b"]);
+    });
+
+    it("merge updates an existing entry by id", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      applyTodoUpdate(m, [{ id: "a", content: "A2", status: "completed" }], { merge: true });
+      expect(m["a"].content).toBe("A2");
+      expect(m["a"].status).toBe(TodoStatus.TODO_COMPLETED);
+    });
+  });
+
+  describe("clear-on-empty", () => {
+    it("clears the map on empty array + full-replace and reports a change", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      const changed = applyTodoUpdate(m, [], { merge: false });
+      expect(changed).toBe(true);
+      expect(Object.keys(m)).toHaveLength(0);
+    });
+
+    it("does NOT clear and reports no change on empty array + merge", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      const changed = applyTodoUpdate(m, [], { merge: true });
+      expect(changed).toBe(false);
+      expect(Object.keys(m)).toEqual(["a"]);
+    });
+
+    it("treats a non-array payload like empty (clears on full-replace)", () => {
+      const m = emptyMap();
+      applyTodoUpdate(m, [{ id: "a", content: "A", status: "pending" }], { merge: false });
+      const changed = applyTodoUpdate(m, undefined, { merge: false });
+      expect(changed).toBe(true);
+      expect(Object.keys(m)).toHaveLength(0);
+    });
+  });
+
+  describe("defensive input handling", () => {
+    it("coerces non-object array entries to empty todos", () => {
+      const m = emptyMap();
+      const changed = applyTodoUpdate(m, ["oops", null, 42], { merge: false });
+      expect(changed).toBe(true);
+      expect(Object.keys(m)).toEqual(["todo-0", "todo-1", "todo-2"]);
+      expect(m["todo-0"].content).toBe("");
+      expect(m["todo-0"].status).toBe(TodoStatus.TODO_PENDING);
+    });
+  });
+
+  describe("dirty return value", () => {
+    it("returns true when items are written", () => {
+      expect(applyTodoUpdate(emptyMap(), [{ content: "A" }], { merge: false })).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,228 @@
+/**
+ * Unit tests for the CAS mid-run progress substrate (DD-33) — the non-git /
+ * gitignored half of the "N files changed so far" strip.
+ *
+ * The substrate reads a {@link CasTouchedSnapshot} (the same before-map the
+ * turn-boundary CAS capture reads) and the after-bytes off a real temp workspace,
+ * classifies each via the shared {@link classifyCasChange}, and reports a bounded
+ * read-prefix plus an honest `totalFilesChanged`. These cases prove: kind
+ * derivation, no-op/created-then-deleted exclusion, binary + oversize zeroing,
+ * secret exclusion, the read budget + tail total, revert-to-empty, and the
+ * size+mtime short-circuit.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { createCasProgressSubstrate, type CasTouchedSnapshot } from "../cas-progress.js";
+import { LINE_COUNT_MAX_BYTES } from "../line-counts.js";
+import type { ProgressEntry } from "../progress.js";
+
+let workspace: string;
+
+beforeEach(() => {
+  workspace = mkdtempSync(join(tmpdir(), "cas-progress-"));
+});
+
+afterEach(() => {
+  rmSync(workspace, { recursive: true, force: true });
+});
+
+function bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+/** Write after-bytes to disk (the observed net result of the turn). */
+function put(rel: string, content: string | Uint8Array): void {
+  const abs = join(workspace, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, typeof content === "string" ? content : Buffer.from(content));
+}
+
+/** A static reader over an explicit before-map + blocked set. */
+function reader(
+  before: Map<string, Uint8Array | null>,
+  blockedSecretPaths: ReadonlySet<string> = new Set(),
+): () => CasTouchedSnapshot {
+  return () => ({ before, blockedSecretPaths });
+}
+
+function entryFor(entries: readonly ProgressEntry[], path: string): ProgressEntry | undefined {
+  return entries.find((e) => e.pathAfter === path || e.pathBefore === path);
+}
+
+describe("createCasProgressSubstrate", () => {
+  it("classifies ADD / MODIFY / DELETE with line counts from the observer + disk", async () => {
+    // before-map: new.ts is new (null), main.ts + gone.ts existed.
+    const before = new Map<string, Uint8Array | null>([
+      ["src/new.ts", null],
+      ["src/main.ts", bytes("export const x = 1;\n")],
+      ["gone.ts", bytes("l1\nl2\nl3\n")],
+    ]);
+    put("src/new.ts", "a\nb\nc\n"); // ADD, +3
+    put("src/main.ts", "export const x = 2;\nexport const y = 3;\n"); // MODIFY
+    // gone.ts is left absent on disk -> DELETE
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta, changed } = await sub.capture();
+    expect(changed).toBe(true);
+    expect(delta.totalFilesChanged).toBe(3);
+    expect(delta.entries).toHaveLength(3);
+
+    const added = entryFor(delta.entries, "src/new.ts")!;
+    expect(added.kind).toBe(FileChangeKind.ADD);
+    expect(added.pathBefore).toBe("");
+    expect(added.linesAdded).toBe(3);
+    expect(added.linesRemoved).toBe(0);
+
+    const modified = entryFor(delta.entries, "src/main.ts")!;
+    expect(modified.kind).toBe(FileChangeKind.MODIFY);
+    expect(modified.linesAdded).toBeGreaterThan(0);
+
+    const deleted = entryFor(delta.entries, "gone.ts")!;
+    expect(deleted.kind).toBe(FileChangeKind.DELETE);
+    expect(deleted.pathAfter).toBe("");
+    expect(deleted.linesRemoved).toBe(3);
+  });
+
+  it("excludes a no-op touch (bytes unchanged) from entries and the total", async () => {
+    const before = new Map<string, Uint8Array | null>([
+      ["noop.ts", bytes("same\n")],
+      ["real.ts", bytes("a\n")],
+    ]);
+    put("noop.ts", "same\n"); // unchanged
+    put("real.ts", "a\nb\n"); // changed
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    expect(entryFor(delta.entries, "noop.ts")).toBeUndefined();
+    expect(entryFor(delta.entries, "real.ts")).toBeDefined();
+    expect(delta.totalFilesChanged).toBe(1);
+  });
+
+  it("excludes a created-then-deleted path (both sides absent)", async () => {
+    const before = new Map<string, Uint8Array | null>([["ephemeral.ts", null]]);
+    // never written to disk -> after is null, before is null -> no change
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    expect(delta.entries).toHaveLength(0);
+    expect(delta.totalFilesChanged).toBe(0);
+  });
+
+  it("zeroes counts for a binary file", async () => {
+    const before = new Map<string, Uint8Array | null>([["blob.bin", null]]);
+    put("blob.bin", new Uint8Array([0, 1, 2, 0, 255, 0]));
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    const bin = entryFor(delta.entries, "blob.bin")!;
+    expect(bin.kind).toBe(FileChangeKind.ADD);
+    expect(bin.linesAdded).toBe(0);
+    expect(bin.linesRemoved).toBe(0);
+  });
+
+  it("derives kind for an oversize after WITHOUT reading it (zeroed counts)", async () => {
+    const before = new Map<string, Uint8Array | null>([["huge.ts", null]]);
+    // One byte over the count ceiling: the substrate stats it, sees it is too
+    // large, and emits an ADD with zero counts rather than reading MBs.
+    put("huge.ts", "x".repeat(LINE_COUNT_MAX_BYTES + 1));
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    const huge = entryFor(delta.entries, "huge.ts")!;
+    expect(huge.kind).toBe(FileChangeKind.ADD);
+    expect(huge.linesAdded).toBe(0);
+    expect(huge.linesRemoved).toBe(0);
+    expect(delta.totalFilesChanged).toBe(1);
+  });
+
+  it("excludes gate-blocked secret paths up front", async () => {
+    const before = new Map<string, Uint8Array | null>([
+      [".env", null],
+      ["app.ts", null],
+    ]);
+    put(".env", "TOKEN=abc\n");
+    put("app.ts", "code\n");
+
+    const sub = createCasProgressSubstrate({
+      workspaceRoot: workspace,
+      read: reader(before, new Set([".env"])),
+    });
+    const { delta } = await sub.capture();
+    expect(entryFor(delta.entries, ".env")).toBeUndefined();
+    expect(entryFor(delta.entries, "app.ts")).toBeDefined();
+    expect(delta.totalFilesChanged).toBe(1);
+  });
+
+  it("also excludes a secret-like path even when not gate-blocked (backstop)", async () => {
+    // No gate-block set, but the path LOOKS secret-like: partitionIgnoredPathsBySecret
+    // withholds it (the global-bypass backstop).
+    const before = new Map<string, Uint8Array | null>([["config/id_rsa", null]]);
+    put("config/id_rsa", "-----BEGIN KEY-----\n");
+
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    expect(delta.entries).toHaveLength(0);
+    expect(delta.totalFilesChanged).toBe(0);
+  });
+
+  it("bounds reads to maxEntries but keeps totalFilesChanged honest over the tail", async () => {
+    const before = new Map<string, Uint8Array | null>();
+    for (let i = 0; i < 5; i++) {
+      const p = `f${String(i).padStart(2, "0")}.ts`;
+      before.set(p, null);
+      put(p, `content ${i}\n`);
+    }
+    const sub = createCasProgressSubstrate({
+      workspaceRoot: workspace,
+      read: reader(before),
+      maxEntries: 2,
+    });
+    const { delta } = await sub.capture();
+    // Only the sorted prefix is read into entries…
+    expect(delta.entries).toHaveLength(2);
+    expect(delta.entries.map((e) => e.pathAfter)).toEqual(["f00.ts", "f01.ts"]);
+    // …but the honest total covers every capturable file.
+    expect(delta.totalFilesChanged).toBe(5);
+  });
+
+  it("returns a zero-file delta after the agent reverts its own edits", async () => {
+    const before = new Map<string, Uint8Array | null>([["r.ts", null]]);
+    // r.ts observed but never left on disk (reverted) -> after null, before null.
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    const { delta } = await sub.capture();
+    expect(delta.totalFilesChanged).toBe(0);
+    expect(delta.entries).toHaveLength(0);
+  });
+
+  it("short-circuits (changed:false) when the touched set + prefix stats are unchanged", async () => {
+    const before = new Map<string, Uint8Array | null>([["a.ts", null]]);
+    put("a.ts", "hello\n");
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+
+    const first = await sub.capture();
+    expect(first.changed).toBe(true);
+
+    const second = await sub.capture();
+    expect(second.changed).toBe(false);
+    // The cached full delta is still returned so the hybrid can merge it.
+    expect(second.delta.totalFilesChanged).toBe(1);
+  });
+
+  it("re-reports changed:true when a NEW path is touched (e.g. a sub-agent write)", async () => {
+    const before = new Map<string, Uint8Array | null>([["a.ts", null]]);
+    put("a.ts", "hello\n");
+    const sub = createCasProgressSubstrate({ workspaceRoot: workspace, read: reader(before) });
+    await sub.capture();
+
+    // A concurrent write adds a new observed path.
+    before.set("b.ts", null);
+    put("b.ts", "world\n");
+    const next = await sub.capture();
+    expect(next.changed).toBe(true);
+    expect(next.delta.totalFilesChanged).toBe(2);
+  });
+});