@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -1,13 +1,33 @@
 /**
  * V3StatusBuilder — consumes StigmerRunEvents from the V3ProtocolNormalizer
- * and progressively builds the AgentExecutionStatus proto.
+ * and progressively builds the transcript half of the AgentExecutionStatus
+ * proto it is handed: messages, tool-call rows and their approval status,
+ * sub-agent rows, todos, artifacts, write-backs.
  *
- * Implements the same behavioral contract as the v2 StatusBuilder for all
- * 8 golden scenarios, using v3 event semantics (tool_call_id keying,
- * content-block-level deltas, explicit tool lifecycle).
+ * The one transcript builder of the native harness since S3 M2b: v3 event
+ * semantics (tool_call_id keying, content-block-level deltas, explicit tool
+ * lifecycle). Its predecessor, the v2 `StatusBuilder` over LangChain's
+ * `streamEvents` v2, was retired with the v2 stream (Q-S3-1); the eight
+ * golden sequences both once had to agree on are this builder's test's.
  *
- * Usage is accumulated on message_finish only (standalone usage events are
+ * What this builder deliberately does NOT write, and who does (the adapter
+ * contract's field ownership, `harness/types.ts` `TurnSink`): the phase,
+ * `startedAt` and `streamingUsage` are the turn runtime's. A gated tool
+ * start is reported as the {@link awaitingApproval} fact and the caller
+ * (`turn-stream.ts`) decides what that means for the turn; usage is reported
+ * raw through {@link V3StatusBuilderOptions.onUsage} and the caller prices
+ * it into the sink (until S3 M2a this builder flipped WAITING_FOR_APPROVAL
+ * itself and summed usage into `streamingUsage` — a second writer of each
+ * field beside the runtime's).
+ *
+ * Usage is reported on message_finish only (standalone usage events are
  * no-ops) to prevent double-counting — v3 emits both for the same turn.
+ * EVERY graph's usage is reported, the sub-agents' included (S3 M2b,
+ * Q-M2b-1): a sub-agent's `message_finish` fires the same hook before it is
+ * routed to the tracker, so the execution's usage — and the cost cap the
+ * runtime enforces over it — is the whole execution's spend. Until M2b the
+ * sub-agents' turns were discarded (S3 M2a finding F-M2a-12); the cost cap
+ * then lived inside the graph, where a middleware saw every model call.
  */
 
 import { create, type JsonObject } from "@bufbuild/protobuf";
@@ -20,7 +40,6 @@ import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/
 import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
 import {
-  ExecutionPhase,
   MessageType,
   ToolCallStatus,
   ToolKind,
@@ -31,48 +50,61 @@ import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
 import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
-import type { ApprovalPolicyProvider } from "./status-builder.js";
 import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
 import { namespaceDepth } from "./v3-events.js";
 import {
-  UsageAccumulator,
   extractToolResultV3,
   sanitizeArgsPreview,
   stampApprovalProvenance,
+  type ApprovalPolicyProvider,
 } from "./status-builder-shared.js";
 import { SubAgentTracker } from "./subagent-tracker.js";
 
+export interface V3StatusBuilderOptions {
+  /**
+   * Fired once per `message_finish` that carries usage — the parent graph's
+   * and every sub-agent's — with the payload exactly as the protocol
+   * delivered it. The builder never sums or prices: the caller accounts (the
+   * turn runtime through `TurnSink.reportUsage`, priced at the turn's model;
+   * a sub-agent on its own model is priced at the parent's rate, as the
+   * in-graph cost cap always did — per-sub-agent pricing is an S5 item).
+   */
+  readonly onUsage?: (usage: V3UsagePayload) => void;
+}
+
 export class V3StatusBuilder implements ExecutionStatusWriter {
   readonly executionId: string;
   private readonly state: ExecutionState;
   private _forceNextUpdate = false;
+  private _awaitingApproval = false;
   private approvalProvider: ApprovalPolicyProvider | null = null;
-  private readonly usageAccumulator: UsageAccumulator;
+  private readonly onUsage: ((usage: V3UsagePayload) => void) | undefined;
   private readonly subAgentTracker: SubAgentTracker;
 
   /** Progressive tool call arg accumulation keyed by callId. */
   private readonly toolArgBuffers = new Map<string, string>();
 
-  constructor(executionId: string, initialStatus: AgentExecutionStatus) {
+  /**
+   * Builds INTO `status`, by reference: its `messages` and
+   * `subAgentExecutions` arrays are the ones indexed and pushed into, never
+   * replaced, so a caller that wraps the same status (the write-back
+   * coordinator's writer, the runtime's chokepoint) keeps seeing every row.
+   */
+  constructor(executionId: string, status: AgentExecutionStatus, options: V3StatusBuilderOptions = {}) {
     this.executionId = executionId;
-    this.state = new ExecutionState(initialStatus);
-
-    // Resume path: when constructed from a persisted transcript (status seeded
-    // in index.ts on a durable-checkpoint resume), rebuild the tool-call index
-    // so resumed tool_started/tool_finished events reconcile to the existing
-    // calls instead of duplicating them. A first run carries no messages, so
-    // this is a no-op.
-    if (initialStatus.messages.length > 0) {
+    this.state = new ExecutionState(status);
+    this.onUsage = options.onUsage;
+
+    // Resume path: when constructed over a persisted transcript (seeded by the
+    // caller on a reinvocation), rebuild the tool-call index so resumed
+    // tool_started/tool_finished events reconcile to the existing calls
+    // instead of duplicating them. A first run carries no messages, so this
+    // is a no-op. The tracker does the same for the seeded sub-agent rows.
+    if (status.messages.length > 0) {
       this.state.rebuildToolCallIndex();
     }
 
-    initialStatus.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
-    if (!initialStatus.startedAt) {
-      initialStatus.startedAt = utcTimestamp();
-    }
-
-    this.usageAccumulator = new UsageAccumulator();
-    this.subAgentTracker = new SubAgentTracker();
+    this.subAgentTracker = new SubAgentTracker(status.subAgentExecutions);
   }
 
   setApprovalProvider(provider: ApprovalPolicyProvider): void {
@@ -83,6 +115,16 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     return this.state.proto;
   }
 
+  /**
+   * True once a tool call this turn was gated and left WAITING_APPROVAL: the
+   * engine has interrupted (or will, at this step's end) and the turn should
+   * end awaiting a decision. A fact about the transcript, not a phase — the
+   * caller owns the phase.
+   */
+  get awaitingApproval(): boolean {
+    return this._awaitingApproval;
+  }
+
   get forceNextUpdate(): boolean {
     return this._forceNextUpdate;
   }
@@ -119,6 +161,9 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
       }
 
       if (this.subAgentTracker.isSubAgentNamespace(event.namespace)) {
+        // A sub-agent's spend is the execution's spend (Q-M2b-1): report it
+        // through the one hook before the tracker folds the message.
+        if (event.kind === "message_finish" && event.usage) this.onUsage?.(event.usage);
         this.subAgentTracker.routeEvent(event);
         return;
       }
@@ -219,7 +264,7 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     }
 
     if (usage) {
-      this.accumulateV3Usage(usage);
+      this.onUsage?.(usage);
     }
   }
 
@@ -257,8 +302,9 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     namespace: string,
   ): void {
     // Resume reconciliation: the gated tool call already exists, seeded from the
-    // persisted transcript of a prior invocation (seedStatusFromExecution in
-    // index.ts). The durable checkpoint re-emits tool_started now that approval
+    // persisted transcript of a prior invocation (the runtime's
+    // `seedFromPersistedStatus`, `harness/turn-context.ts`). The durable
+    // checkpoint re-emits tool_started now that approval
     // is granted — flip the existing call to RUNNING in place rather than
     // appending a duplicate or re-triggering the approval gate. v3 keys by
     // tool_call_id, so this is an exact match (no name heuristics needed).
@@ -270,7 +316,6 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
       if (Object.keys(input).length > 0 && !existing.args) {
         existing.args = input as JsonObject;
       }
-      this.state.toolStartTimes.set(callId, performance.now());
       this._forceNextUpdate = true;
       return;
     }
@@ -304,7 +349,8 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
 
     // Stamp authorization provenance in the same spot as tool_kind, for every
     // observed tool call (gated or auto-approved). A gated call is re-seeded on
-    // reinvocation (index.ts) with the same source carried through the interrupt.
+    // reinvocation (the runtime's wide seed) with the same source carried
+    // through the interrupt.
     stampApprovalProvenance(tc, this.approvalProvider);
 
     if (approvalReq.requiresApproval) {
@@ -317,12 +363,11 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
         tc.argsPreview = argsPreview;
       }
 
-      this.state.proto.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
+      this._awaitingApproval = true;
     }
 
     parentMsg.toolCalls.push(tc);
     this.state.toolCalls.set(callId, tc);
-    this.state.toolStartTimes.set(callId, performance.now());
 
     this._forceNextUpdate = true;
   }
@@ -339,7 +384,6 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     tc.result = extractToolResultV3(output);
     tc.completedAt = utcTimestamp();
     tc.isStreaming = false;
-    this.state.toolStartTimes.delete(callId);
     this.toolArgBuffers.delete(callId);
 
     // Project a completed to-do write into status.todos. deepagents' write_todos
@@ -364,7 +408,6 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     tc.error = message;
     tc.completedAt = utcTimestamp();
     tc.isStreaming = false;
-    this.state.toolStartTimes.delete(callId);
     this.toolArgBuffers.delete(callId);
 
     this._forceNextUpdate = true;
@@ -498,21 +541,6 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     return msg;
   }
 
-  // ── Usage ──────────────────────────────────────────────────────────
-
-  private accumulateV3Usage(usage: V3UsagePayload): void {
-    const meta: Record<string, unknown> = {
-      input_tokens: usage.input_tokens,
-      output_tokens: usage.output_tokens,
-    };
-    if (usage.input_token_details) {
-      meta.cache_read_input_tokens = usage.input_token_details.cache_read;
-      meta.cache_creation_input_tokens = usage.input_token_details.cache_creation;
-    }
-    this.usageAccumulator.accumulate(meta);
-    this.state.proto.streamingUsage = this.usageAccumulator.toProto();
-  }
-
   // ── Sub-Agent Integration ──────────────────────────────────────────
 
   /**
@@ -525,20 +553,13 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
   }
 
   /**
-   * Sync sub-agent executions into the proto for persistence.
-   * Called by the streaming orchestrator before each persist.
-   */
-  syncSubAgentExecutions(): void {
-    if (this.subAgentTracker.hasExecutions()) {
-      this.state.proto.subAgentExecutions = this.subAgentTracker.getExecutions();
-    }
-  }
-
-  /**
-   * Cancel all in-progress sub-agents (called on parent cancellation).
+   * Clear the streaming flag on every sub-agent message still marked as
+   * streaming — what a turn that stopped mid-delegation owes the transcript
+   * beside the CANCELLED status the caller stamps on the row itself
+   * (`shared/subagent-rows.ts` `cancelInProgressSubAgentProtos`, the one
+   * home of that transition for every harness).
    */
-  cancelSubAgents(): void {
-    this.subAgentTracker.cancelAll();
-    this.syncSubAgentExecutions();
+  finalizeSubAgentStreaming(): void {
+    this.subAgentTracker.finalizeAllStreaming();
   }
 }

package/src/harness/__tests__/approval-decisions.test.ts

@@ -0,0 +1,116 @@
+/**
+ * `harness/approval-decisions.ts` — the runtime's one settler of a decision
+ * that never runs the tool. These arms came with the function from the
+ * native harness's `hitl.ts` (`reconcileNonExecutingDecisions`, S3 M1 /
+ * M2a): SKIP and REJECT settle to SKIPPED (REJECT with the pinned reason),
+ * APPROVE and APPROVE_ALL are left to the engine's own events, sub-agent
+ * transcripts are settled alike, and an undecided row is untouched. The
+ * reader half (`approvalDecisionsOf`) is pinned against the Cursor adapter's
+ * own reader in `execute-cursor/__tests__/approval-decisions-agree.test.ts`
+ * and exercised through `turn-context.test.ts`.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { REJECTED_BY_USER_ERROR, terminalizeNonExecutingDecisions } from "../approval-decisions.js";
+
+describe("terminalizeNonExecutingDecisions", () => {
+  function statusWith(
+    toolCalls: Array<{ id: string; status: ToolCallStatus; approvalAction: ApprovalAction }>,
+  ) {
+    return create(AgentExecutionStatusSchema, {
+      messages: [
+        create(AgentMessageSchema, {
+          toolCalls: toolCalls.map(tc =>
+            create(ToolCallSchema, {
+              id: tc.id,
+              name: "test_tool",
+              status: tc.status,
+              approvalAction: tc.approvalAction,
+            }),
+          ),
+        }),
+      ],
+    });
+  }
+
+  it("terminalizes a REJECT decision to SKIPPED with the pinned reason (does not FAIL)", () => {
+    const status = statusWith([{
+      id: "call-reject",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.REJECT,
+    }]);
+
+    terminalizeNonExecutingDecisions(status);
+
+    const tc = status.messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_SKIPPED);
+    expect(tc.error).toBe(REJECTED_BY_USER_ERROR);
+    // The REJECT decision is preserved so the audit trail stays honest.
+    expect(tc.approvalAction).toBe(ApprovalAction.REJECT);
+  });
+
+  it("terminalizes a SKIP decision to SKIPPED (fixes the stuck-WAITING for skip too)", () => {
+    const status = statusWith([{
+      id: "call-skip",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.SKIP,
+    }]);
+
+    terminalizeNonExecutingDecisions(status);
+
+    expect(status.messages[0].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_SKIPPED);
+  });
+
+  it("leaves APPROVE / APPROVE_ALL untouched (the tool executes)", () => {
+    const status = statusWith([
+      { id: "call-approve", status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL, approvalAction: ApprovalAction.APPROVE },
+      { id: "call-approve-all", status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL, approvalAction: ApprovalAction.APPROVE_ALL },
+    ]);
+
+    terminalizeNonExecutingDecisions(status);
+
+    // Still WAITING — real tool events (not this reconciler) terminalize them.
+    expect(status.messages[0].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(status.messages[0].toolCalls[1].status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+
+  it("settles sub-agent transcripts too", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      subAgentExecutions: [
+        create(SubAgentExecutionSchema, {
+          id: "sub-1",
+          messages: [
+            create(AgentMessageSchema, {
+              toolCalls: [create(ToolCallSchema, {
+                id: "sub-call-skip",
+                name: "test_tool",
+                status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+                approvalAction: ApprovalAction.SKIP,
+              })],
+            }),
+          ],
+        }),
+      ],
+    });
+
+    terminalizeNonExecutingDecisions(status);
+
+    expect(status.subAgentExecutions[0].messages[0].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_SKIPPED);
+  });
+
+  it("is a no-op when there are no decided tool calls", () => {
+    const status = statusWith([{
+      id: "call-pending",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.UNSPECIFIED,
+    }]);
+
+    expect(() => terminalizeNonExecutingDecisions(status)).not.toThrow();
+    expect(status.messages[0].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+  });
+});

package/src/harness/__tests__/capture.test.ts

@@ -0,0 +1,268 @@
+/**
+ * The runtime's capture (`harness/capture.ts`) over a REAL git work tree,
+ * without any engine: the pin, the candidate, the stamp, the provenance and
+ * the review decision, each as the runtime performs it between the
+ * resolution phases and the outcome table.
+ *
+ * What is asserted here and nowhere else are the two rules the lift made
+ * one for every harness (S3 M4, Q-M4-5, Q-M4-6):
+ *
+ *  - the stamp reads the ROW's status: a COMPLETED write row created this
+ *    turn is badged, a FAILED or WAITING one is not, a seeded prior-turn row
+ *    keeps its own change set;
+ *  - the provenance scopes by id-novelty and consents by the row's own
+ *    approval: the approved command that executed ON ITS SEEDED ROW (message
+ *    0, the shape both engines produce — F-M4-P3) qualifies the turn, where
+ *    a positional scope missed it.
+ *
+ * The ledger shape itself is `shared/filereview/capture.ts`'s and is pinned
+ * by its own tests and the two harnesses' `file-review-capture` goldens; the
+ * end-to-end pause and reconcile are the kit's runtime arm. The git fixture
+ * is the shared one every file-review scenario stands on.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema, type AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema, ToolCallSchema, type ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ApprovalAction, FileChangeKind, MessageType, SnapshotKind, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { makeInMemoryArtifactStorage } from "../../__test-utils__/fake-artifact-storage.js";
+import { initGitWorkspace } from "../../__test-utils__/git-workspace-fixture.js";
+import { mockWorkspaceBackend } from "../../__test-utils__/mock-workspace.js";
+import type { FileReviewIdentity } from "../capabilities.js";
+import { captureCandidate, deriveCommandProvenance, pinCaptureBaseline } from "../capture.js";
+import type { TurnWorkspace } from "../types.js";
+
+const EXECUTION_ID = "aex-capture-unit";
+const FILE_REVIEW: FileReviewIdentity = { harnessId: "unit", excludePaths: [".unit/scratch.json"] };
+
+function workspaceOver(root: string, turnSeq = 0): TurnWorkspace {
+  return {
+    dirs: [root],
+    primaryDir: root,
+    gitWorkspace: true,
+    captureMode: true,
+    changeSetId: `${EXECUTION_ID}:${turnSeq}`,
+    provision: { workspaceDirs: [root], provisionResults: [], workspaceBackend: mockWorkspaceBackend() },
+  };
+}
+
+/** The three row facts these arms vary: the args (a path for the stamp), the server's verdict, a prior stamp. */
+interface RowFacts {
+  readonly args?: JsonObject;
+  readonly approvalAction?: ApprovalAction;
+  readonly fileChangeSetId?: string;
+}
+
+function row(id: string, name: string, status: ToolCallStatus, extra: RowFacts = {}): ToolCall {
+  return create(ToolCallSchema, { id, name, status, ...extra });
+}
+
+function messageWith(...toolCalls: ToolCall[]) {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls });
+}
+
+describe("harness/capture over a git work tree", () => {
+  let root: string;
+  let status: AgentExecutionStatus;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "stigmer-capture-unit-"));
+    initGitWorkspace(root, { "notes.md": "one\n", "keep.md": "keep\n" });
+    status = create(AgentExecutionStatusSchema, {});
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("outside capture mode there is nothing to pin", async () => {
+    const capture = await pinCaptureBaseline({
+      status,
+      executionId: EXECUTION_ID,
+      workspace: { ...workspaceOver(root), captureMode: false },
+      fileReview: FILE_REVIEW,
+      artifactStorage: undefined,
+    });
+    expect(capture).toBeUndefined();
+    expect(status.fileReviewEventStream).toBeUndefined();
+  });
+
+  it("pins the baseline, captures the net change after the turn, stamps only the COMPLETED write rows, and reports the review pending", async () => {
+    const workspace = workspaceOver(root);
+    const capture = (await pinCaptureBaseline({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined }))!;
+    expect(capture.baselineTree).toMatch(/^[0-9a-f]{40}$/);
+    expect(status.fileReviewEventStream?.events.map((e) => e.payload.case)).toEqual(["baselineCaptured"]);
+
+    // The engine's turn: one edit flowed, one edit failed, one write is still
+    // waiting at a gate (a deny-and-retry harness's denied row); an excluded
+    // path written by the harness itself must never reach the diff.
+    writeFileSync(join(root, "notes.md"), "one\ntwo\n");
+    mkdirSync(join(root, ".unit"));
+    writeFileSync(join(root, ".unit/scratch.json"), "{}");
+    status.messages.push(
+      messageWith(
+        row("tc-flowed", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED, { args: { file_path: "notes.md", content: "one\ntwo\n" } }),
+        row("tc-failed", "write_file", ToolCallStatus.TOOL_CALL_FAILED, { args: { file_path: "other.md" } }),
+        row("tc-denied", "write_file", ToolCallStatus.TOOL_CALL_WAITING_APPROVAL, { args: { file_path: ".env" } }),
+      ),
+    );
+
+    const pending = await captureCandidate({
+      status,
+      executionId: EXECUTION_ID,
+      workspace,
+      fileReview: FILE_REVIEW,
+      artifactStorage: undefined,
+      capture,
+      globalBypass: false,
+    });
+
+    expect(pending).toBe(true);
+    const events = status.fileReviewEventStream?.events ?? [];
+    expect(events.map((e) => e.payload.case)).toEqual(["baselineCaptured", "candidateCaptured"]);
+    const candidate = events[1]!.payload;
+    if (candidate.case !== "candidateCaptured") throw new Error("unreachable");
+    expect(candidate.value.changes.map((c) => c.pathAfter), "the excluded path never enters the diff").toEqual(["notes.md"]);
+    expect(candidate.value.candidateSnapshot?.kind).toBe(SnapshotKind.GIT_TREE_REF);
+    expect(candidate.value.commandProvenance, "a file-tool turn never qualifies for auto-keep").toBeUndefined();
+
+    const byId = new Map(status.messages.flatMap((m) => m.toolCalls).map((tc) => [tc.id, tc.fileChangeSetId]));
+    expect(byId.get("tc-flowed"), "the COMPLETED write is badged").toBe(workspace.changeSetId);
+    expect(byId.get("tc-failed"), "a FAILED write did not land").toBe("");
+    expect(byId.get("tc-denied"), "a WAITING write did not land").toBe("");
+  });
+
+  it("a turn that changed nothing authors no candidate and pends no review", async () => {
+    const workspace = workspaceOver(root);
+    const capture = (await pinCaptureBaseline({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined }))!;
+    const pending = await captureCandidate({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined, capture, globalBypass: false });
+    expect(pending).toBe(false);
+    expect(status.fileReviewEventStream?.events.map((e) => e.payload.case)).toEqual(["baselineCaptured"]);
+  });
+
+  it("a turn that changed nothing on the tree stamps no row, even a COMPLETED write whose edit was reverted before the boundary", async () => {
+    const workspace = workspaceOver(root);
+    const capture = (await pinCaptureBaseline({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined }))!;
+    status.messages.push(messageWith(row("tc-reverted", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED, { args: { file_path: "notes.md" } })));
+    // The engine wrote and then wrote the original back: no net change.
+    writeFileSync(join(root, "notes.md"), "one\n");
+
+    const pending = await captureCandidate({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined, capture, globalBypass: false });
+
+    expect(pending).toBe(false);
+    expect(status.messages[0]!.toolCalls[0]!.fileChangeSetId, "a row must never reference a change set that does not exist").toBe("");
+  });
+
+  it("the progress substrate follows the workspace shape: git-only without storage surfaces the tracked change; CAS reads what the adapter bound", async () => {
+    const gitOnly = (await pinCaptureBaseline({ status, executionId: EXECUTION_ID, workspace: workspaceOver(root), fileReview: FILE_REVIEW, artifactStorage: undefined }))!;
+    writeFileSync(join(root, "notes.md"), "one\ntwo\n");
+    const tracked = await gitOnly.progress.substrate.capture();
+    expect(tracked.changed).toBe(true);
+    expect(tracked.delta.entries.map((e) => e.pathAfter)).toEqual(["notes.md"]);
+
+    // A non-git workspace with storage: the CAS slice alone, over the reader
+    // the adapter binds; unbound it reads nothing observed.
+    const casRoot = mkdtempSync(join(tmpdir(), "stigmer-capture-cas-"));
+    try {
+      const casWorkspace: TurnWorkspace = { ...workspaceOver(casRoot), gitWorkspace: false };
+      const cas = (await pinCaptureBaseline({
+        status: create(AgentExecutionStatusSchema, {}),
+        executionId: EXECUTION_ID,
+        workspace: casWorkspace,
+        fileReview: FILE_REVIEW,
+        artifactStorage: makeInMemoryArtifactStorage().storage,
+      }))!;
+      expect(cas.baselineTree, "a non-git baseline is the CAS manifest, not a tree").toBe("");
+      writeFileSync(join(casRoot, "scratch.log"), "line\n");
+      expect((await cas.progress.substrate.capture()).delta.entries, "nothing bound, nothing observed").toEqual([]);
+      cas.casObservations = () => ({ before: new Map([["scratch.log", null]]), blockedSecretPaths: new Set() });
+      const observed = await cas.progress.substrate.capture();
+      expect(observed.delta.entries.map((e) => [e.pathAfter, e.kind])).toEqual([["scratch.log", FileChangeKind.ADD]]);
+    } finally {
+      rmSync(casRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("scopes the stamp to this turn: a seeded prior-turn row keeps its change set, a sub-agent row created this turn takes the parent's", async () => {
+    // The seed a reinvocation carries: a prior turn's flowed row and a prior sub-agent row.
+    status.messages.push(messageWith(row("tc-prior", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED, { fileChangeSetId: `${EXECUTION_ID}:0` })));
+    status.subAgentExecutions.push(
+      create(SubAgentExecutionSchema, { id: "sa-prior", name: "editor", messages: [messageWith(row("sa-tc-prior", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED))] }),
+    );
+    const workspace = workspaceOver(root, 1);
+    const capture = (await pinCaptureBaseline({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined }))!;
+
+    writeFileSync(join(root, "keep.md"), "kept and changed\n");
+    status.subAgentExecutions[0]!.messages.push(messageWith(row("sa-tc-new", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED)));
+
+    await captureCandidate({ status, executionId: EXECUTION_ID, workspace, fileReview: FILE_REVIEW, artifactStorage: undefined, capture, globalBypass: false });
+
+    expect(status.messages[0]!.toolCalls[0]!.fileChangeSetId, "the prior turn's row is untouched").toBe(`${EXECUTION_ID}:0`);
+    const sub = status.subAgentExecutions[0]!.messages.flatMap((m) => m.toolCalls);
+    expect(sub.find((tc) => tc.id === "sa-tc-prior")!.fileChangeSetId, "the prior sub-agent row is untouched").toBe("");
+    expect(sub.find((tc) => tc.id === "sa-tc-new")!.fileChangeSetId, "this turn's sub-agent row takes the parent set").toBe(`${EXECUTION_ID}:1`);
+  });
+});
+
+describe("deriveCommandProvenance — one rule for both engines (F-M4-P3)", () => {
+  const seededShell = (status: ToolCallStatus, approvalAction: ApprovalAction) =>
+    row("tc-shell", "shell", status, { approvalAction, args: { command: "make generate" } });
+
+  it("qualifies the approved command that executed ON ITS SEEDED ROW — the shape a positional scope missed", () => {
+    // Turn 1 left the gate row WAITING at message 0; the reinvocation
+    // reconciled the re-attempt onto it: same id, same position, COMPLETED,
+    // the server's APPROVE preserved. It had NOT settled before this turn.
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [
+        messageWith(seededShell(ToolCallStatus.TOOL_CALL_COMPLETED, ApprovalAction.APPROVE)),
+        create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "Generated." }),
+      ],
+    });
+    const provenance = deriveCommandProvenance(status, { priorSettledToolCallIds: new Set(), priorSubAgentToolCallIds: new Set() }, false);
+    expect(provenance?.consentToolCallIds).toEqual(["tc-shell"]);
+    expect(provenance?.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("the gate turn itself does not qualify: the proposed command is WAITING, not executed", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [messageWith(seededShell(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL, ApprovalAction.UNSPECIFIED))],
+    });
+    expect(deriveCommandProvenance(status, { priorSettledToolCallIds: new Set(), priorSubAgentToolCallIds: new Set() }, false)).toBeUndefined();
+  });
+
+  it("a command settled before this turn is prior history and cannot qualify or disqualify it", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [
+        messageWith(seededShell(ToolCallStatus.TOOL_CALL_COMPLETED, ApprovalAction.APPROVE)),
+        messageWith(row("tc-read", "read_file", ToolCallStatus.TOOL_CALL_COMPLETED)),
+      ],
+    });
+    expect(
+      deriveCommandProvenance(status, { priorSettledToolCallIds: new Set(["tc-shell"]), priorSubAgentToolCallIds: new Set() }, false),
+      "no executed consented command THIS turn",
+    ).toBeUndefined();
+  });
+
+  it("any sub-agent activity this turn fails closed (DD-28 D1)", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [messageWith(seededShell(ToolCallStatus.TOOL_CALL_COMPLETED, ApprovalAction.APPROVE))],
+      subAgentExecutions: [create(SubAgentExecutionSchema, { id: "sa", messages: [messageWith(row("sa-tc", "write_file", ToolCallStatus.TOOL_CALL_COMPLETED))] })],
+    });
+    expect(deriveCommandProvenance(status, { priorSettledToolCallIds: new Set(), priorSubAgentToolCallIds: new Set() }, false)).toBeUndefined();
+  });
+
+  it("under the global bypass an executed unconsented command is attributed to auto_approve_all", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [messageWith(row("tc-shell", "shell", ToolCallStatus.TOOL_CALL_COMPLETED, { args: { command: "make" } }))],
+    });
+    const provenance = deriveCommandProvenance(status, { priorSettledToolCallIds: new Set(), priorSubAgentToolCallIds: new Set() }, true);
+    expect(provenance?.authorizedByAutoApproveAll).toBe(true);
+    expect(provenance?.consentToolCallIds).toEqual([]);
+  });
+});