@stigmer/runner 3.1.2 → 3.1.4

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

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

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

@@ -24,6 +24,7 @@ import {
   casBlobKey,
   casBlobReader,
   casManifestKey,
+  classifyCasChange,
   loadCasManifest,
   restoreCasToBaseline,
   snapshotCasChangeSet,
@@ -97,6 +98,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({
@@ -402,3 +437,68 @@ describe("digest independence from capture class", () => {
     expect(files.map((f) => f.pathAfter)).toEqual(["a", "m", "z"]);
   });
 });
+
+// The single classification authority for a CAS before/after pair. Both the
+// turn-boundary capture (buildCasCapturedFile, exercised via snapshotCasChangeSet)
+// and the mid-run progress producer (cas-progress) route through it, so these
+// cases lock the shape the strip and the reviewed set share.
+describe("classifyCasChange (pure)", () => {
+  const buf = (s: string): Buffer => Buffer.from(s, "utf8");
+
+  it("classifies ADD from a null before and blanks the before path", () => {
+    const c = classifyCasChange("new.ts", null, buf("a\nb\nc\n"))!;
+    expect(c.kind).toBe(FileChangeKind.ADD);
+    expect(c.pathBefore).toBe("");
+    expect(c.pathAfter).toBe("new.ts");
+    expect(c.isBinary).toBe(false);
+    expect(c.lineCounts).toEqual({ linesAdded: 3, linesRemoved: 0 });
+  });
+
+  it("classifies DELETE from a null after and blanks the after path", () => {
+    const c = classifyCasChange("gone.ts", buf("x\ny\n"), null)!;
+    expect(c.kind).toBe(FileChangeKind.DELETE);
+    expect(c.pathBefore).toBe("gone.ts");
+    expect(c.pathAfter).toBe("");
+    expect(c.lineCounts).toEqual({ linesAdded: 0, linesRemoved: 2 });
+  });
+
+  it("classifies MODIFY from two present sides", () => {
+    const c = classifyCasChange("m.ts", buf("a\n"), buf("a\nb\n"))!;
+    expect(c.kind).toBe(FileChangeKind.MODIFY);
+    expect(c.pathBefore).toBe("m.ts");
+    expect(c.pathAfter).toBe("m.ts");
+    expect(c.lineCounts).toEqual({ linesAdded: 1, linesRemoved: 0 });
+  });
+
+  it("returns undefined for both-null and for a no-op touch (unchanged bytes)", () => {
+    expect(classifyCasChange("p", null, null)).toBeUndefined();
+    expect(classifyCasChange("p", buf("same\n"), buf("same\n"))).toBeUndefined();
+  });
+
+  it("marks a binary side and withholds line counts", () => {
+    const bin = Buffer.from([0, 1, 2, 0, 255, 0]);
+    const c = classifyCasChange("blob.bin", null, bin)!;
+    expect(c.kind).toBe(FileChangeKind.ADD);
+    expect(c.isBinary).toBe(true);
+    expect(c.lineCounts).toBeUndefined();
+  });
+
+  it("is the authority snapshotCasChangeSet uses (parity guard)", async () => {
+    const { storage } = makeFakeStorage();
+    const before = bytes("one\ntwo\n");
+    const after = bytes("one\ntwo\nthree\n");
+    const { manifest } = await snapshotCasChangeSet({
+      storage, executionId: EXEC, changeSetId: CHANGE_SET,
+      captures: [{ path: "m.ts", before, after, captureClass: IGNORED }],
+    });
+    const file = manifest.files[0];
+    const direct = classifyCasChange("m.ts", Buffer.from(before), Buffer.from(after))!;
+    // The captured file's display classification is exactly what the shared
+    // classifier produces — no second authority that could drift.
+    expect(file.kind).toBe(direct.kind);
+    expect(file.pathBefore).toBe(direct.pathBefore);
+    expect(file.pathAfter).toBe(direct.pathAfter);
+    expect(file.diffComplete).toBe(!direct.isBinary);
+    expect(file.lineCounts).toEqual(direct.lineCounts);
+  });
+});

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

@@ -0,0 +1,252 @@
+/**
+ * Unit tests for the shared DD-28 qualification rule
+ * ({@link qualifyTurnCommandProvenance}) — the harness-agnostic core both the
+ * Cursor and deep-agent adapters delegate to.
+ *
+ * These exercise the rule in isolation over synthetic `turnToolCalls` (the
+ * harness supplies the scoping + consent resolvers); each harness's own mapping
+ * is covered by its adapter suite. The rule: a turn qualifies only when every
+ * mutation-capable call it executed was a shell command with a provable consent
+ * source (direct / lease / auto_approve_all), and every uncertainty fails closed.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ApprovalAction,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { qualifyTurnCommandProvenance, findLeaseConsentId } from "../command-provenance.js";
+
+function toolCall(overrides: MessageInitShape<typeof ToolCallSchema>): ToolCall {
+  return create(ToolCallSchema, {
+    id: "call-1",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+function aiMessageWith(toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls });
+}
+
+// Default resolvers for the common "no direct consent, every listed call ran"
+// case — individual tests override as needed.
+const executedAlways = (): boolean => true;
+const noDirectConsent = (): undefined => undefined;
+
+function shell(id: string, cmd = "seq 1 5 > out.txt"): ToolCall {
+  return toolCall({ id, name: "shell", args: { command: cmd } });
+}
+
+describe("qualifyTurnCommandProvenance", () => {
+  it("cites the direct consent id the resolver returns", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: (t) => (t.id === "shell-1" ? "consent-row" : undefined),
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("falls back to the APPROVE_ALL lease row when there is no direct consent", () => {
+    const leaseRow = toolCall({
+      id: "lease-row",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const leased = shell("shell-leased");
+    const messages = [aiMessageWith([leaseRow]), aiMessageWith([leased])];
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [leased],
+      messages,
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+
+  it("flags auto_approve_all when only the global bypass authorized the command", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: true,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual([]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(true);
+  });
+
+  it("prefers direct consent over auto_approve_all when both are available", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: true,
+    });
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("fails closed on a file-tool call (mixed turn)", () => {
+    const tc = shell("shell-1");
+    const edit = toolCall({ id: "edit-1", name: "edit", args: { path: "a.txt" } });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, edit],
+      messages: [aiMessageWith([tc, edit])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an MCP tool", () => {
+    const tc = shell("shell-1");
+    const mcp = toolCall({ id: "mcp-1", name: "apply_resource", mcpServerSlug: "planton" });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, mcp],
+      messages: [aiMessageWith([tc, mcp])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on a sub-agent delegation (task -> SUBAGENT kind)", () => {
+    const tc = shell("shell-1");
+    const task = toolCall({ id: "task-1", name: "task", args: { prompt: "go" } });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, task],
+      messages: [aiMessageWith([tc, task])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an unrecognized tool name", () => {
+    const tc = shell("shell-1");
+    const unknown = toolCall({ id: "u-1", name: "mystery_tool" });
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc, unknown],
+      messages: [aiMessageWith([tc, unknown])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an executed command with no provable consent source", () => {
+    const tc = shell("shell-1");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [tc],
+      messages: [aiMessageWith([tc])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("returns undefined when no command executed (only a pending shell)", () => {
+    const pending = shell("shell-pending");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [pending],
+      messages: [aiMessageWith([pending])],
+      isExecutedCommand: () => false, // pending / denied — never executed
+      resolveDirectConsent: () => "consent-row",
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("skips read-only tools and hidden collapsed rows, then qualifies", () => {
+    const read = toolCall({ id: "read-1", name: "read", args: { path: "a.txt" } });
+    const hidden = toolCall({
+      id: "hidden-1",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_SKIPPED,
+      args: undefined,
+    });
+    const executed = shell("shell-executed");
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [read, hidden, executed],
+      messages: [aiMessageWith([read, hidden, executed])],
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: (t) => (t.id === "shell-executed" ? "consent-row" : undefined),
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["consent-row"]);
+  });
+
+  it("dedupes consent ids across multiple commands citing the same lease", () => {
+    const leaseRow = toolCall({
+      id: "lease-row",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const a = shell("shell-a");
+    const b = shell("shell-b");
+    const messages = [aiMessageWith([leaseRow]), aiMessageWith([a, b])];
+    const provenance = qualifyTurnCommandProvenance({
+      turnToolCalls: [a, b],
+      messages,
+      isExecutedCommand: executedAlways,
+      resolveDirectConsent: noDirectConsent,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+});
+
+describe("findLeaseConsentId", () => {
+  it("returns the earliest APPROVE_ALL row of the tool's category", () => {
+    const first = toolCall({ id: "lease-1", name: "shell", approvalAction: ApprovalAction.APPROVE_ALL });
+    const second = toolCall({ id: "lease-2", name: "bash", approvalAction: ApprovalAction.APPROVE_ALL });
+    const messages = [aiMessageWith([first]), aiMessageWith([second])];
+    expect(findLeaseConsentId(messages, "execute")).toBe("lease-1");
+  });
+
+  it("returns undefined when no APPROVE_ALL lease exists for the category", () => {
+    const writeApproveAll = toolCall({
+      id: "w-1",
+      name: "write",
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    const messages = [aiMessageWith([writeApproveAll])];
+    // A write-category lease does not authorize a shell command.
+    expect(findLeaseConsentId(messages, "shell")).toBeUndefined();
+  });
+
+  it("returns undefined for a non-gated (read-only) tool name", () => {
+    const messages = [aiMessageWith([shell("s")])];
+    expect(findLeaseConsentId(messages, "read")).toBeUndefined();
+  });
+});