@stigmer/runner 3.1.1 → 3.1.3

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;

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

@@ -57,6 +57,7 @@ import {
 import type { ArtifactStorage } from "../artifact-storage.js";
 import { bytesLookBinary } from "../file-change.js";
 import { sha256Bytes, sha256Hex } from "./digest.js";
+import { countLineChanges, type LineChangeCounts } from "./line-counts.js";
 
 /**
  * Reads an artifact's raw bytes back by storage key. Injected so this module
@@ -91,6 +92,14 @@ export interface CasCapturedFile {
   readonly after?: CasBlobRef;
   /** False when a side is binary — the change set cannot be approved as complete. */
   readonly diffComplete: boolean;
+  /**
+   * Display `+N −M` counted from the in-memory bytes at capture — the only
+   * moment a CAS change's text exists outside blob storage. Absent for binary
+   * or oversized sides. Carried in memory to the CANDIDATE event only, never
+   * persisted in the manifest: the manifest is the reconcile's source of truth,
+   * and display decoration does not belong in an enforcement record.
+   */
+  readonly lineCounts?: LineChangeCounts;
 }
 
 /** The durable manifest for one change set — the reconcile's source of truth. */
@@ -210,6 +219,7 @@ async function buildCasCapturedFile(
 
   const isCreate = kind === FileChangeKind.ADD;
   const isDelete = kind === FileChangeKind.DELETE;
+  const isBinary = beforeRef?.isBinary || afterRef?.isBinary;
 
   return {
     pathBefore: isCreate ? "" : path,
@@ -220,7 +230,13 @@ async function buildCasCapturedFile(
     after: afterRef,
     // Binary on either side means the diff cannot render as text; the change set
     // then cannot be approved as complete (parity with the git substrate).
-    diffComplete: !(beforeRef?.isBinary || afterRef?.isBinary),
+    diffComplete: !isBinary,
+    // Display counts are taken NOW, while the text bytes are still in memory —
+    // after this they exist only as offloaded blobs. A binary change has no
+    // line diff to count.
+    lineCounts: isBinary
+      ? undefined
+      : countLineChanges(beforeBuf?.toString("utf8"), afterBuf?.toString("utf8")),
   };
 }
 

package/src/shared/filereview/events.ts

@@ -42,6 +42,7 @@ import {
   FileReviewFailureKind,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { aggregateDigest, fileDigest, sha256Bytes } from "./digest.js";
+import { countLineChanges, type LineChangeCounts } from "./line-counts.js";
 import { looksBinary } from "../file-change.js";
 
 // The runner is the author of capture/reconcile/failure events. "runner" (not
@@ -150,6 +151,15 @@ export interface CapturedChangeInput {
    * this UNSPECIFIED. See {@link FileReviewBlockReason}.
    */
   readonly blockedReason?: FileReviewBlockReason;
+  /**
+   * Display line counts for this change, for producers whose bodies are not
+   * inline here (the CAS substrate counts from the in-memory bytes before
+   * offloading them as blob refs). Omit for inline content —
+   * {@link buildCapturedFileChange} then counts the inline sides itself, with
+   * the same shared {@link countLineChanges}. Informational only, never folded
+   * into the digests.
+   */
+  readonly lineCounts?: LineChangeCounts;
 }
 
 /** Normalize the string-shorthand to a {@link CapturedContent}. */
@@ -175,6 +185,37 @@ export function contentSha256(content: CapturedContent): string {
   }
 }
 
+/**
+ * Count the display `+N −M` from a change's inline sides, or `undefined` when
+ * counting is not honest here: a side that exists without inline text (a `ref`
+ * whose bytes were already offloaded, or a `binary` side with no body), or
+ * inline text that would render as binary (the UI shows "Binary file changed"
+ * for it, never a line diff — a count would describe a diff nobody sees).
+ * An absent side is fine — it is the empty document of an ADD/DELETE.
+ */
+function countInlineSides(
+  before: CapturedContent | undefined,
+  after: CapturedContent | undefined,
+): LineChangeCounts | undefined {
+  const beforeText = inlineTextOrNull(before);
+  const afterText = inlineTextOrNull(after);
+  if (beforeText === null || afterText === null) return undefined;
+  return countLineChanges(beforeText, afterText);
+}
+
+/**
+ * A side's countable inline text: the text for a non-binary inline side,
+ * `undefined` for an absent side (countable as the empty document), and `null`
+ * when the side exists but cannot be counted (ref / binary / binary-looking).
+ */
+function inlineTextOrNull(
+  content: CapturedContent | undefined,
+): string | undefined | null {
+  if (content === undefined) return undefined;
+  if (content.kind !== "inline" || looksBinary(content.text)) return null;
+  return content.text;
+}
+
 /** Build the proto {@link FileContent} for one content side (inline, ref, or binary). */
 function toFileContent(content: CapturedContent): FileContent {
   if (content.kind === "inline") {
@@ -212,12 +253,19 @@ function toFileContent(content: CapturedContent): FileContent {
  * `file_digest`) over the captured bytes. Content may be inline (git) or a blob
  * ref (CAS) — the digests are identical either way, so the aggregate digest and
  * the reconcile enforcement compose across both substrates.
+ *
+ * Display line counts are stamped here too — the single seam every substrate
+ * flows through — from `input.lineCounts` when the producer counted at its own
+ * source (CAS), else counted from the inline sides. Counting happens BEFORE any
+ * persist-time offload, so the counts survive a body being elided later. They
+ * never enter `fileDigest` (informational, not enforcement).
  */
 export function buildCapturedFileChange(input: CapturedChangeInput): CapturedFileChange {
   const before = normalizeContent(input.before);
   const after = normalizeContent(input.after);
   const beforeSha256 = before ? contentSha256(before) : "";
   const afterSha256 = after ? contentSha256(after) : "";
+  const counts = input.lineCounts ?? countInlineSides(before, after);
 
   const fc = create(CapturedFileChangeSchema, {
     id: input.id,
@@ -229,6 +277,8 @@ export function buildCapturedFileChange(input: CapturedChangeInput): CapturedFil
     afterSha256,
     diffComplete: input.diffComplete ?? true,
     blockedReason: input.blockedReason ?? FileReviewBlockReason.UNSPECIFIED,
+    linesAdded: counts?.linesAdded ?? 0,
+    linesRemoved: counts?.linesRemoved ?? 0,
     fileDigest: fileDigest({
       pathBefore: input.pathBefore,
       pathAfter: input.pathAfter,

package/src/shared/filereview/git-substrate.ts

@@ -308,6 +308,81 @@ export async function captureChangeSet(
   return { baselineTree, afterTree, changes };
 }
 
+/**
+ * One file's slim, content-free progress delta: paths + kind + line counts, NO
+ * bytes. The mid-run analogue of {@link GitSubstrateChange} (which carries the
+ * before/after {@link CapturedContent}); this deliberately carries neither side,
+ * so it can never leak content. `linesAdded`/`linesRemoved` are 0 when
+ * uncountable (a binary file — numstat reports `-`).
+ */
+export interface GitProgressEntry {
+  /** Path before the change (repo-relative). Empty for a CREATE. */
+  readonly pathBefore: string;
+  /** Path after the change (repo-relative). Empty for a DELETE. */
+  readonly pathAfter: string;
+  readonly changeType: FileChangeType;
+  readonly linesAdded: number;
+  readonly linesRemoved: number;
+}
+
+/** Result of {@link captureProgressDelta}. */
+export interface ProgressDelta {
+  /** The post-diff working-tree sha, for the caller's short-circuit cache. */
+  readonly afterTree: string;
+  /** One count-only entry per changed file (no content). */
+  readonly entries: readonly GitProgressEntry[];
+}
+
+/**
+ * Capture a NON-AUTHORITATIVE, content-free snapshot of the working-tree delta
+ * against `baselineTree` — the substrate for the live "N files changed so far"
+ * surface (mid-run live capture). Unlike {@link captureChangeSet} this reads NO
+ * file bytes: it stages the working tree into a temp index, writes its tree, and
+ * asks git for `--numstat` + `--name-status` only. Cheap enough to run on a
+ * debounce during the turn.
+ *
+ * Short-circuit: returns `undefined` when the working tree is unchanged since
+ * `lastTreeSha` (the caller passes back the previous result's `afterTree`), so a
+ * quiet turn pays only one `write-tree`, never a diff.
+ *
+ * Uses a dedicated temp-index label ("progress") so it never collides with the
+ * `baseline`/`capture`/`approved` indexes. `--no-renames` matches
+ * {@link captureChangeSet} (a rename surfaces as delete + create). A torn read of
+ * a file being written mid-turn is acceptable — the snapshot is non-authoritative
+ * and self-corrects on the next capture.
+ */
+export async function captureProgressDelta(
+  gitRoot: string,
+  executionId: string,
+  baselineTree: string,
+  excludePaths: readonly string[] = [],
+  lastTreeSha?: string,
+): Promise<ProgressDelta | undefined> {
+  const gitDir = await resolveGitDir(gitRoot);
+  const afterTree = await writeWorkingTree(gitRoot, gitDir, "progress", executionId, excludePaths);
+  if (lastTreeSha !== undefined && afterTree === lastTreeSha) return undefined;
+
+  const [nameStatusRaw, numstatRaw] = await Promise.all([
+    git(gitRoot, ["diff", "--no-renames", "--name-status", "-z", baselineTree, afterTree]),
+    git(gitRoot, ["diff", "--no-renames", "--numstat", "-z", baselineTree, afterTree]),
+  ]);
+
+  const counts = parseNumstatZ(numstatRaw);
+  const entries: GitProgressEntry[] = [];
+  for (const { status, path } of parseNameStatusZ(nameStatusRaw)) {
+    const changeType = nameStatusToChangeType(status);
+    const count = counts.get(path);
+    entries.push({
+      pathBefore: changeType === FileChangeType.CREATE ? "" : path,
+      pathAfter: changeType === FileChangeType.DELETE ? "" : path,
+      changeType,
+      linesAdded: count?.added ?? 0,
+      linesRemoved: count?.removed ?? 0,
+    });
+  }
+  return { afterTree, entries };
+}
+
 /**
  * Restore the given files to their `baselineTree` (pre-turn) bytes. On resume
  * this reverts the REJECTED/undecided subset so a discarded change snaps back
@@ -462,6 +537,39 @@ function parseNameStatusZ(raw: string): NameStatusEntry[] {
   return entries;
 }
 
+/**
+ * Parse `git diff --numstat -z` into a path -> {added, removed} map. Each record
+ * is a NUL-terminated `<added>\t<removed>\t<path>` triple; a binary file reports
+ * `-` for both counts, which we surface as 0 (no count) per the display contract.
+ */
+function parseNumstatZ(raw: string): Map<string, { added: number; removed: number }> {
+  const counts = new Map<string, { added: number; removed: number }>();
+  for (const record of raw.split("\u0000")) {
+    if (!record) continue;
+    const tab = record.indexOf("\t");
+    const tab2 = record.indexOf("\t", tab + 1);
+    if (tab < 0 || tab2 < 0) continue;
+    const addedStr = record.slice(0, tab);
+    const removedStr = record.slice(tab + 1, tab2);
+    const path = record.slice(tab2 + 1);
+    if (!path) continue;
+    const added = addedStr === "-" ? 0 : Number.parseInt(addedStr, 10) || 0;
+    const removed = removedStr === "-" ? 0 : Number.parseInt(removedStr, 10) || 0;
+    counts.set(path, { added, removed });
+  }
+  return counts;
+}
+
+/**
+ * Map a `--name-status` status letter to a {@link FileChangeType} — the same
+ * A -> CREATE, D -> DELETE, else MODIFY rule {@link buildCapturedChange} uses.
+ */
+function nameStatusToChangeType(status: string): FileChangeType {
+  if (status === "A") return FileChangeType.CREATE;
+  if (status === "D") return FileChangeType.DELETE;
+  return FileChangeType.MODIFY;
+}
+
 /** Read a blob's exact BYTES from a tree, or `undefined` when absent. */
 async function readBlobBytes(
   gitRoot: string,

package/src/shared/filereview/index.ts

@@ -33,7 +33,28 @@ export {
   type CaptureResumeResult,
 } from "./capture.js";
 
-export { isGitWorkTree } from "./git-substrate.js";
+export {
+  captureProgressDelta,
+  isGitWorkTree,
+  type GitProgressEntry,
+  type ProgressDelta,
+} from "./git-substrate.js";
+
+export {
+  buildFileChangeProgress,
+  captureFileChangeProgress,
+  newProgressCaptureState,
+  PROGRESS_CAPTURE_MIN_INTERVAL_MS,
+  PROGRESS_MAX_ENTRIES,
+  shouldCaptureProgress,
+  type ProgressCaptureState,
+} from "./progress.js";
+
+export {
+  countLineChanges,
+  LINE_COUNT_MAX_BYTES,
+  type LineChangeCounts,
+} from "./line-counts.js";
 
 export {
   applyCasApproved,

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

@@ -0,0 +1,83 @@
+/**
+ * Capture-time line counting for the file-review subsystem: the `+N −M` stamped
+ * onto each {@link CapturedFileChange} so review surfaces can decorate file
+ * lists without the file bodies.
+ *
+ * WHY THE RUNNER COUNTS, AND WHY WITH JSDIFF. The counts exist because the
+ * review UI's compact file lists must show per-file magnitude, but by the time
+ * the UI renders, large before/after bodies may have been offloaded to artifact
+ * storage (status-offload) — a client cannot count what it would first have to
+ * download. So the counts are computed once, at capture, where the bytes are
+ * always in hand. They are computed with the SAME `diff` (jsdiff) Myers
+ * algorithm the SDK's diff renderer uses (`computeDiff` → `structuredPatch`),
+ * NOT with `git diff --numstat`: two counting authorities can disagree on edge
+ * cases (trailing newlines being the classic), and a list that says `+37 −1`
+ * beside a rendered diff showing `+37 −0` is a self-contradicting UI. One
+ * algorithm, consistent by construction.
+ *
+ * The counts are INFORMATIONAL display data only — never an enforcement input,
+ * never folded into `file_digest`/`aggregate_digest` (the same contract as
+ * `blocked_reason`).
+ */
+
+import { structuredPatch } from "diff";
+
+/**
+ * Per-side byte ceiling above which counting is skipped. Myers is O(ND) and a
+ * pathological many-MB text pair must never stall the capture activity just to
+ * decorate a list; above this the counts stay absent and the UI hides the stat.
+ * Generous relative to the 128 KiB per-side inline-persist cap — a file can be
+ * several times that and still count quickly — while bounding the worst case.
+ */
+export const LINE_COUNT_MAX_BYTES = 1024 * 1024;
+
+/** The `+N −M` pair for one file change. */
+export interface LineChangeCounts {
+  readonly linesAdded: number;
+  readonly linesRemoved: number;
+}
+
+/**
+ * Count the added/removed lines between two text sides, exactly as the SDK's
+ * diff renderer would show them.
+ *
+ * An absent side is the empty document — an ADD counts every `after` line as
+ * added, a DELETE every `before` line as removed — mirroring how the renderer
+ * diffs a create/delete. `` markers are metadata,
+ * not content, and are excluded (the same rule as the SDK's `mapPatchHunks`).
+ *
+ * Returns `undefined` when counting is not possible or meaningful: both sides
+ * absent, or either side over {@link LINE_COUNT_MAX_BYTES}. Callers leave the
+ * proto counts at zero in that case, which consumers render as "no stat".
+ */
+export function countLineChanges(
+  before: string | undefined,
+  after: string | undefined,
+): LineChangeCounts | undefined {
+  if (before === undefined && after === undefined) return undefined;
+  const beforeText = before ?? "";
+  const afterText = after ?? "";
+  if (
+    Buffer.byteLength(beforeText, "utf8") > LINE_COUNT_MAX_BYTES ||
+    Buffer.byteLength(afterText, "utf8") > LINE_COUNT_MAX_BYTES
+  ) {
+    return undefined;
+  }
+
+  // Zero context: the +/- line population is independent of context width, and
+  // omitting context lines keeps the walk (and the patch object) minimal.
+  const patch = structuredPatch("a", "b", beforeText, afterText, "", "", {
+    context: 0,
+  });
+
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  for (const hunk of patch.hunks) {
+    for (const line of hunk.lines) {
+      if (line.startsWith("\\")) continue;
+      if (line[0] === "+") linesAdded++;
+      else if (line[0] === "-") linesRemoved++;
+    }
+  }
+  return { linesAdded, linesRemoved };
+}