@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/harness/__tests__/turn-context.test.ts

@@ -2,20 +2,25 @@
  * Pins the turn context's pure decisions — the three places `turn-context.ts`
  * decides something rather than fetching it:
  *
- *  - `isReinvocation`: the one reading of "does the engine already hold state
- *    for this execution", keyed on how the harness mints its state id. The
- *    engine-minted arm is today's `!!threadId`; the deterministic arm refuses
- *    until the native adapter lands (S3), and the refusal is pinned so a
- *    future caller cannot get a silent `false`.
- *  - `approvalDecisionsOf`: the runtime's reader of adjudicated approvals,
+ *  - `isReinvocation`: the runtime's one reading of "does this invocation
+ *    resume rather than begin", keyed on how the harness mints its state id.
+ *    The engine-minted arm is `!!threadId`; the deterministic arm is the
+ *    persisted transcript's non-emptiness, whatever the thread id says (the
+ *    id exists on the first turn too), and never the live engine checkpoint.
+ *  - `approvalDecisionsOf` (`approval-decisions.ts`): the runtime's reader of adjudicated approvals,
  *    over a transcript that carries every row shape it must include or
  *    exclude. Its agreement with the Cursor adapter's own reader
  *    (`reconstructAdjudicatedApprovals`) is pinned from the adapter's side
  *    (`activities/execute-cursor/__tests__/approval-state.test.ts`), because
  *    `src/harness/` never imports `src/activities/`, tests included.
- *  - `decideReinvocation`: the four ways a resume proceeds (reject fails,
- *    approvals run, a clean file-review resume completes, a failed or
- *    partially discarded one completes with its facts carried).
+ *  - `decideReinvocation`: the three ways a resume proceeds (any decision
+ *    runs the agent — REJECT included since S3 M1 —, a clean file-review
+ *    resume completes, a failed or partially discarded one completes with
+ *    its facts carried).
+ *  - `regeneratesApprovedWrites`: which pause primitives make the runner pin
+ *    an approved whole-file write's bytes itself (the engine re-runs the
+ *    model) and which never do (the engine applies the exact args it paused
+ *    on). S3 M2a, Q-M2a-3.
  *
  * The phases that fetch and provision are exercised end to end by the
  * hermetic goldens (`activities/execute-cursor/__tests__/hermetic/`), which
@@ -25,30 +30,53 @@
 
 import { describe, expect, it } from "vitest";
 import { create } from "@bufbuild/protobuf";
-import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSchema, 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, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
-import { approvalDecisionsOf, decideReinvocation, isReinvocation, type ReinvocationFacts } from "../turn-context.js";
+import { approvalDecisionsOf } from "../approval-decisions.js";
+import { decideReinvocation, isReinvocation, regeneratesApprovedWrites, type ReinvocationFacts } from "../turn-context.js";
 
 const INPUT = { executionId: "aex_1", threadId: "", turnSeq: 0 } as const;
 
+/** An execution with no persisted history (a first run) or with `n` persisted AI rows (a continuation). */
+function executionWithTranscript(rows: number) {
+  return create(AgentExecutionSchema, {
+    status: {
+      messages: Array.from({ length: rows }, (_, i) =>
+        create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: `row ${i}` }),
+      ),
+    },
+  });
+}
+const FIRST_RUN = executionWithTranscript(0);
+const CONTINUATION = executionWithTranscript(1);
+
 describe("isReinvocation", () => {
   it("engine-minted: an empty state id is a first turn, any id is a resume", () => {
-    expect(isReinvocation("engine-minted", INPUT)).toBe(false);
-    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42" })).toBe(true);
+    expect(isReinvocation("engine-minted", INPUT, FIRST_RUN)).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42" }, FIRST_RUN)).toBe(true);
   });
 
   it("engine-minted: turnSeq is NOT the signal (a pure-reconcile turn does not advance it; the legacy wire shape yields 0)", () => {
-    expect(isReinvocation("engine-minted", { ...INPUT, turnSeq: 3 })).toBe(false);
-    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42", turnSeq: 0 })).toBe(true);
+    expect(isReinvocation("engine-minted", { ...INPUT, turnSeq: 3 }, FIRST_RUN)).toBe(false);
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42", turnSeq: 0 }, FIRST_RUN)).toBe(true);
   });
 
-  it("deterministic: refuses rather than guess until the native adapter lands (S3)", () => {
-    expect(() => isReinvocation("deterministic", { ...INPUT, threadId: "thread-1" })).toThrow(
-      /deterministic arm lands with the native adapter \(S3\)/,
-    );
+  it("engine-minted: the transcript is NOT the signal (the bound id is; a follow-up turn with a bound id and an empty transcript still resumes the engine)", () => {
+    expect(isReinvocation("engine-minted", { ...INPUT, threadId: "agent-42" }, FIRST_RUN)).toBe(true);
+    expect(isReinvocation("engine-minted", INPUT, CONTINUATION)).toBe(false);
+  });
+
+  it("deterministic: the persisted transcript is the signal — empty is a first run, any committed history is a continuation", () => {
+    expect(isReinvocation("deterministic", { ...INPUT, threadId: "thread-ses_1" }, FIRST_RUN)).toBe(false);
+    expect(isReinvocation("deterministic", { ...INPUT, threadId: "thread-ses_1" }, CONTINUATION)).toBe(true);
+  });
+
+  it("deterministic: the thread id is NOT the signal (a deterministic harness has one on its first turn too)", () => {
+    expect(isReinvocation("deterministic", { ...INPUT, threadId: "thread-ses_1", turnSeq: 0 }, FIRST_RUN)).toBe(false);
+    expect(isReinvocation("deterministic", { ...INPUT, threadId: "", turnSeq: 0 }, CONTINUATION)).toBe(true);
   });
 });
 
@@ -135,21 +163,22 @@ describe("decideReinvocation", () => {
     expect(decideReinvocation(facts())).toBeUndefined();
   });
 
-  it("any REJECT among the adjudicated decisions fails the turn, whatever else was decided", () => {
+  it("a REJECT runs the agent like any other decision — the run continues without the tool (stigmer#197; S3 M1, Q-S3-2)", () => {
+    // Until S3 M1 this returned `{ kind: "rejected-by-user" }` and the runtime
+    // FAILED the execution before any engine ran, contradicting the proto, the
+    // conformance suite and the native harness (S2 M4 finding F1).
     const decisions = new Map([
       ["tc-1", ApprovalAction.APPROVE],
       ["tc-2", ApprovalAction.REJECT],
     ]);
-    expect(decideReinvocation(facts({ approvalDecisions: decisions }))).toEqual({ kind: "rejected-by-user" });
+    expect(decideReinvocation(facts({ approvalDecisions: decisions }))).toBeUndefined();
+    expect(decideReinvocation(facts({ approvalDecisions: new Map([["tc-2", ApprovalAction.REJECT]]) }))).toBeUndefined();
   });
 
-  it("approvals without a reject run the agent, even when file review was also reconciled", () => {
+  it("any adjudicated decision runs the agent, even when file review was also reconciled", () => {
     const decisions = new Map([["tc-1", ApprovalAction.APPROVE]]);
     expect(decideReinvocation(facts({ approvalDecisions: decisions, reconciledFileReview: true }))).toBeUndefined();
-    expect(
-      decideReinvocation(facts({ approvalDecisions: new Map([["tc-1", ApprovalAction.SKIP]]) })),
-      "a SKIP is not a reject",
-    ).toBeUndefined();
+    expect(decideReinvocation(facts({ approvalDecisions: new Map([["tc-1", ApprovalAction.SKIP]]) }))).toBeUndefined();
   });
 
   it("a pure file-review resume completes, carrying the reconcile's facts", () => {
@@ -176,3 +205,21 @@ describe("decideReinvocation", () => {
     });
   });
 });
+
+describe("regeneratesApprovedWrites", () => {
+  it("a deny-and-retry engine re-prompts the model with grants, so the runner pins the approved bytes", () => {
+    expect(regeneratesApprovedWrites("deny-and-retry")).toBe(true);
+  });
+
+  it("a callback engine's resumed session re-attempts the call, so the runner pins the approved bytes", () => {
+    expect(regeneratesApprovedWrites("callback")).toBe(true);
+  });
+
+  it("an interrupt engine applies the exact args it paused on — a runner-side write would land twice and pre-empt the row", () => {
+    expect(regeneratesApprovedWrites("interrupt")).toBe(false);
+  });
+
+  it("a gate-less engine has nothing approved to apply", () => {
+    expect(regeneratesApprovedWrites("none")).toBe(false);
+  });
+});

package/src/harness/approval-decisions.ts

@@ -0,0 +1,104 @@
+/**
+ * The runtime's one reader and one settler of a user's approval decision.
+ *
+ * A decision lives on the tool-call row the server owns
+ * (`ToolCall.approval_action`, written by `SubmitApproval`); the runtime
+ * reads it at the start of a reinvocation and settles the rows that never
+ * run at the end of it. Both acts are here so the two halves of one
+ * transition cannot drift apart:
+ *
+ *  - {@link approvalDecisionsOf} reads every top-level row still
+ *    WAITING_APPROVAL whose action is set. The WAITING filter is what keeps a
+ *    decided row from being re-gated on the NEXT reinvocation (its row is
+ *    COMPLETED or SKIPPED by then) and what lets the adapter still describe
+ *    the decision to its engine on THIS one (Cursor's reinvocation prompt
+ *    names the skipped and rejected actions in human terms).
+ *  - {@link terminalizeNonExecutingDecisions} settles SKIP and REJECT rows to
+ *    TOOL_CALL_SKIPPED (REJECT also carries `error: "Rejected by user"`),
+ *    root and sub-agent transcripts alike. The runtime calls it once,
+ *    immediately after `adapter.runTurn` returns and before any persist of
+ *    the outcome, for EVERY outcome: a decision that never runs the tool has
+ *    no engine event to flip its row, so the row would otherwise persist
+ *    WAITING on a completed execution. APPROVE and APPROVE_ALL are not
+ *    touched — the tool executes, and the adapter's own events settle it.
+ *
+ * Why after the adapter, not before: both readers above filter on WAITING, so
+ * stamping first would hide the decision from the reinvocation prompt and
+ * from the exact-apply. Why by decision and not by row status: the outcome
+ * of SKIP and REJECT is fully determined by the recorded decision, whatever
+ * transient status an engine left (a denial ToolMessage with no tool events,
+ * or a replay that never re-drove the gate), so the stamp is idempotent and
+ * checkpointer-independent by construction. REJECT and SKIP share SKIPPED as
+ * the terminal status (the tool did not run) and stay distinguishable by
+ * `approval_action` and by the server's append-only approval-event stream.
+ *
+ * This is the contract as of stigmer#197: REJECT denies the tool and the run
+ * CONTINUES; it never fails the execution. The native harness proved it
+ * (`hitl.ts` `reconcileNonExecutingDecisions`, moved here at S3 M1) and the
+ * conformance suite (`agentexecution-approval.conformance.test.ts`) is its
+ * arbiter for both harnesses.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/** The row's error for a REJECT; byte-pinned by the native goldens (`reject.turn2.status.json`) and the conformance suite. */
+export const REJECTED_BY_USER_ERROR = "Rejected by user";
+
+/**
+ * Every top-level tool-call row still WAITING_APPROVAL whose `approvalAction`
+ * the server has set, keyed by tool-call id, in transcript order. Derived
+ * from the status on every invocation, never stored, so it cannot drift from
+ * the rows. The same rows, in the same order, that the Cursor adapter's
+ * `reconstructAdjudicatedApprovals` reads for its own facts (the
+ * pending-approval protos and content digests); a test pins the two
+ * readers' agreement.
+ */
+export function approvalDecisionsOf(status: AgentExecutionStatus): ReadonlyMap<string, ApprovalAction> {
+  const decisions = new Map<string, ApprovalAction>();
+  for (const message of status.messages) {
+    for (const row of message.toolCalls) {
+      if (row.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL) continue;
+      if (row.approvalAction === ApprovalAction.UNSPECIFIED) continue;
+      decisions.set(row.id, row.approvalAction);
+    }
+  }
+  return decisions;
+}
+
+/**
+ * Settle every SKIP and REJECT row to TOOL_CALL_SKIPPED, root and sub-agent
+ * transcripts, in place. Idempotent: a row already settled carries the same
+ * decision and re-settles identically. A REJECT row's `error` is set only
+ * when empty, so an engine's own denial text, if any, stands.
+ */
+export function terminalizeNonExecutingDecisions(status: AgentExecutionStatus): void {
+  const settle = (messages: readonly AgentMessage[]): void => {
+    for (const message of messages) {
+      for (const row of message.toolCalls) {
+        switch (row.approvalAction) {
+          case ApprovalAction.SKIP:
+            row.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+            break;
+          case ApprovalAction.REJECT:
+            row.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+            if (!row.error) row.error = REJECTED_BY_USER_ERROR;
+            break;
+          case ApprovalAction.UNSPECIFIED:
+          case ApprovalAction.APPROVE:
+          case ApprovalAction.APPROVE_ALL:
+            break;
+          default: {
+            const exhaustive: never = row.approvalAction;
+            throw new Error(`terminalizeNonExecutingDecisions: unknown approval action ${String(exhaustive)}`);
+          }
+        }
+      }
+    }
+  };
+  settle(status.messages);
+  for (const subAgent of status.subAgentExecutions) {
+    settle(subAgent.messages);
+  }
+}

package/src/harness/capabilities.ts

@@ -9,6 +9,15 @@
  * Every row of the matrix below is either a flag here or internal to one
  * adapter; nothing in it needed a third kind of thing.
  *
+ * One flag is declared for the matrix and read by no runtime phase today:
+ * `systemPrompt`. Its readers are the adapters' own prompt builders, by
+ * placement (the native builder renders a system prompt rebuilt every turn;
+ * the Cursor builder renders the session's first user message), and the
+ * shared prompt glue (`shared/prompt-sections.ts`) is written so that
+ * placement stays each adapter's. The runtime would branch on it only if it
+ * ever composed prompts itself — the S4/S5 unification question, not a phase
+ * that exists (S3 M5, Q-M5-6).
+ *
  * The matrix the contract was designed against (2026-09; Claude and Codex are
  * the surveyed SDKs, not built harnesses):
  *
@@ -63,13 +72,15 @@ export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none
 export type StateIdSource = "deterministic" | "engine-minted";
 
 /**
- * The two facts the runtime's file-review reconcile needs from the harness
- * and cannot know: the id the projection reads from the BASELINE payload
- * (`shared/filereview/capture.ts` `applyCaptureDecisions`), and the
+ * The two facts the runtime's file-review capture and reconcile need from
+ * the harness and cannot know: the id the projection reads from the
+ * BASELINE payload (`shared/filereview/capture.ts`), and the
  * workspace-relative paths the harness writes into the repo that a turn's
  * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
- * once per adapter, read by `turn-context.ts` (ruled Q-M2-6 as an argument,
- * homed here at M3).
+ * once per adapter, read by `harness/capture.ts` (the pin, the progress
+ * slice, the candidate) and `turn-context.ts` (the reconcile). Ruled Q-M2-6
+ * as an argument, homed here at S2 M3; the capture joined the reconcile as a
+ * reader at S3 M4.
  */
 export interface FileReviewIdentity {
   readonly harnessId: string;

package/src/harness/capture.ts

@@ -0,0 +1,301 @@
+/**
+ * The runtime's file-review capture — apply-then-review for every harness,
+ * written once: the baseline pinned before the engine runs, the mid-run
+ * progress the chokepoint refreshes on every write, the candidate captured
+ * after the engine's turn, the DD-28 approved-command provenance, the flowed
+ * transcript rows stamped with the change set, and the one question the
+ * outcome table asks afterwards: is a review pending?
+ *
+ * ONE CAPTURE, ONE MOMENT, ONE OWNER
+ * ----------------------------------
+ * A turn's reviewable change is a property of the TREE, not of the engine:
+ * whatever sits on the working tree when the engine's turn is over is what
+ * the user reviews, whoever wrote it — the engine, a sub-agent, a recovery
+ * retry, a stdio MCP server the engine spawned. So the runtime pins the
+ * baseline as its LAST act before `adapter.runTurn` (after its own writes
+ * into the tree — the reconcile, the skill and attachment mounts — so they
+ * cancel out of the diff) and captures ONCE after `runTurn` returns, over
+ * the whole turn. Anything written into the tree after the pin is the
+ * turn's change. An adapter needs neither the baseline nor the change-set
+ * id and never learns whether a review is pending; the one fact it holds
+ * that the runtime cannot read is what its engine observed touching
+ * CAS-owned paths (`TurnSink.bindCasObservations`).
+ *
+ * Until S3 M4 both adapters carried this whole act (Cursor in its
+ * `turn-boundary.ts` between the stream and `run.wait()`, the deep-agent in
+ * its `turn-settle.ts`), each with its own evidence source and its own
+ * scoping rules for the provenance and the stamp. The two rules here are the
+ * one reading both engines already produce:
+ *
+ *  - PROVENANCE (DD-28, `shared/filereview/command-provenance.ts` is the
+ *    rule; this is its two inputs). "This turn's commands" are the top-level
+ *    rows whose id had not SETTLED before the engine ran — never a message
+ *    position, because on BOTH engines an approved command executes on the
+ *    row the runtime seeded for it (the deep-agent's builder and Cursor's
+ *    translator both reconcile the re-attempt onto the seeded WAITING row),
+ *    at its prior position; a positional scope misses it (F-M4-P3: Cursor's
+ *    did, so its auto-keep never qualified a gated-then-approved command).
+ *    "Executed" is a COMPLETED row. "Consented" is the row's own
+ *    server-authored `approval_action` — the seeded row keeps its id and its
+ *    verdict when it executes on resume, so the executed command IS its
+ *    consent row. Any sub-agent activity fails closed (DD-28 D1).
+ *  - THE STAMP (`shared/tool-row.ts` `stampFlowedFileEditRows`). A write or
+ *    delete row created this turn that reached COMPLETED flowed onto the
+ *    tree and is badged with the change set; a WAITING (denied, gated) or
+ *    FAILED row did not and is not. The row's own status is the evidence,
+ *    not a ledger of denial tokens.
+ *
+ * WHAT IS NOT HERE
+ * ----------------
+ * The substrate and the ledger authoring (`shared/filereview/capture.ts`,
+ * `cas-touched.ts`, `progress.ts`); the resume-time reconcile
+ * (`turn-context.ts` `reconcileReinvocation`, already the runtime's since
+ * S2); the outcome matrix that turns "a review is pending" into a phase
+ * (`run-turn.ts`, through `terminal-table.ts` `awaitingReviewArm`).
+ *
+ * TWO GAPS THIS MODULE DOES NOT CLOSE (recorded for S5, S3 M4 F-M4-P-gaps)
+ * ----------------------------------------------------------------------
+ * A turn that ends `interrupted` is not captured (a stop fired; the tree may
+ * be mid-edit). So a platform STOP returns COMPLETED with unreviewed edits
+ * on the tree, and a pause or worker shutdown reinvokes the same turn, whose
+ * new pin absorbs the pre-pause edits into its baseline and authors a second
+ * BASELINE for the same change set. Both predate the lift on both harnesses.
+ */
+
+import { ApprovalAction, FileCaptureClass, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+import type { ArtifactStorage } from "../shared/artifact-storage.js";
+import { captureBaselineToLedger, captureCandidateToLedger } from "../shared/filereview/capture.js";
+import { createCasProgressSubstrate } from "../shared/filereview/cas-progress.js";
+import { buildCasTurnCaptures, type CasTouchedReader, type CasTouchedSnapshot } from "../shared/filereview/cas-touched.js";
+import { qualifyTurnCommandProvenance } from "../shared/filereview/command-provenance.js";
+import { hasCandidateCaptured } from "../shared/filereview/events.js";
+import {
+  createGitProgressSubstrate,
+  createHybridProgressSubstrate,
+  newProgressCaptureState,
+  type ProgressCaptureState,
+  type ProgressSubstrate,
+} from "../shared/filereview/progress.js";
+import { collectSettledToolCallIds, collectSubAgentToolCallIds, stampFlowedFileEditRows, stampFlowedSubAgentFileEditRows } from "../shared/tool-row.js";
+import type { FileReviewIdentity } from "./capabilities.js";
+import type { TurnWorkspace } from "./types.js";
+
+/** The mid-run progress the chokepoint refreshes on every write: the substrate and the floor it throttles by. */
+export interface TurnProgress {
+  readonly changeSetId: string;
+  readonly substrate: ProgressSubstrate;
+  readonly state: ProgressCaptureState;
+}
+
+/**
+ * One turn's capture as the runtime holds it between the pin and the
+ * boundary — a `runTurn` closure value beside the usage accumulator and the
+ * watchdog, on neither `TurnInput` (the adapter needs none of it) nor the
+ * frame (nothing here is a resource to release). Absent outside capture
+ * mode.
+ */
+export interface TurnCapture {
+  readonly changeSetId: string;
+  /** The pre-turn tree on a git work tree; `""` on a non-git one (the CAS manifest is the baseline there). */
+  readonly baselineTree: string;
+  readonly progress: TurnProgress;
+  /** Top-level rows already settled before the engine ran: the complement is "this turn's" (the provenance scope). */
+  readonly priorSettledToolCallIds: ReadonlySet<string>;
+  /** Sub-agent rows present before the engine ran: the stamp's scope, and any growth fails provenance closed. */
+  readonly priorSubAgentToolCallIds: ReadonlySet<string>;
+  /**
+   * What the engine observed touching CAS-owned paths, once the adapter has
+   * bound it (`TurnSink.bindCasObservations`); read at each progress capture
+   * and at the boundary. Unbound reads as nothing observed: git-only capture.
+   */
+  casObservations: CasTouchedReader | undefined;
+}
+
+const NOTHING_OBSERVED: CasTouchedSnapshot = { before: new Map(), blockedSecretPaths: new Set() };
+
+/**
+ * Turn start, in capture mode: snapshot the pre-turn ids, pin the pre-turn
+ * tree behind the baseline ref and author BASELINE_CAPTURED under the
+ * harness's identity (the event rides the next persist), and build the
+ * progress substrate for this workspace shape — the git slice over the
+ * baseline and the harness's excluded paths, the CAS slice over whatever
+ * observations the adapter later binds (a delegating reader, since the bind
+ * happens inside `runTurn`), hybrid when both apply. The CAS slice exists
+ * only when artifact storage does: without it a gitignored write is
+ * deny-gated by the harness (`captureIgnored`), never captured, and the
+ * ledger could not store its blobs anyway.
+ *
+ * Returns `undefined` outside capture mode: nothing to pin, nothing to
+ * capture, the classic deny-gate governs writes.
+ */
+export async function pinCaptureBaseline(args: {
+  readonly status: AgentExecutionStatus;
+  readonly executionId: string;
+  readonly workspace: TurnWorkspace;
+  readonly fileReview: FileReviewIdentity;
+  readonly artifactStorage: ArtifactStorage | undefined;
+}): Promise<TurnCapture | undefined> {
+  const { status, executionId, workspace, fileReview, artifactStorage } = args;
+  if (!workspace.captureMode) return undefined;
+  const { primaryDir, gitWorkspace, changeSetId } = workspace;
+
+  const priorSettledToolCallIds = collectSettledToolCallIds(status.messages);
+  const priorSubAgentToolCallIds = collectSubAgentToolCallIds(status.subAgentExecutions);
+
+  const baselineTree = await captureBaselineToLedger({
+    status,
+    gitRoot: primaryDir,
+    executionId,
+    changeSetId,
+    harnessId: fileReview.harnessId,
+    excludePaths: fileReview.excludePaths,
+    gitWorkspace,
+  });
+
+  const capture: TurnCapture = {
+    changeSetId,
+    baselineTree,
+    progress: {
+      changeSetId,
+      state: newProgressCaptureState(),
+      substrate: buildProgressSubstrate({
+        executionId,
+        workspace,
+        baselineTree,
+        excludePaths: fileReview.excludePaths,
+        casSlice: artifactStorage !== undefined,
+        // Delegates to whatever the adapter binds later; `capture` is
+        // assigned before any capture() can run.
+        readObservations: () => capture.casObservations?.() ?? NOTHING_OBSERVED,
+      }),
+    },
+    priorSettledToolCallIds,
+    priorSubAgentToolCallIds,
+    casObservations: undefined,
+  };
+  return capture;
+}
+
+/**
+ * The progress substrate for this workspace shape (DD-32 / DD-33): a git
+ * tree diffs its tracked paths by `--numstat` against the baseline; the CAS
+ * slice reads the engine's observations for the gitignored (git tree) or
+ * every (non-git) path; a git tree with storage composes both. The truth
+ * table is `deriveCaptureMode`'s: capture mode holds only for a git tree or
+ * a workspace with storage, so the fourth cell is unreachable and says so.
+ */
+function buildProgressSubstrate(args: {
+  readonly executionId: string;
+  readonly workspace: TurnWorkspace;
+  readonly baselineTree: string;
+  readonly excludePaths: readonly string[];
+  readonly casSlice: boolean;
+  readonly readObservations: CasTouchedReader;
+}): ProgressSubstrate {
+  const { executionId, workspace, baselineTree, excludePaths, casSlice, readObservations } = args;
+  const git = workspace.gitWorkspace
+    ? createGitProgressSubstrate({ workspaceRoot: workspace.primaryDir, executionId, baselineTree, excludePaths })
+    : undefined;
+  const cas = casSlice ? createCasProgressSubstrate({ workspaceRoot: workspace.primaryDir, read: readObservations }) : undefined;
+  if (git && cas) return createHybridProgressSubstrate(git, cas);
+  const one = git ?? cas;
+  if (!one) throw new Error(`capture: capture mode on a non-git tree without storage (execution=${executionId}); deriveCaptureMode forbids this`);
+  return one;
+}
+
+/**
+ * Turn end: compose the CAS captures from the bound observations, derive the
+ * approved-command provenance, author CANDIDATE_CAPTURED (the seam authors
+ * nothing for a turn that changed nothing), and — iff a candidate exists —
+ * stamp the flowed rows. The working tree is LEFT applied: the user reviews
+ * the real change, and a reject snaps files back on the resume
+ * (`reconcileReinvocation`). Returns whether a review is now pending.
+ */
+export async function captureCandidate(args: {
+  readonly status: AgentExecutionStatus;
+  readonly executionId: string;
+  readonly workspace: TurnWorkspace;
+  readonly fileReview: FileReviewIdentity;
+  readonly artifactStorage: ArtifactStorage | undefined;
+  readonly capture: TurnCapture;
+  /** `spec.auto_approve_all`, the one whole-run bypass: qualifies every executed command as consented (DD-28). */
+  readonly globalBypass: boolean;
+}): Promise<boolean> {
+  const { status, executionId, workspace, fileReview, artifactStorage, capture, globalBypass } = args;
+  const { primaryDir, gitWorkspace } = workspace;
+  const { changeSetId } = capture;
+
+  const casCaptureClass = gitWorkspace ? FileCaptureClass.GIT_IGNORED_CAPTURED : FileCaptureClass.NON_GIT_CAS;
+  const observed = artifactStorage && capture.casObservations ? await capture.casObservations() : NOTHING_OBSERVED;
+  const { casCaptures, unreviewablePaths } = await buildCasTurnCaptures(observed, primaryDir, casCaptureClass);
+
+  const commandProvenance = deriveCommandProvenance(status, capture, globalBypass);
+  if (commandProvenance) {
+    console.log(
+      `capture: turn qualifies for approved-command auto-keep ` +
+        `(consent rows: ${commandProvenance.consentToolCallIds.join(",") || "(auto_approve_all)"}); ` +
+        `attaching provenance to candidate (execution=${executionId})`,
+    );
+  }
+
+  await captureCandidateToLedger({
+    status,
+    gitRoot: primaryDir,
+    executionId,
+    changeSetId,
+    baselineTree: capture.baselineTree,
+    harnessId: fileReview.harnessId,
+    excludePaths: fileReview.excludePaths,
+    casCaptures,
+    storage: artifactStorage,
+    unreviewablePaths,
+    unreviewableCaptureClass: casCaptureClass,
+    gitWorkspace,
+    commandProvenance,
+  });
+
+  const pending = hasCandidateCaptured(status, changeSetId);
+  if (pending) {
+    // A row must never reference a change set that does not exist, so the
+    // stamp is gated on the authored candidate.
+    stampFlowedFileEditRows(status.messages, changeSetId, { flowed: isCompletedRow });
+    stampFlowedSubAgentFileEditRows(status.subAgentExecutions, changeSetId, capture.priorSubAgentToolCallIds, isCompletedRow);
+    console.log(`capture: change set ${changeSetId} authored to the file_review ledger; working tree left applied for review (execution=${executionId})`);
+  }
+  return pending;
+}
+
+/** The row's own evidence that its effect landed on the tree. */
+function isCompletedRow(tc: ToolCall): boolean {
+  return tc.status === ToolCallStatus.TOOL_CALL_COMPLETED;
+}
+
+/**
+ * The runtime's two inputs to the shared DD-28 rule (see the header). Pure
+ * over the status and the pre-turn snapshots; exported for its own tests.
+ */
+export function deriveCommandProvenance(
+  status: AgentExecutionStatus,
+  capture: Pick<TurnCapture, "priorSettledToolCallIds" | "priorSubAgentToolCallIds">,
+  globalBypass: boolean,
+): TurnCommandProvenance | undefined {
+  // DD-28 D1: any sub-agent activity this turn disqualifies — a sub-agent
+  // that ran contributes at least one row id absent from the pre-turn set,
+  // and its writes fold into this change set without a consented command.
+  for (const id of collectSubAgentToolCallIds(status.subAgentExecutions)) {
+    if (!capture.priorSubAgentToolCallIds.has(id)) return undefined;
+  }
+  const turnToolCalls = status.messages.flatMap((m) => m.toolCalls).filter((tc) => !capture.priorSettledToolCallIds.has(tc.id));
+  return qualifyTurnCommandProvenance({
+    turnToolCalls,
+    messages: status.messages,
+    isExecutedCommand: isCompletedRow,
+    resolveDirectConsent: (tc) =>
+      tc.approvalAction === ApprovalAction.APPROVE || tc.approvalAction === ApprovalAction.APPROVE_ALL ? tc.id : undefined,
+    globalBypass,
+  });
+}

package/src/harness/persist-chokepoint.ts

@@ -10,13 +10,21 @@
  *     any built-in write row targeting a secret-like path, top-level and
  *     sub-agent. The single airtight choke point for a deny-gate harness and
  *     the only guarantee under `auto_approve_all`. Idempotent.
- *  2. `streaming_usage` is refreshed from the accumulator when it has turns,
+ *  2. `file_change_progress` is refreshed from the turn's capture (the "N
+ *     files changed so far" strip, DD-32) when the turn is in capture mode:
+ *     the tree is read at most once per floor interval and only re-attached
+ *     when it moved (`shared/filereview/progress.ts`), so a write that
+ *     changed nothing on disk carries the snapshot it already had. Before
+ *     S3 M4 each adapter's stream loop did this before its own persists; the
+ *     runtime owns the capture now, so the display field it derives is
+ *     refreshed where every other runtime-owned field is — here.
+ *  3. `streaming_usage` is refreshed from the accumulator when it has turns,
  *     so the summary the UI shows is the one the write carries.
- *  3. `persistStatus` (`shared/status.ts`): tool-output offload, the
+ *  4. `persistStatus` (`shared/status.ts`): tool-output offload, the
  *     aggregate size cap, transient retry, oversize recovery. Never rejects.
- *  4. A Temporal heartbeat, so a long streaming turn's liveness is proven by
+ *  5. A Temporal heartbeat, so a long streaming turn's liveness is proven by
  *     the writes it makes (Q-S2-10).
- *  5. The control plane's answer: STOP becomes the runtime's platform-stop
+ *  6. The control plane's answer: STOP becomes the runtime's platform-stop
  *     cause on the stop controller, which aborts the adapter's signal.
  *
  * Single-flight with coalescing: an adapter's `requestPersist()` while a
@@ -39,9 +47,11 @@ import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agent
 import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 
 import type { StigmerClient } from "../client/stigmer-client.js";
+import { captureFileChangeProgress } from "../shared/filereview/progress.js";
 import { persistStatus } from "../shared/status.js";
 import type { ToolOutputOffloadContext } from "../shared/status-offload.js";
 import { withholdSecretContentFromMessages } from "../shared/tool-row.js";
+import type { TurnProgress } from "./capture.js";
 import type { UsageAccumulator } from "./usage-accumulator.js";
 
 export interface PersistChokepointDeps {
@@ -56,6 +66,12 @@ export interface PersistChokepointDeps {
    * and is `undefined` for a write made before then (no usage yet anyway).
    */
   readonly usage: () => UsageAccumulator | undefined;
+  /**
+   * The turn's mid-run progress, read at WRITE time for the same reason as
+   * `usage`: it exists only once the runtime has pinned the capture baseline,
+   * after resolution, and is `undefined` outside capture mode.
+   */
+  readonly progress: () => TurnProgress | undefined;
   /** The Temporal heartbeat, pulsed after each write. */
   readonly heartbeat: () => void;
   /** The control plane answered STOP to this write. */
@@ -99,6 +115,10 @@ export class PersistChokepoint {
   async write(): Promise<void> {
     const { client, executionId, status, offload, heartbeat } = this.deps;
     withholdSecretContentFromMessages(status.messages, status.subAgentExecutions);
+    const progress = this.deps.progress();
+    if (progress) {
+      await captureFileChangeProgress({ status, changeSetId: progress.changeSetId, substrate: progress.substrate, state: progress.state });
+    }
     const usage = this.deps.usage();
     if (usage?.hasTurns) {
       status.streamingUsage = create(StreamingUsageSummarySchema, usage.snapshot());