@stigmer/runner 3.1.1 → 3.1.3

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

@@ -14,7 +14,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { clone, create } from "@bufbuild/protobuf";
+import { clone, create, toBinary } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
@@ -28,6 +28,7 @@ import {
   FileCaptureClass,
   FileChangeKind,
   FileChangeSetStatus,
+  FileChangeType,
   FileDecisionAction,
   FileDecisionScope,
   FileReviewBlockReason,
@@ -41,7 +42,9 @@ import {
   captureBaselineToLedger,
   captureCandidateToLedger,
   deriveCaptureMode,
+  partitionGitChangesBySecret,
 } from "../capture.js";
+import type { GitSubstrateChange } from "../git-substrate.js";
 import { casBlobReader } from "../cas-substrate.js";
 
 const execFileAsync = promisify(execFile);
@@ -609,6 +612,184 @@ describe("capture orchestration — secret-blocked DIFF_UNREVIEWABLE (DD-E)", ()
   });
 });
 
+// A git-TRACKED secret-like file (a committed credentials.json, .env.example,
+// ...) FLOWS in capture mode (the gate allows tracked mutations with no secret
+// check), so it reaches the turn boundary in the git diff WITH real bytes. Those
+// bytes must never enter the ledger: the capture seam authors it content-less
+// (SECRET_WITHHELD / GIT_TRACKED), discard-only, and the git substrate reverts
+// it byte-exact on reject. This is the one place that can withhold a DELETE's
+// baseline (before) secret too — the gate never sees a delete's content.
+// (DD-26 follow-up #3.)
+describe("capture orchestration — git-tracked secret withheld (DD-26 follow-up #3)", () => {
+  const SECRET_PATH = "config/credentials.json";
+  const BASELINE_SECRET = "OLD_API_KEY=sk-live-OLDSECRET-do-not-persist-111\n";
+  const NEW_SECRET = "NEW_API_KEY=sk-live-NEWSECRET-do-not-persist-222\n";
+
+  async function commitBaselineSecret(): Promise<void> {
+    await write(SECRET_PATH, BASELINE_SECRET);
+    await git(["add", "-A"]);
+    await git(["commit", "-q", "-m", "add tracked secret"]);
+  }
+
+  // Serialize the WHOLE persisted status (ledger + any rows) and assert neither
+  // the baseline nor the new secret bytes survive anywhere — the leak-scan that
+  // would FAIL before this fix (the git diff carried the inline body).
+  function assertNoSecretBytes(status: AgentExecutionStatus): void {
+    const wire = Buffer.from(toBinary(AgentExecutionStatusSchema, status));
+    expect(wire.includes(Buffer.from(BASELINE_SECRET))).toBe(false);
+    expect(wire.includes(Buffer.from(NEW_SECRET))).toBe(false);
+  }
+
+  it("MODIFY: content-less SECRET_WITHHELD/GIT_TRACKED entry; PARTIAL_BLOCKED; nothing persisted", async () => {
+    await commitBaselineSecret();
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS,
+    });
+    await write(SECRET_PATH, NEW_SECRET); // the agent edits the committed secret
+
+    await captureCandidateToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+      baselineTree: baseline, harnessId: HARNESS,
+    });
+
+    const entry = candidateChanges(status).find((c) => (c.pathAfter || c.pathBefore) === SECRET_PATH)!;
+    expect(entry).toBeDefined();
+    expect(entry.captureClass).toBe(FileCaptureClass.GIT_TRACKED);
+    expect(entry.kind).toBe(FileChangeKind.MODIFY);
+    expect(entry.diffComplete).toBe(false);
+    expect(entry.blockedReason).toBe(FileReviewBlockReason.SECRET_WITHHELD);
+    // No content and no enforcement digests on EITHER side (before is secret too).
+    expect(entry.before).toBeUndefined();
+    expect(entry.after).toBeUndefined();
+    expect(entry.beforeSha256).toBe("");
+    expect(entry.afterSha256).toBe("");
+    expect(candidateCompleteness(status)).toBe(DiffCompleteness.PARTIAL_BLOCKED);
+    assertNoSecretBytes(status);
+  });
+
+  it("CREATE: a newly-created tracked secret is content-less (kind ADD, no after bytes)", async () => {
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS,
+    });
+    await write(SECRET_PATH, NEW_SECRET); // brand-new secret file this turn
+
+    await captureCandidateToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+      baselineTree: baseline, harnessId: HARNESS,
+    });
+
+    const entry = candidateChanges(status).find((c) => (c.pathAfter || c.pathBefore) === SECRET_PATH)!;
+    expect(entry.kind).toBe(FileChangeKind.ADD);
+    expect(entry.captureClass).toBe(FileCaptureClass.GIT_TRACKED);
+    expect(entry.diffComplete).toBe(false);
+    expect(entry.blockedReason).toBe(FileReviewBlockReason.SECRET_WITHHELD);
+    expect(entry.after).toBeUndefined();
+    expect(entry.afterSha256).toBe("");
+    expect(candidateCompleteness(status)).toBe(DiffCompleteness.PARTIAL_BLOCKED);
+    assertNoSecretBytes(status);
+  });
+
+  it("DELETE: withholds the deleted file's baseline (before) secret bytes (kind DELETE)", async () => {
+    await commitBaselineSecret();
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS,
+    });
+    await rm(join(repo, SECRET_PATH), { force: true }); // the agent deletes the secret
+
+    await captureCandidateToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+      baselineTree: baseline, harnessId: HARNESS,
+    });
+
+    const entry = candidateChanges(status).find((c) => c.pathBefore === SECRET_PATH)!;
+    expect(entry).toBeDefined();
+    expect(entry.kind).toBe(FileChangeKind.DELETE);
+    expect(entry.captureClass).toBe(FileCaptureClass.GIT_TRACKED);
+    expect(entry.diffComplete).toBe(false);
+    // The DELETE's `before` side is the committed secret — the leak only this
+    // seam can withhold (the gate never sees a delete's content).
+    expect(entry.before).toBeUndefined();
+    expect(entry.beforeSha256).toBe("");
+    expect(candidateCompleteness(status)).toBe(DiffCompleteness.PARTIAL_BLOCKED);
+    assertNoSecretBytes(status);
+  });
+
+  it("mixed set: the non-secret file stays keepable; the secret reverts byte-exact on reject", async () => {
+    await commitBaselineSecret();
+    const status = newStatus();
+    const baseline = await captureBaselineToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS,
+    });
+    await write("notes.md", "planton notes\n"); // reviewable tracked change
+    await write(SECRET_PATH, NEW_SECRET); // withheld tracked secret change
+
+    await captureCandidateToLedger({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID,
+      baselineTree: baseline, harnessId: HARNESS,
+    });
+
+    const byPath = new Map(candidateChanges(status).map((c) => [c.pathAfter || c.pathBefore, c]));
+    // The non-secret file is fully reviewable/keepable (content present).
+    expect(byPath.get("notes.md")!.diffComplete).toBe(true);
+    expect(byPath.get("notes.md")!.after).toBeDefined();
+    expect(byPath.get("notes.md")!.blockedReason).toBe(FileReviewBlockReason.UNSPECIFIED);
+    // The secret rides alongside content-less, forcing the set PARTIAL_BLOCKED.
+    expect(byPath.get(SECRET_PATH)!.diffComplete).toBe(false);
+    expect(byPath.get(SECRET_PATH)!.blockedReason).toBe(FileReviewBlockReason.SECRET_WITHHELD);
+    expect(candidateCompleteness(status)).toBe(DiffCompleteness.PARTIAL_BLOCKED);
+    assertNoSecretBytes(status);
+
+    // Keep the reviewable file; discard the secret. The git substrate reverts the
+    // secret to its committed baseline BYTE-EXACT (not deleted) and keeps notes.md.
+    const changeSet = decidedChangeSet(status, {
+      "notes.md": FileDecisionAction.APPROVE,
+      [SECRET_PATH]: FileDecisionAction.REJECT,
+    });
+    const result = await applyCaptureDecisions({
+      status, gitRoot: repo, executionId: EXEC_ID, changeSet, harnessId: HARNESS,
+    });
+
+    expect(result.failed).toBe(false);
+    expect(result.approvedPaths).toEqual(["notes.md"]);
+    expect(result.rejectedPaths).toEqual([SECRET_PATH]);
+    expect(await read("notes.md")).toBe("planton notes\n");
+    expect(await read(SECRET_PATH)).toBe(BASELINE_SECRET); // reverted byte-exact
+    // Even after reconcile, no secret bytes are anywhere in the persisted status.
+    assertNoSecretBytes(status);
+  });
+});
+
+// partitionGitChangesBySecret: the pure split the composition relies on.
+describe("partitionGitChangesBySecret (pure)", () => {
+  const mk = (path: string): GitSubstrateChange => ({
+    path,
+    changeType: FileChangeType.MODIFY,
+    before: { kind: "inline", text: "a" },
+    after: { kind: "inline", text: "b" },
+  });
+
+  it("routes secret-like paths to `secret` and everything else to `safe`", () => {
+    const { safe, secret } = partitionGitChangesBySecret([
+      mk("src/main.ts"),
+      mk("config/credentials.json"),
+      mk(".env"),
+      mk("README.md"),
+      mk("keys/id_rsa"),
+    ]);
+    expect(safe.map((c) => c.path)).toEqual(["src/main.ts", "README.md"]);
+    expect(secret.map((c) => c.path)).toEqual(["config/credentials.json", ".env", "keys/id_rsa"]);
+  });
+
+  it("returns everything safe when no path is secret-like", () => {
+    const { safe, secret } = partitionGitChangesBySecret([mk("a.ts"), mk("b/c.md")]);
+    expect(safe).toHaveLength(2);
+    expect(secret).toHaveLength(0);
+  });
+});
+
 // Slice 2a (DD-21 D2): the shared orchestration must capture and reconcile a
 // NON-GIT workspace entirely from the CAS manifest — no git refs, no whole-tree
 // snapshot, bounded to the paths the observer actually touched. These exercise

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

@@ -97,6 +97,40 @@ describe("snapshotCasChangeSet — classification", () => {
     expect(del.before?.sha256).toBe(sha256Bytes(bytes("BYE=1")));
   });
 
+  it("counts display line changes from the in-memory bytes at capture", async () => {
+    const { storage } = makeFakeStorage();
+    const { manifest } = await snapshotCasChangeSet({
+      storage,
+      executionId: EXEC,
+      changeSetId: CHANGE_SET,
+      captures: [
+        { path: "created.env", before: null, after: bytes("A=1\nB=2\n"), captureClass: IGNORED },
+        { path: "changed.env", before: bytes("OLD=1\n"), after: bytes("OLD=2\n"), captureClass: IGNORED },
+        // Binary side: no text diff exists, so no counts may claim one does.
+        { path: "blob.bin", before: null, after: new Uint8Array([0, 1, 2]), captureClass: IGNORED },
+      ],
+    });
+    const byPath = new Map(manifest.files.map((f) => [f.pathAfter || f.pathBefore, f]));
+
+    expect(byPath.get("created.env")!.lineCounts).toEqual({ linesAdded: 2, linesRemoved: 0 });
+    expect(byPath.get("changed.env")!.lineCounts).toEqual({ linesAdded: 1, linesRemoved: 1 });
+    expect(byPath.get("blob.bin")!.lineCounts).toBeUndefined();
+  });
+
+  it("keeps line counts out of the persisted manifest (display data, not an enforcement record)", async () => {
+    const { storage, readBlob } = makeFakeStorage();
+    const { ref } = await snapshotCasChangeSet({
+      storage,
+      executionId: EXEC,
+      changeSetId: CHANGE_SET,
+      captures: [
+        { path: "changed.env", before: bytes("OLD=1\n"), after: bytes("OLD=2\n"), captureClass: IGNORED },
+      ],
+    });
+    const roundTripped = await loadCasManifest({ readBlob, ref });
+    expect(roundTripped.files[0].lineCounts).toBeUndefined();
+  });
+
   it("drops a touched-but-unchanged path (before == after)", async () => {
     const { storage } = makeFakeStorage();
     const { manifest } = await snapshotCasChangeSet({

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

@@ -138,6 +138,111 @@ describe("buildCapturedFileChange", () => {
     }
   });
 
+  it("stamps display line counts from inline sides", () => {
+    const modify = buildCapturedFileChange({
+      id: "fc-counts",
+      pathBefore: "src/a.ts",
+      pathAfter: "src/a.ts",
+      kind: FileChangeKind.MODIFY,
+      captureClass: FileCaptureClass.GIT_TRACKED,
+      before: "one\ntwo\n",
+      after: "one\nTWO\nthree\n",
+    });
+    expect(modify.linesAdded).toBe(2);
+    expect(modify.linesRemoved).toBe(1);
+
+    const add = buildCapturedFileChange({
+      id: "fc-add-counts",
+      pathBefore: "",
+      pathAfter: "src/new.ts",
+      kind: FileChangeKind.ADD,
+      captureClass: FileCaptureClass.GIT_TRACKED,
+      after: "a\nb\nc\n",
+    });
+    expect(add.linesAdded).toBe(3);
+    expect(add.linesRemoved).toBe(0);
+  });
+
+  it("prefers explicit lineCounts (the CAS substrate's capture-time counts) over inline counting", () => {
+    const change = buildCapturedFileChange({
+      id: "fc-explicit",
+      pathBefore: "notes.txt",
+      pathAfter: "notes.txt",
+      kind: FileChangeKind.MODIFY,
+      captureClass: FileCaptureClass.NON_GIT_CAS,
+      before: {
+        kind: "ref", sha256: "s1", storageKey: "k1", sizeBytes: 10, isBinary: false,
+      },
+      after: {
+        kind: "ref", sha256: "s2", storageKey: "k2", sizeBytes: 12, isBinary: false,
+      },
+      lineCounts: { linesAdded: 7, linesRemoved: 4 },
+    });
+    expect(change.linesAdded).toBe(7);
+    expect(change.linesRemoved).toBe(4);
+  });
+
+  it("leaves counts at zero when a side is not countable (binary / ref without explicit counts / withheld)", () => {
+    // Binary side: no text diff exists, so no count may claim one does.
+    const binary = binaryChange("bin");
+    expect(binary.linesAdded).toBe(0);
+    expect(binary.linesRemoved).toBe(0);
+
+    // Ref side without explicit counts: the bytes are not here to count.
+    const ref = buildCapturedFileChange({
+      id: "fc-ref",
+      pathBefore: "big.txt",
+      pathAfter: "big.txt",
+      kind: FileChangeKind.MODIFY,
+      captureClass: FileCaptureClass.NON_GIT_CAS,
+      before: { kind: "ref", sha256: "s1", storageKey: "k1", sizeBytes: 9, isBinary: false },
+      after: { kind: "ref", sha256: "s2", storageKey: "k2", sizeBytes: 9, isBinary: false },
+    });
+    expect(ref.linesAdded).toBe(0);
+    expect(ref.linesRemoved).toBe(0);
+
+    // Secret-withheld: content-less by design.
+    const withheld = unavailableChange("secret");
+    expect(withheld.linesAdded).toBe(0);
+    expect(withheld.linesRemoved).toBe(0);
+  });
+
+  it("keeps line counts out of the enforcement digests (informational only)", () => {
+    const common = {
+      id: "fc-digest",
+      pathBefore: "a",
+      pathAfter: "a",
+      kind: FileChangeKind.MODIFY,
+      captureClass: FileCaptureClass.NON_GIT_CAS,
+      before: {
+        kind: "ref", sha256: "s1", storageKey: "k1", sizeBytes: 3, isBinary: false,
+      },
+      after: {
+        kind: "ref", sha256: "s2", storageKey: "k2", sizeBytes: 3, isBinary: false,
+      },
+    } as const;
+    // Identical content with and without counts must be digest-indistinguishable —
+    // structurally guaranteed (FileDigestInput excludes counts), locked here so a
+    // future refactor cannot silently fold display data into enforcement.
+    const withoutCounts = buildCapturedFileChange(common);
+    const withCounts = buildCapturedFileChange({
+      ...common,
+      lineCounts: { linesAdded: 5, linesRemoved: 2 },
+    });
+    expect(withCounts.fileDigest).toBe(withoutCounts.fileDigest);
+
+    const aggWithout = buildCandidateCapturedEvent(ctx, undefined, [withoutCounts]);
+    const aggWith = buildCandidateCapturedEvent(ctx, undefined, [withCounts]);
+    if (
+      aggWithout.payload.case === "candidateCaptured" &&
+      aggWith.payload.case === "candidateCaptured"
+    ) {
+      expect(aggWith.payload.value.aggregateDigest).toBe(
+        aggWithout.payload.value.aggregateDigest,
+      );
+    }
+  });
+
   it("omits the before side for an ADD and the after side for a DELETE", () => {
     const add = buildCapturedFileChange({
       id: "fc-add",

package/src/shared/filereview/__tests__/line-counts.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Capture-time line counting: the `+N −M` semantics must mirror what the SDK's
+ * jsdiff-based diff renderer shows (same algorithm, same "\ No newline"
+ * exclusion), with absent sides treated as the empty document and a byte-size
+ * guard that skips counting rather than stalling capture.
+ */
+
+import { describe, expect, it } from "vitest";
+import { countLineChanges, LINE_COUNT_MAX_BYTES } from "../line-counts.js";
+
+describe("countLineChanges", () => {
+  it("counts a plain modify", () => {
+    expect(countLineChanges("a\nb\nc\n", "a\nB\nc\nd\n")).toEqual({
+      linesAdded: 2,
+      linesRemoved: 1,
+    });
+  });
+
+  it("counts an ADD (absent before) as all lines added", () => {
+    expect(countLineChanges(undefined, "one\ntwo\nthree\n")).toEqual({
+      linesAdded: 3,
+      linesRemoved: 0,
+    });
+  });
+
+  it("counts a DELETE (absent after) as all lines removed", () => {
+    expect(countLineChanges("one\ntwo\n", undefined)).toEqual({
+      linesAdded: 0,
+      linesRemoved: 2,
+    });
+  });
+
+  it("returns zero counts for identical sides", () => {
+    expect(countLineChanges("same\n", "same\n")).toEqual({
+      linesAdded: 0,
+      linesRemoved: 0,
+    });
+  });
+
+  it("returns undefined when both sides are absent", () => {
+    expect(countLineChanges(undefined, undefined)).toBeUndefined();
+  });
+
+  it("excludes the no-trailing-newline marker from the counts", () => {
+    // "a" -> "a\n": jsdiff models this as the "a" line replaced (one removed,
+    // one added) plus "\ No newline" metadata, which must not be counted —
+    // exactly the population the SDK's mapPatchHunks renders.
+    expect(countLineChanges("a", "a\n")).toEqual({
+      linesAdded: 1,
+      linesRemoved: 1,
+    });
+  });
+
+  it("counts an added file with no trailing newline by its real line count", () => {
+    expect(countLineChanges(undefined, "one\ntwo")).toEqual({
+      linesAdded: 2,
+      linesRemoved: 0,
+    });
+  });
+
+  it("skips counting when a side exceeds the byte guard", () => {
+    const huge = "x\n".repeat(LINE_COUNT_MAX_BYTES / 2 + 1);
+    expect(countLineChanges(huge, "small\n")).toBeUndefined();
+    expect(countLineChanges("small\n", huge)).toBeUndefined();
+  });
+
+  it("guards on UTF-8 byte length, not character count", () => {
+    // Each "€" is 3 bytes; a string just over the guard in bytes while well
+    // under it in characters must still be skipped.
+    const wide = "€".repeat(Math.ceil(LINE_COUNT_MAX_BYTES / 3) + 1);
+    expect(countLineChanges(wide, "")).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,236 @@
+/**
+ * Unit tests for mid-run live capture (DD-32):
+ *  - `captureProgressDelta` (git-substrate) against a REAL temp git repo — the
+ *    only faithful test for git plumbing (kinds, counts, binary, rename→add+del,
+ *    tree-unchanged short-circuit, excludePaths).
+ *  - `buildFileChangeProgress` (pure) — secret zeroing, entry cap with honest
+ *    totals, aggregate sums.
+ *  - `shouldCaptureProgress` (pure) — the debounce floor.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { beforeEach, afterEach, describe, expect, it } from "vitest";
+import { FileChangeKind, FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  captureProgressDelta,
+  snapshotBaseline,
+  dropCaptureRefs,
+  type GitProgressEntry,
+  type ProgressDelta,
+} from "../git-substrate.js";
+import {
+  buildFileChangeProgress,
+  PROGRESS_MAX_ENTRIES,
+  shouldCaptureProgress,
+} from "../progress.js";
+
+const execFileAsync = promisify(execFile);
+const EXEC_ID = "exec-progress-1";
+const CHANGE_SET_ID = "exec-progress-1:0";
+const RUNNER_OWNED_PATHS: readonly string[] = [".cursor/hooks.json"];
+
+let repo: string;
+
+async function git(args: string[]): Promise<void> {
+  await execFileAsync("git", args, { cwd: repo });
+}
+
+async function write(rel: string, content: string): Promise<void> {
+  await mkdir(join(repo, rel, ".."), { recursive: true });
+  await writeFile(join(repo, rel), content, "utf-8");
+}
+
+async function writeBytes(rel: string, bytes: Uint8Array): Promise<void> {
+  await mkdir(join(repo, rel, ".."), { recursive: true });
+  await writeFile(join(repo, rel), bytes);
+}
+
+function entryFor(delta: ProgressDelta, path: string): GitProgressEntry | undefined {
+  return delta.entries.find((e) => e.pathAfter === path || e.pathBefore === path);
+}
+
+beforeEach(async () => {
+  repo = await mkdtemp(join(tmpdir(), "stigmer-progress-"));
+  await git(["init", "-q"]);
+  await git(["config", "user.email", "t@t.local"]);
+  await git(["config", "user.name", "t"]);
+  await write("src/main.ts", "export const x = 1;\n");
+  await write("keep.txt", "line1\nline2\nline3\n");
+  await git(["add", "-A"]);
+  await git(["commit", "-q", "-m", "initial"]);
+});
+
+afterEach(async () => {
+  await dropCaptureRefs(repo, EXEC_ID).catch(() => {});
+  await rm(repo, { recursive: true, force: true });
+});
+
+describe("captureProgressDelta (real git repo)", () => {
+  it("reports ADD / MODIFY / DELETE with line counts and honest path sides", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+
+    await write("src/new.ts", "a\nb\nc\n"); // ADD (3 added)
+    await write("src/main.ts", "export const x = 2;\nexport const y = 3;\n"); // MODIFY
+    await rm(join(repo, "keep.txt")); // DELETE (3 removed)
+
+    const delta = await captureProgressDelta(repo, EXEC_ID, baseline);
+    expect(delta).toBeDefined();
+    expect(delta!.entries).toHaveLength(3);
+
+    const added = entryFor(delta!, "src/new.ts")!;
+    expect(added.changeType).toBe(FileChangeType.CREATE);
+    expect(added.pathBefore).toBe("");
+    expect(added.pathAfter).toBe("src/new.ts");
+    expect(added.linesAdded).toBe(3);
+    expect(added.linesRemoved).toBe(0);
+
+    const modified = entryFor(delta!, "src/main.ts")!;
+    expect(modified.changeType).toBe(FileChangeType.MODIFY);
+    expect(modified.pathBefore).toBe("src/main.ts");
+    expect(modified.pathAfter).toBe("src/main.ts");
+    expect(modified.linesAdded).toBeGreaterThan(0);
+
+    const deleted = entryFor(delta!, "keep.txt")!;
+    expect(deleted.changeType).toBe(FileChangeType.DELETE);
+    expect(deleted.pathBefore).toBe("keep.txt");
+    expect(deleted.pathAfter).toBe("");
+    expect(deleted.linesRemoved).toBe(3);
+    expect(deleted.linesAdded).toBe(0);
+  });
+
+  it("surfaces a binary change with zero counts (numstat reports '-')", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+    await writeBytes("blob.bin", new Uint8Array([0, 1, 2, 0, 255, 0, 3]));
+
+    const delta = await captureProgressDelta(repo, EXEC_ID, baseline);
+    const bin = entryFor(delta!, "blob.bin")!;
+    expect(bin.changeType).toBe(FileChangeType.CREATE);
+    expect(bin.linesAdded).toBe(0);
+    expect(bin.linesRemoved).toBe(0);
+  });
+
+  it("splits a rename into a delete + create (--no-renames)", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+    await rm(join(repo, "keep.txt"));
+    await write("renamed.txt", "line1\nline2\nline3\n");
+
+    const delta = await captureProgressDelta(repo, EXEC_ID, baseline);
+    expect(entryFor(delta!, "keep.txt")!.changeType).toBe(FileChangeType.DELETE);
+    expect(entryFor(delta!, "renamed.txt")!.changeType).toBe(FileChangeType.CREATE);
+  });
+
+  it("short-circuits (returns undefined) when the tree is unchanged since lastTreeSha", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+    await write("src/new.ts", "a\nb\n");
+
+    const first = await captureProgressDelta(repo, EXEC_ID, baseline);
+    expect(first).toBeDefined();
+
+    const second = await captureProgressDelta(repo, EXEC_ID, baseline, [], first!.afterTree);
+    expect(second).toBeUndefined();
+  });
+
+  it("recomputes (0 entries) after the agent reverts its own edits", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID);
+    await write("src/new.ts", "a\nb\n");
+    const first = await captureProgressDelta(repo, EXEC_ID, baseline);
+
+    await rm(join(repo, "src/new.ts")); // revert to clean
+    const second = await captureProgressDelta(repo, EXEC_ID, baseline, [], first!.afterTree);
+    expect(second).toBeDefined();
+    expect(second!.entries).toHaveLength(0);
+  });
+
+  it("excludes runner-owned gate files from the delta", async () => {
+    const baseline = await snapshotBaseline(repo, EXEC_ID, RUNNER_OWNED_PATHS);
+    await write(".cursor/hooks.json", "{}\n");
+    await write("real.ts", "x\n");
+
+    const delta = await captureProgressDelta(repo, EXEC_ID, baseline, RUNNER_OWNED_PATHS);
+    expect(entryFor(delta!, ".cursor/hooks.json")).toBeUndefined();
+    expect(entryFor(delta!, "real.ts")).toBeDefined();
+  });
+});
+
+describe("buildFileChangeProgress (pure)", () => {
+  function delta(entries: GitProgressEntry[]): ProgressDelta {
+    return { afterTree: "tree-sha", entries };
+  }
+  function entry(path: string, added: number, removed: number): GitProgressEntry {
+    return {
+      pathBefore: path,
+      pathAfter: path,
+      changeType: FileChangeType.MODIFY,
+      linesAdded: added,
+      linesRemoved: removed,
+    };
+  }
+
+  it("sums aggregate counts and maps kind", () => {
+    const progress = buildFileChangeProgress(
+      delta([
+        { pathBefore: "", pathAfter: "a.ts", changeType: FileChangeType.CREATE, linesAdded: 5, linesRemoved: 0 },
+        entry("b.ts", 2, 3),
+      ]),
+      CHANGE_SET_ID,
+    );
+    expect(progress.changeSetId).toBe(CHANGE_SET_ID);
+    expect(progress.filesChanged).toBe(2);
+    expect(progress.linesAdded).toBe(7);
+    expect(progress.linesRemoved).toBe(3);
+    expect(progress.entries[0].kind).toBe(FileChangeKind.ADD);
+    expect(progress.entries[1].kind).toBe(FileChangeKind.MODIFY);
+    expect(progress.capturedAt).not.toBe("");
+  });
+
+  it("zeroes counts for secret-like paths (path visible, magnitude withheld)", () => {
+    const progress = buildFileChangeProgress(
+      delta([entry(".env", 10, 2), entry("app.ts", 4, 1)]),
+      CHANGE_SET_ID,
+    );
+    // The secret path is still counted as a changed file and its path is present…
+    expect(progress.filesChanged).toBe(2);
+    const secret = progress.entries.find((e) => e.pathAfter === ".env")!;
+    expect(secret.linesAdded).toBe(0);
+    expect(secret.linesRemoved).toBe(0);
+    // …but its magnitude is excluded from the aggregate.
+    expect(progress.linesAdded).toBe(4);
+    expect(progress.linesRemoved).toBe(1);
+  });
+
+  it("caps entries but keeps files_changed and totals honest over all files", () => {
+    const entries: GitProgressEntry[] = [];
+    for (let i = 0; i < PROGRESS_MAX_ENTRIES + 25; i++) {
+      entries.push(entry(`f${i}.ts`, 1, 1));
+    }
+    const progress = buildFileChangeProgress(delta(entries), CHANGE_SET_ID);
+    expect(progress.entries).toHaveLength(PROGRESS_MAX_ENTRIES);
+    expect(progress.filesChanged).toBe(PROGRESS_MAX_ENTRIES + 25);
+    expect(progress.linesAdded).toBe(PROGRESS_MAX_ENTRIES + 25);
+    expect(progress.linesRemoved).toBe(PROGRESS_MAX_ENTRIES + 25);
+  });
+
+  it("produces a zero-file snapshot for an empty delta (revert-to-clean)", () => {
+    const progress = buildFileChangeProgress(delta([]), CHANGE_SET_ID);
+    expect(progress.filesChanged).toBe(0);
+    expect(progress.entries).toHaveLength(0);
+  });
+});
+
+describe("shouldCaptureProgress (pure)", () => {
+  it("always captures on the first call (lastAtMs = 0, real clock)", () => {
+    // The caller starts a fresh turn with lastAtMs = 0 and now = Date.now(),
+    // which is always far past any floor.
+    expect(shouldCaptureProgress(0, Date.now(), 2000)).toBe(true);
+  });
+
+  it("gates within the floor and allows once it elapses", () => {
+    expect(shouldCaptureProgress(1000, 2500, 2000)).toBe(false);
+    expect(shouldCaptureProgress(1000, 3000, 2000)).toBe(true);
+    expect(shouldCaptureProgress(1000, 3001, 2000)).toBe(true);
+  });
+});