@stigmer/runner 3.1.2 → 3.1.3

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);
+  });
+});

package/src/shared/filereview/capture.ts

@@ -77,6 +77,7 @@ import {
   type CasPathCapture,
   type CasSnapshotRef,
 } from "./cas-substrate.js";
+import { isSecretLikePath } from "./secret-paths.js";
 
 /**
  * Whether a turn runs in apply-then-review CAPTURE mode (file edits flow and are
@@ -244,21 +245,41 @@ export async function captureCandidateToLedger(opts: {
 
   const unreviewable = unreviewablePaths ?? [];
 
+  // Secret handling is three-way across the substrates, and this is the last of
+  // the three (the other two happen upstream at the harness gate):
+  //   1. A gitignored secret WRITE never flows — hard-blocked at the gate /
+  //      deny-gate (DD-12/DD-30). It arrives here only as a path in
+  //      `unreviewablePaths` (recorded by the gate), authored content-less below.
+  //   2. A gitignored secret that flowed under the global bypass is withheld from
+  //      CAS by `partitionIgnoredPathsBySecret` (secret-paths.ts), so its bytes
+  //      never reach `casCaptures`.
+  //   3. A git-TRACKED secret DID flow (the capture-mode gate allows tracked
+  //      mutations with no secret check) and is present in `gitChanges` with real
+  //      bytes. We split it out here and author it content-less, so its content
+  //      never reaches the ledger. Unlike a gitignored secret it HAS a reversible
+  //      substrate (the git refs), so it is withheld-and-reverted rather than
+  //      never-applied — same never-persisted guarantee, appropriate mechanism.
+  const { safe: safeGitChanges, secret: secretGitChanges } =
+    partitionGitChangesBySecret(gitChanges);
+
   // A turn that changed nothing (no tracked/ignored change and no blocked path)
-  // authors no event.
+  // authors no event. A secret-only tracked turn is NOT a no-op — its file is in
+  // `gitChanges`, so the guard below is false and it authors a blocked entry.
   if (gitChanges.length === 0 && casFiles.length === 0 && unreviewable.length === 0) {
     return gitChanges;
   }
 
-  // One combined change set: git-tracked (inline bodies) + CAS (blob refs) +
-  // secret-blocked (content-less, DIFF_UNREVIEWABLE). The aggregate digest folds
-  // all (buildCandidateCapturedEvent sorts by file digest), so the reviewed diff
-  // and its identity span every substrate. deriveDiffCompleteness then rolls the
-  // per-file signals up three ways: any content-less (non-binary) entry forces
-  // PARTIAL_BLOCKED; a set blocked only by binaries is BINARY_SUMMARY_ONLY
-  // (keepable in one acknowledged action); else COMPLETE.
+  // One combined change set: git-tracked (inline bodies) + git-tracked-secret
+  // (content-less) + CAS (blob refs) + gitignored-secret-blocked (content-less).
+  // The aggregate digest folds all (buildCandidateCapturedEvent sorts by file
+  // digest), so the reviewed diff and its identity span every substrate.
+  // deriveDiffCompleteness then rolls the per-file signals up three ways: any
+  // content-less (non-binary) entry forces PARTIAL_BLOCKED; a set blocked only by
+  // binaries is BINARY_SUMMARY_ONLY (keepable in one acknowledged action); else
+  // COMPLETE.
   const captured = [
-    ...gitChanges.map((c) => buildCapturedFileChange(toCapturedChangeInput(changeSetId, c))),
+    ...safeGitChanges.map((c) => buildCapturedFileChange(toCapturedChangeInput(changeSetId, c))),
+    ...secretGitChanges.map((c) => buildCapturedFileChange(trackedSecretChangeInput(changeSetId, c))),
     ...casFiles.map((f) => buildCapturedFileChange(casToCapturedChangeInput(changeSetId, f))),
     ...unreviewable.map((p) => buildCapturedFileChange(unreviewableChangeInput(changeSetId, p, unreviewableCaptureClass))),
   ];
@@ -622,7 +643,9 @@ function candidateCasRef(changeSet: FileChangeSet): CasSnapshotRef | undefined {
  * after bodies are carried as blob REFS (already offloaded to artifact storage
  * by the CAS substrate), never re-inlined — so the CANDIDATE event stays small
  * and the bytes are stored exactly once. Enforcement digests come from the blob
- * content addresses, identical in form to the git path.
+ * content addresses, identical in form to the git path. The display line counts
+ * ride along explicitly — a ref side has no inline text for the producer to
+ * count, so the substrate's capture-time counts are the only honest source.
  */
 function casToCapturedChangeInput(
   changeSetId: string,
@@ -634,6 +657,7 @@ function casToCapturedChangeInput(
     pathAfter: file.pathAfter,
     kind: file.kind,
     captureClass: file.captureClass,
+    lineCounts: file.lineCounts,
     before: file.before
       ? {
           kind: "ref",
@@ -657,37 +681,117 @@ function casToCapturedChangeInput(
 }
 
 /**
- * Map a secret-blocked gitignored path to a content-less producer input (design
- * doc 12, DD-E). The bytes are deliberately never captured, so both sides are
- * absent (empty enforcement digests) and `diffComplete=false`. Being non-binary
- * incomplete with no keepable bytes, it forces the change set to PARTIAL_BLOCKED
- * (never BINARY_SUMMARY_ONLY) — approval is blocked and the path is surfaced
- * honestly, while its CONTENT never enters the ledger or storage. `blockedReason` records
- * the honest cause (SECRET_WITHHELD) so the review UI can say *why* rather than
- * showing a cause-agnostic "unavailable" (doc 15). Kind is MODIFY: the write was
- * blocked before it ran, so create-vs-modify is unknown and irrelevant (nothing
- * is ever applied or reconciled for this entry). `captureClass` is the turn's CAS
- * substrate class (GIT_IGNORED_CAPTURED | NON_GIT_CAS) so the blocked path is
- * labeled with its true provenance.
+ * The single content-less `SECRET_WITHHELD` producer input — the one shape every
+ * secret-blocked change (gitignored OR git-tracked) is authored with, so the two
+ * producers can never drift (a divergence in `diffComplete`/`blockedReason` would
+ * make the backend gate treat one kind of secret differently from the other).
+ *
+ * Both sides are absent (empty enforcement digests) and `diffComplete=false`.
+ * Being non-binary incomplete with no keepable bytes, it forces the change set to
+ * PARTIAL_BLOCKED (never BINARY_SUMMARY_ONLY) — approval is blocked and the path
+ * is surfaced honestly, while its CONTENT never enters the ledger or storage.
+ * `blockedReason=SECRET_WITHHELD` records the honest cause so the review UI can say
+ * *why* rather than a cause-agnostic "unavailable" (doc 15). Callers supply the
+ * id / paths / kind / captureClass so each producer keeps its own honest identity.
  */
-function unreviewableChangeInput(
-  changeSetId: string,
-  path: string,
+function secretWithheldChangeInput(
+  id: string,
+  pathBefore: string,
+  pathAfter: string,
+  kind: FileChangeKind,
   captureClass: FileCaptureClass,
 ): CapturedChangeInput {
   return {
-    id: `${changeSetId}:${path}`,
-    pathBefore: path,
-    pathAfter: path,
-    kind: FileChangeKind.MODIFY,
+    id,
+    pathBefore,
+    pathAfter,
+    kind,
     captureClass,
     diffComplete: false,
     blockedReason: FileReviewBlockReason.SECRET_WITHHELD,
   };
 }
 
+/**
+ * Map a secret-blocked GITIGNORED path (the write never flowed — hard-blocked at
+ * the harness gate, design doc 12 / DD-E) to a content-less entry. The write was
+ * blocked before it ran, so create-vs-modify is unknown and irrelevant (nothing
+ * is ever applied or reconciled for this entry) — kind is MODIFY. `captureClass`
+ * is the turn's CAS substrate class (GIT_IGNORED_CAPTURED | NON_GIT_CAS).
+ */
+function unreviewableChangeInput(
+  changeSetId: string,
+  path: string,
+  captureClass: FileCaptureClass,
+): CapturedChangeInput {
+  return secretWithheldChangeInput(
+    `${changeSetId}:${path}`,
+    path,
+    path,
+    FileChangeKind.MODIFY,
+    captureClass,
+  );
+}
+
+/**
+ * Map a secret-like GIT-TRACKED change to a content-less entry (DD-26 follow-up
+ * #3). Unlike a gitignored secret, a tracked secret write actually FLOWED (the
+ * capture-mode gate allows tracked mutations), so it is present in the git diff
+ * with real bytes — which must never be persisted into the ledger. We author it
+ * content-less here so its CONTENT never reaches the ledger / Temporal history /
+ * storage, while the honest kind + paths (a CREATE/MODIFY/DELETE, mirroring
+ * {@link toCapturedChangeInput}'s id/path derivation so the resume reconcile
+ * lookup matches) and `GIT_TRACKED` provenance are preserved. It is discard-only
+ * (PARTIAL_BLOCKED): on resume it can only be rejected, and the git substrate
+ * reverts it byte-exact from the baseline ref (the reversible substrate a
+ * gitignored secret lacks — so "withhold + revert" upholds never-persisted here
+ * without the gate hard-block). A DELETE is handled here too: the git diff
+ * resurrects the deleted file's baseline (secret) bytes as the `before` side, a
+ * leak only this seam can withhold (the gate sees no content for a delete).
+ */
+function trackedSecretChangeInput(
+  changeSetId: string,
+  change: GitCapturedChange,
+): CapturedChangeInput {
+  const isCreate = change.changeType === FileChangeType.CREATE;
+  const isDelete = change.changeType === FileChangeType.DELETE;
+  const pathBefore = isCreate ? "" : change.path;
+  const pathAfter = isDelete ? "" : change.path;
+  return secretWithheldChangeInput(
+    `${changeSetId}:${pathAfter || pathBefore}`,
+    pathBefore,
+    pathAfter,
+    toFileChangeKind(change.changeType),
+    FileCaptureClass.GIT_TRACKED,
+  );
+}
+
+/**
+ * Split a turn's git-tracked changes by the secret gate: a secret-like tracked
+ * path (a committed `credentials.json`, `.env.example`, `*.tfvars`, ...) goes to
+ * `secret` (authored content-less via {@link trackedSecretChangeInput}); every
+ * other tracked change stays in `safe` (its diff is captured normally). Pure and
+ * exported for direct unit testing. Keyed on the same {@link isSecretLikePath}
+ * classifier the CAS/gitignored path uses ({@link partitionIgnoredPathsBySecret}
+ * in secret-paths.ts), so a path is classified identically everywhere. NOTE: the
+ * classifier is path-based (DD-12 D2), so a rename to an innocuous name defeats
+ * it — an intentional, cross-substrate limitation, not introduced here.
+ */
+export function partitionGitChangesBySecret(changes: readonly GitCapturedChange[]): {
+  readonly safe: readonly GitCapturedChange[];
+  readonly secret: readonly GitCapturedChange[];
+} {
+  const safe: GitCapturedChange[] = [];
+  const secret: GitCapturedChange[] = [];
+  for (const change of changes) {
+    if (isSecretLikePath(change.path)) secret.push(change);
+    else safe.push(change);
+  }
+  return { safe, secret };
+}
+
 /** Map the git capture kind to the file-review {@link FileChangeKind}. */
-function toFileChangeKind(changeType: FileChangeType): FileChangeKind {
+export function toFileChangeKind(changeType: FileChangeType): FileChangeKind {
   switch (changeType) {
     case FileChangeType.CREATE:
       return FileChangeKind.ADD;