@stigmer/runner 3.1.3 → 3.1.5

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

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

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

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

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

@@ -189,6 +189,66 @@ export async function snapshotCasChangeSet(opts: {
   };
 }
 
+/**
+ * The display-facing classification of one CAS path's before/after bytes: the
+ * change kind, whether either side is binary, and the `+N −M` line counts.
+ */
+export interface CasChangeClassification {
+  /** Path before the change (workspace-relative). Empty for ADD. */
+  readonly pathBefore: string;
+  /** Path after the change. Empty for DELETE. */
+  readonly pathAfter: string;
+  readonly kind: FileChangeKind;
+  /** A NUL byte on either side — the diff cannot render as text. */
+  readonly isBinary: boolean;
+  /** `+N −M` from the in-memory bytes; absent for a binary or oversized side. */
+  readonly lineCounts?: LineChangeCounts;
+}
+
+/**
+ * Classify one CAS path's before/after bytes. Returns `undefined` for a
+ * non-change — both sides absent, or a touch that left the bytes unchanged —
+ * exactly as the git substrate's diff omits unchanged files.
+ *
+ * This is the SINGLE classification authority for a CAS before/after pair: the
+ * turn-boundary capture ({@link buildCasCapturedFile}) and the mid-run progress
+ * producer ({@link ./cas-progress.js}) both route through it, so the live "N
+ * files changed so far" strip and the reviewed change set can never disagree on
+ * an edge case (the trailing-newline class of bug {@link ./line-counts.js}
+ * warns about). Kind, no-op detection, binary detection, and counting live here
+ * and nowhere else.
+ */
+export function classifyCasChange(
+  path: string,
+  beforeBuf: Buffer | null,
+  afterBuf: Buffer | null,
+): CasChangeClassification | undefined {
+  if (beforeBuf === null && afterBuf === null) return undefined;
+  // A touch that did not change the bytes is not a reviewable change.
+  if (beforeBuf && afterBuf && beforeBuf.equals(afterBuf)) return undefined;
+
+  const kind =
+    beforeBuf === null
+      ? FileChangeKind.ADD
+      : afterBuf === null
+        ? FileChangeKind.DELETE
+        : FileChangeKind.MODIFY;
+  const isBinary =
+    (beforeBuf !== null && bytesLookBinary(beforeBuf)) ||
+    (afterBuf !== null && bytesLookBinary(afterBuf));
+
+  return {
+    pathBefore: kind === FileChangeKind.ADD ? "" : path,
+    pathAfter: kind === FileChangeKind.DELETE ? "" : path,
+    kind,
+    isBinary,
+    // A binary change has no text line diff to count.
+    lineCounts: isBinary
+      ? undefined
+      : countLineChanges(beforeBuf?.toString("utf8"), afterBuf?.toString("utf8")),
+  };
+}
+
 /**
  * Store one path's before/after blobs and classify the change. Returns
  * `undefined` for a no-op (both sides absent, or an unchanged touch).
@@ -199,44 +259,29 @@ async function buildCasCapturedFile(
   capture: CasPathCapture,
 ): Promise<CasCapturedFile | undefined> {
   const { path, before, after, captureClass } = capture;
-  if (before === null && after === null) return undefined;
-
   const beforeBuf = before === null ? null : Buffer.from(before);
   const afterBuf = after === null ? null : Buffer.from(after);
 
-  // A touch that did not change the bytes is not a reviewable change.
-  if (beforeBuf && afterBuf && beforeBuf.equals(afterBuf)) return undefined;
+  const classification = classifyCasChange(path, beforeBuf, afterBuf);
+  if (!classification) return undefined;
 
   const beforeRef = beforeBuf ? await storeBlob(storage, executionId, beforeBuf) : undefined;
   const afterRef = afterBuf ? await storeBlob(storage, executionId, afterBuf) : undefined;
 
-  const kind =
-    beforeRef === undefined
-      ? FileChangeKind.ADD
-      : afterRef === undefined
-        ? FileChangeKind.DELETE
-        : FileChangeKind.MODIFY;
-
-  const isCreate = kind === FileChangeKind.ADD;
-  const isDelete = kind === FileChangeKind.DELETE;
-  const isBinary = beforeRef?.isBinary || afterRef?.isBinary;
-
   return {
-    pathBefore: isCreate ? "" : path,
-    pathAfter: isDelete ? "" : path,
-    kind,
+    pathBefore: classification.pathBefore,
+    pathAfter: classification.pathAfter,
+    kind: classification.kind,
     captureClass,
     before: beforeRef,
     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: !isBinary,
+    diffComplete: !classification.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")),
+    // after this they exist only as offloaded blobs (the same counts the mid-run
+    // progress producer derives via classifyCasChange).
+    lineCounts: classification.lineCounts,
   };
 }
 

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

@@ -0,0 +1,180 @@
+/**
+ * The DD-28 approved-command turn qualification rule — the harness-agnostic core
+ * of the auto-keep policy's runner-side facts.
+ *
+ * A turn whose ONLY mutation source was shell commands the human had already
+ * authorized should not re-gate its file effects at the turn-boundary review —
+ * the user consented to the command, and the command's file effects are the
+ * consented outcome. The server cannot derive this itself (tool calls carry no
+ * turn marker), so the runner — the only component that owns turn scoping —
+ * derives the facts and attaches them to the CANDIDATE_CAPTURED event as
+ * {@link TurnCommandProvenance}.
+ *
+ * This module owns the *qualification rule* both harnesses share; each harness
+ * supplies only what genuinely differs — how "this turn's tool calls" are scoped,
+ * and how a single executed command's DIRECT consent row is identified — via
+ * {@link CommandProvenanceCoreInputs}. Keeping the rule in one place is what makes
+ * the Cursor and deep-agent qualifications provably identical (a second copy would
+ * drift on edge cases — the divergence the AI-Engineer role warns against).
+ *
+ * TRUST BOUNDARY. This module asserts turn FACTS (which tools ran this turn),
+ * the same trust level as the captured bytes themselves. It never asserts
+ * CONSENT: a resolved consent id merely POINTS at a transcript row whose
+ * `approval_action` was authored by the server's SubmitApproval (and is
+ * preserved against runner writes) — the backend re-verifies every claimed row
+ * against that server-owned record before authoring the policy decision, so a
+ * runner cannot mint authorization it was never given.
+ *
+ * FAIL-CLOSED. Every uncertainty disqualifies (returns undefined → the set
+ * reviews manually, exactly as before DD-28): a file-tool call, an MCP tool, a
+ * sub-agent delegation, an unrecognized tool name, or an executed shell command
+ * with no provable consent source. Being conservative here costs only an extra
+ * review; being permissive would silently waive one.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { TurnCommandProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { ApprovalAction, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool, toolApprovalCategory } from "../tool-kind.js";
+import { isToolCallRowHidden } from "../tool-row.js";
+
+/**
+ * Tool kinds that can never mutate the workspace: their presence in a turn is
+ * irrelevant to change-set provenance. Everything OUTSIDE this set is either a
+ * consent-mapped shell command or a disqualifier — never silently ignored.
+ */
+export const NON_MUTATING_KINDS: ReadonlySet<ToolKind> = new Set([
+  ToolKind.FILE_READ,
+  ToolKind.SEARCH,
+  ToolKind.LIST,
+  ToolKind.FETCH,
+  ToolKind.WEB_SEARCH,
+  ToolKind.THINK,
+  ToolKind.TODO,
+]);
+
+/**
+ * The harness-supplied inputs to the shared DD-28 qualification rule. The two
+ * function inputs are exactly the two things that differ between harnesses
+ * (turn scoping is expressed by which calls appear in {@link turnToolCalls}).
+ */
+export interface CommandProvenanceCoreInputs {
+  /**
+   * This turn's tool calls, already scoped by the harness (Cursor: the positional
+   * slice from the turn's first streamed message; deep-agent: the calls whose id
+   * is new since a pre-stream settled snapshot). Order is preserved but irrelevant.
+   */
+  readonly turnToolCalls: readonly ToolCall[];
+  /**
+   * The WHOLE transcript, for the APPROVE_ALL lease lookup — a lease is
+   * run-lifetime and its granting row usually lives in a prior turn.
+   */
+  readonly messages: readonly AgentMessage[];
+  /**
+   * Whether a (shell) tool call actually EXECUTED this turn, as opposed to being
+   * a pending/denied gate that produced no mutation. A non-executed shell neither
+   * needs consent nor disqualifies (Cursor: not in the denial ledger; deep-agent:
+   * status is COMPLETED).
+   */
+  readonly isExecutedCommand: (tc: ToolCall) => boolean;
+  /**
+   * The tool-call id of the row whose server-authored `approval_action` DIRECTLY
+   * authorized this executed command, or undefined when none does (then the lease
+   * / global-bypass fallbacks apply). Cursor maps a reinvocation grant token back
+   * to its consent row; the deep-agent's gated command IS its own consent row
+   * (same id, `approval_action` written in place).
+   */
+  readonly resolveDirectConsent: (tc: ToolCall) => string | undefined;
+  /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+  readonly globalBypass: boolean;
+}
+
+/**
+ * Apply the DD-28 qualification rule to a harness-scoped turn, returning the
+ * {@link TurnCommandProvenance} to attach to the candidate — or undefined when
+ * the turn does not qualify (any non-shell mutation-capable call, any unknown
+ * tool, any executed command without a provable consent source, or no executed
+ * consented command at all).
+ */
+export function qualifyTurnCommandProvenance(
+  inputs: CommandProvenanceCoreInputs,
+): TurnCommandProvenance | undefined {
+  const { turnToolCalls, messages, isExecutedCommand, resolveDirectConsent, globalBypass } = inputs;
+
+  const consentIds = new Set<string>();
+  let authorizedByAutoApproveAll = false;
+  let executedCommandCount = 0;
+
+  for (const tc of turnToolCalls) {
+    // A hidden row is a collapsed twin/reaction — it never executed.
+    if (isToolCallRowHidden(tc)) continue;
+
+    const kind = classifyTool(tc.name, tc.mcpServerSlug);
+    if (NON_MUTATING_KINDS.has(kind)) continue;
+
+    if (kind !== ToolKind.SHELL) {
+      // A file tool (mixed turn), a sub-agent (unattributable mutations), an
+      // MCP tool (opaque side effects), or an unrecognized name — the turn's
+      // mutations cannot be attributed to consented commands. Fail closed.
+      return undefined;
+    }
+
+    if (!isExecutedCommand(tc)) {
+      // A pending / denied shell — this turn's gate, not a mutation source.
+      continue;
+    }
+    executedCommandCount++;
+
+    const consentId = resolveDirectConsent(tc);
+    if (consentId) {
+      consentIds.add(consentId);
+      continue;
+    }
+    const leaseConsentId = findLeaseConsentId(messages, tc.name);
+    if (leaseConsentId) {
+      consentIds.add(leaseConsentId);
+      continue;
+    }
+    if (globalBypass) {
+      authorizedByAutoApproveAll = true;
+      continue;
+    }
+    // An executed shell command with no grant, no lease, and no bypass should
+    // be impossible (every un-consented shell is gated); if it ever happens,
+    // the honest answer is a manual review, not a waived one.
+    return undefined;
+  }
+
+  // A turn that executed no consented command has nothing to attribute the
+  // change set to — whatever changed came from somewhere else. Manual review.
+  if (executedCommandCount === 0) return undefined;
+
+  return create(TurnCommandProvenanceSchema, {
+    consentToolCallIds: [...consentIds],
+    authorizedByAutoApproveAll,
+  });
+}
+
+/**
+ * Find the transcript row whose APPROVE_ALL authored the run-lifetime lease
+ * covering `toolName`'s category — the consent row a lease-executed command
+ * cites. Searched across the whole transcript (a lease usually originates in a
+ * prior turn); the first (earliest) APPROVE_ALL of the category is the lease's
+ * origin. Returns undefined when no lease row exists for the category.
+ */
+export function findLeaseConsentId(
+  messages: readonly AgentMessage[],
+  toolName: string,
+): string | undefined {
+  const category = toolApprovalCategory(toolName);
+  if (!category) return undefined;
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.approvalAction !== ApprovalAction.APPROVE_ALL) continue;
+      if (toolApprovalCategory(tc.name) === category) return tc.id;
+    }
+  }
+  return undefined;
+}

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

@@ -97,6 +97,10 @@ export function captureRef(executionId: string): string {
  * garbage collection — but `git commit-tree` still requires an author/committer,
  * and the repo may have no user.name/email configured. Supplied via env so we
  * never mutate the repo's config.
+ *
+ * Deliberately distinct from the public agent identity in
+ * `../workspace/git-identity.ts`, which authors the write-back commits that
+ * land on real branches and pull requests.
  */
 const SNAPSHOT_IDENTITY_ENV: Record<string, string> = {
   GIT_AUTHOR_NAME: "stigmer-runner",
@@ -325,8 +329,14 @@ export interface GitProgressEntry {
   readonly linesRemoved: number;
 }
 
-/** Result of {@link captureProgressDelta}. */
-export interface ProgressDelta {
+/**
+ * Result of {@link captureProgressDelta} — the git-numstat delta. Distinct from
+ * the substrate-neutral `ProgressDelta` (in {@link ./progress.js}) that the
+ * git/cas/hybrid substrates emit: this carries the working-tree sha (for the
+ * short-circuit) and git's `FileChangeType` entries; the neutral one carries
+ * proto `FileChangeKind` entries and an honest total.
+ */
+export interface GitProgressDelta {
   /** 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). */
@@ -357,7 +367,7 @@ export async function captureProgressDelta(
   baselineTree: string,
   excludePaths: readonly string[] = [],
   lastTreeSha?: string,
-): Promise<ProgressDelta | undefined> {
+): Promise<GitProgressDelta | undefined> {
   const gitDir = await resolveGitDir(gitRoot);
   const afterTree = await writeWorkingTree(gitRoot, gitDir, "progress", executionId, excludePaths);
   if (lastTreeSha !== undefined && afterTree === lastTreeSha) return undefined;