@stigmer/runner 3.14.0 → 3.15.0

package/src/activities/execute-cursor/__tests__/approval-decisions-agree.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Two readers of one fact must agree: the turn runtime reads the adjudicated
+ * approvals as the VERDICT (`harness/turn-context.ts` `approvalDecisionsOf`,
+ * the `TurnInput.approvalDecisions` the contract carries) and this adapter
+ * reads the same rows for the FACTS beside the verdict (the pending-approval
+ * protos the grant builder and the reinvocation prompt render, the content
+ * digest that authorizes an approved edit by its exact bytes —
+ * `reconstructAdjudicatedApprovals`). The contract's rule is that an adapter
+ * never re-derives the verdict itself, so the two functions must select the
+ * same rows in the same order or the grants would be minted for a different
+ * set than the runtime decided on.
+ *
+ * Lives on the adapter's side because `src/harness/` never imports
+ * `src/activities/`, tests included (`harness/__tests__/import-direction.test.ts`).
+ */
+
+import { describe, expect, it } 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 { ApprovalAction, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { approvalDecisionsOf } from "../../../harness/turn-context.js";
+import { reconstructAdjudicatedApprovals } from "../approval-state.js";
+
+describe("the runtime's approvalDecisionsOf and the adapter's reconstructAdjudicatedApprovals", () => {
+  it("select the same rows in the same order over every row shape a transcript carries", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          toolCalls: [
+            create(ToolCallSchema, {
+              id: "tc-approved",
+              name: "Shell",
+              status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+              approvalAction: ApprovalAction.APPROVE,
+              approvalContentDigest: "sha256:approved",
+            }),
+            create(ToolCallSchema, {
+              id: "tc-undecided",
+              name: "Shell",
+              status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+              approvalAction: ApprovalAction.UNSPECIFIED,
+            }),
+          ],
+        }),
+        create(AgentMessageSchema, {
+          type: MessageType.MESSAGE_AI,
+          toolCalls: [
+            create(ToolCallSchema, {
+              id: "tc-completed",
+              name: "Read",
+              status: ToolCallStatus.TOOL_CALL_COMPLETED,
+              approvalAction: ApprovalAction.APPROVE,
+            }),
+            create(ToolCallSchema, {
+              id: "tc-skipped",
+              name: "Write",
+              status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+              approvalAction: ApprovalAction.SKIP,
+            }),
+            create(ToolCallSchema, {
+              id: "tc-rejected",
+              name: "Write",
+              status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+              approvalAction: ApprovalAction.REJECT,
+            }),
+          ],
+        }),
+      ],
+    });
+
+    const runtime = approvalDecisionsOf(status);
+    const adapter = reconstructAdjudicatedApprovals(status.messages);
+
+    expect([...runtime.entries()]).toEqual([...adapter.decisions.entries()]);
+    expect(
+      adapter.pendingApprovals.map((pa) => pa.toolCallId),
+      "the adapter's row facts cover exactly the rows the runtime decided on",
+    ).toEqual([...runtime.keys()]);
+    expect([...runtime.keys()]).toEqual(["tc-approved", "tc-skipped", "tc-rejected"]);
+  });
+
+  it("both read nothing from a fresh transcript", () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    expect(approvalDecisionsOf(status).size).toBe(0);
+    expect(reconstructAdjudicatedApprovals(status.messages).decisions.size).toBe(0);
+  });
+});

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -12,8 +12,8 @@ import { create } from "@bufbuild/protobuf";
 import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 
-import { appendStructuredOutputDirective, buildPrompt, isHitlReinvocation, primarySendCarriesImages, promptCarriesStandingContext } from "../index.js";
-import type { BuildPromptInput } from "../index.js";
+import { appendStructuredOutputDirective, buildPrompt, isHitlReinvocation, primarySendCarriesImages, promptCarriesStandingContext } from "../prompt-builder.js";
+import type { BuildPromptInput } from "../prompt-builder.js";
 import { buildReinvocationPrompt, formatInteractionModePrefix, formatImplementPlanSection, formatToolApprovalProtocol, buildToolApprovalRuleFile } from "../prompt-builder.js";
 import { PLAN_MODE_DIRECTIVE } from "../../../shared/plan-mode-prompt.js";
 import type { AgentResolution, AgentResolutionReason } from "../session-lifecycle.js";
@@ -38,7 +38,7 @@ function resolution(
 function input(overrides: Partial<BuildPromptInput>): BuildPromptInput {
   return {
     resolution: resolution("local", "resumed_successfully"),
-    approvalDecisions: undefined,
+    approvalDecisions: new Map(),
     instructions: "You are a test agent.",
     userMessage: USER_MESSAGE,
     skills: [],
@@ -357,7 +357,7 @@ describe("buildPrompt", () => {
         const prompt = buildPrompt(
           input({
             resolution: resolution("local", reason),
-            approvalDecisions: hitl ? hitlDecisions : undefined,
+            approvalDecisions: hitl ? hitlDecisions : new Map(),
             pendingApprovals: hitl ? hitlApprovals : [],
             recalledMemories: { facts: ["Prefers OpenTofu."] },
           }),
@@ -395,8 +395,7 @@ describe("buildPrompt", () => {
 });
 
 describe("isHitlReinvocation (paired with resolution.reason at every consumer — issue #366)", () => {
-  it("is false with no decisions and false with an empty map", () => {
-    expect(isHitlReinvocation(undefined)).toBe(false);
+  it("is false with an empty map (the shape a turn with no adjudicated approvals carries)", () => {
     expect(isHitlReinvocation(new Map())).toBe(false);
   });
 
@@ -504,8 +503,8 @@ describe("HITL recovery — fresh agent mid-HITL (issue #366)", () => {
     // resolution-time resume failure.
     expect(primarySendCarriesImages(decisions(), "created_after_resume_failure")).toBe(true);
     // Non-HITL turns always carry the message's images, resumed or not.
-    expect(primarySendCarriesImages(undefined, "resumed_successfully")).toBe(true);
-    expect(primarySendCarriesImages(undefined, "created_first_execution")).toBe(true);
+    expect(primarySendCarriesImages(new Map(), "resumed_successfully")).toBe(true);
+    expect(primarySendCarriesImages(new Map(), "created_first_execution")).toBe(true);
   });
 
   it("the structured-output directive is a pure append shared by the primary and recovery sends — absent schema, absent suffix", () => {

package/src/activities/execute-cursor/__tests__/capture-flow.test.ts

@@ -44,7 +44,7 @@ import {
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import {
-  applyCaptureDecisions,
+  CURSOR_FILE_REVIEW_IDENTITY,
   captureBaselineToLedger,
   captureTurnToLedger,
 } from "../capture-flow.js";
@@ -52,6 +52,33 @@ import { toolIdentity, primaryToken } from "../approval-state.js";
 import { contentDigest } from "../../../shared/file-tools.js";
 import { buildObservationStagingScript, casObservationsDir } from "../cas-observations.js";
 import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
+import { applyCaptureDecisions as sharedApplyCaptureDecisions } from "../../../shared/filereview/capture.js";
+import { casBlobReader } from "../../../shared/filereview/cas-substrate.js";
+import type { ArtifactStorage } from "../../../shared/artifact-storage.js";
+import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+/**
+ * The resume reconcile as the turn runtime runs it for this harness
+ * (`harness/turn-context.ts` `reconcileReinvocation`): the shared reconcile
+ * under Cursor's file-review identity, with the CAS blob reader derived from
+ * the same storage. Bound here so every resume case below proves the Cursor
+ * pair (harness id, excluded gate paths) over the shared code, exactly as
+ * production composes it.
+ */
+function applyCaptureDecisions(opts: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSet: FileChangeSet;
+  readonly storage?: ArtifactStorage;
+  readonly gitWorkspace?: boolean;
+}) {
+  return sharedApplyCaptureDecisions({
+    ...opts,
+    ...CURSOR_FILE_REVIEW_IDENTITY,
+    readBlob: opts.storage ? casBlobReader(opts.storage) : undefined,
+  });
+}
 
 const execFileAsync = promisify(execFile);
 const EXEC_ID = "exec-capflow-1";

package/src/activities/execute-cursor/__tests__/deny-gate-exact-apply.test.ts

@@ -50,7 +50,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { applyApprovedWholeFileWrites, excludeAppliedFromGrants } from "../exact-apply.js";
+import { applyApprovedWholeFileWrites, excludeAppliedFromGrants } from "../../../shared/exact-apply.js";
 import { reconstructAdjudicatedApprovals, buildApprovalGrants } from "../approval-state.js";
 import type { ApprovalGrant } from "../approval-state.js";
 import { LocalWorkspaceBackend } from "../../../shared/workspace/local-backend.js";

package/src/activities/execute-cursor/__tests__/fetch-interceptor.test.ts

@@ -19,7 +19,7 @@ describe("fetch-interceptor", () => {
   let calls: CapturedCall[];
   let installFetchInterceptor: typeof import("../fetch-interceptor.js").installFetchInterceptor;
   let uninstallFetchInterceptor: typeof import("../fetch-interceptor.js").uninstallFetchInterceptor;
-  let getExecutionContext: typeof import("../fetch-interceptor.js").getExecutionContext;
+  let getExecutionContext: typeof import("../../../shared/execution-context.js").getExecutionContext;
 
   beforeEach(async () => {
     calls = [];
@@ -40,7 +40,9 @@ describe("fetch-interceptor", () => {
     const mod = await import("../fetch-interceptor.js");
     installFetchInterceptor = mod.installFetchInterceptor;
     uninstallFetchInterceptor = mod.uninstallFetchInterceptor;
-    getExecutionContext = mod.getExecutionContext;
+    // The store lives in shared/ and must be the SAME fresh instance the
+    // interceptor just imported, so it is resolved after the reset too.
+    getExecutionContext = (await import("../../../shared/execution-context.js")).getExecutionContext;
   });
 
   afterEach(() => {
@@ -50,7 +52,7 @@ describe("fetch-interceptor", () => {
 
   describe("Connect-RPC paths via fetch (BiDi proxy auth injection)", () => {
     beforeEach(() => {
-      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: { current: STIGMER_TOKEN } });
     });
 
     it("injects x-stigmer-auth on /aiserver.v1 path targeting proxy endpoint", async () => {
@@ -139,7 +141,7 @@ describe("fetch-interceptor", () => {
 
   describe("REST path URL rewriting (existing behavior)", () => {
     beforeEach(() => {
-      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: { current: STIGMER_TOKEN } });
     });
 
     it("rewrites Cursor-domain REST URLs and replaces auth", async () => {
@@ -171,9 +173,65 @@ describe("fetch-interceptor", () => {
     });
   });
 
+  describe("the token ref is read per request (the root rotates it in place; Q-S2-7)", () => {
+    let proxyTokenRef: { current: string | null };
+
+    beforeEach(() => {
+      proxyTokenRef = { current: STIGMER_TOKEN };
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef });
+    });
+
+    it("a rotation reaches the next REST rewrite and the next BiDi-auth fetch without a call into the module", async () => {
+      proxyTokenRef.current = "refreshed-stigmer-jwt-token";
+
+      await globalThis.fetch("https://api.cursor.com/v1/models", { headers: { authorization: "Bearer original-key" } });
+      await globalThis.fetch(`${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`, { method: "POST" });
+
+      expect(calls).toHaveLength(2);
+      expect(new Headers(calls[0].init?.headers).get("authorization")).toBe("Bearer refreshed-stigmer-jwt-token");
+      expect(new Headers(calls[1].init?.headers).get("x-stigmer-auth")).toBe("Bearer refreshed-stigmer-jwt-token");
+    });
+
+    it("an emptied ref sends no proxy credential and never leaks the SDK's own authorization to the proxy", async () => {
+      proxyTokenRef.current = null;
+
+      await globalThis.fetch("https://api.cursor.com/v1/models", { headers: { authorization: "Bearer cursor-secret" } });
+      await globalThis.fetch(`${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`, { method: "POST" });
+
+      expect(new Headers(calls[0].init?.headers).get("authorization")).toBeNull();
+      expect(new Headers(calls[1].init?.headers).get("x-stigmer-auth")).toBeNull();
+    });
+  });
+
+  describe("install guard", () => {
+    it("a proxy endpoint with no bound ref fails the install, as a missing token always has, and leaves fetch untouched", () => {
+      const before = globalThis.fetch;
+      expect(() => installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: undefined })).toThrow(
+        /STIGMER_TOKEN is required when STIGMER_PROXY_ENDPOINT is set/,
+      );
+      expect(() => installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: { current: null } })).toThrow(
+        /STIGMER_TOKEN is required when STIGMER_PROXY_ENDPOINT is set/,
+      );
+      expect(globalThis.fetch).toBe(before);
+    });
+
+    it("is idempotent: a second install rebinds the ref and keeps delegating to the fetch captured at load", async () => {
+      const first = { current: "first-token" };
+      const second = { current: "second-token" };
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: first });
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: second });
+
+      await globalThis.fetch(`${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`, { method: "POST" });
+
+      // One hop to the captured fetch (a self-capture would recurse or double-wrap).
+      expect(calls).toHaveLength(1);
+      expect(new Headers(calls[0].init?.headers).get("x-stigmer-auth")).toBe("Bearer second-token");
+    });
+  });
+
   describe("timed REST path timing", () => {
     beforeEach(() => {
-      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: { current: STIGMER_TOKEN } });
     });
 
     /**
@@ -284,7 +342,7 @@ describe("fetch-interceptor", () => {
 
   describe("passthrough (no interception)", () => {
     beforeEach(() => {
-      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, proxyTokenRef: { current: STIGMER_TOKEN } });
     });
 
     it("does NOT intercept Connect-RPC paths on non-proxy hosts", async () => {

package/src/activities/execute-cursor/__tests__/hermetic/deny-and-retry.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Hermetic golden: the DENY-AND-RETRY approval round trip through two real
+ * `ExecuteCursor` invocations, with the REAL bash hook as the out-of-process
+ * half.
+ *
+ * Invariant pinned (the Cursor pause primitive, parent §4a `pausePrimitive:
+ * "deny-and-retry"`): the model proposes a gated built-in (`shell`); the
+ * workspace hook the activity installed DENIES it and appends to the denial
+ * ledger; the stream loop reads the ledger on the next `tool_call` event, cancels
+ * the run, and the turn boundary overlays the row as WAITING_APPROVAL; the
+ * activity persists WAITING_FOR_APPROVAL, parks the agent, and RETURNS a slim
+ * status. The user approves (the server writes `approval_action` on the row —
+ * here the record does, per field ownership). The reinvocation (`thread_id` set,
+ * `turn_seq` 1) seeds its transcript from the persisted execution, derives a
+ * grant from the approved row, reinstalls the gate, and the SAME hook now ALLOWS
+ * the re-issued call — which the model emits under a FRESH `call_id`, and which
+ * the transcript reconciles onto the committed row by canonical identity (a
+ * superset, never a duplicate, never a second gate). The turn ends COMPLETED.
+ *
+ * Two goldens, one per invocation: `goldens/deny-and-retry.turn1.status.json`
+ * (the paused transcript) and `goldens/deny-and-retry.turn2.status.json` (the
+ * resumed, completed transcript). S2 must reproduce both byte for byte.
+ *
+ * Parent phase rows exercised beyond `tool-call`: reinvocation detection and
+ * transcript seeding (Phase 3); reading approval decisions from the persisted
+ * transcript (`reconstructAdjudicatedApprovals`); grants → approval state →
+ * the gate (Phase 5c); the first-denial early stop in the stream loop; the
+ * turn boundary's denial overlay; `enterApprovalPause` (WAITING_FOR_APPROVAL,
+ * park, return); the parked-agent checkout on the resume (#215, no `Agent.resume`
+ * call); the resume prompt.
+ *
+ * The hook is the runner's own generated bash script, found the way the SDK
+ * finds it (`.cursor/hooks.json` in the workspace) and run with the SDK's real
+ * preToolUse input shape (`cursor-hook-harness.ts` builders). Skipped where
+ * `bash` is unavailable — reported as SKIPPED, never a silent pass.
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-cursor/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ApprovalAction,
+  ExecutionPhase,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { hasBash, hookShell } from "../../__test-utils__/cursor-hook-harness.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+  runWorkspaceHook,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const AGENT_ID = "agent-hermetic-deny-0001";
+const RUN_1 = "run-hermetic-deny-0001";
+const RUN_2 = "run-hermetic-deny-0002";
+const CALL_TURN_1 = "call-hermetic-shell-0001";
+const CALL_TURN_2 = "call-hermetic-shell-0002";
+const USER_MESSAGE = "Run the build and tell me if it passes.";
+const COMMAND = "npm run build";
+const SHELL_ARGS = { command: COMMAND };
+const BUILD_OUTPUT = "build ok (hermetic)\n";
+const FINAL_TEXT = "The build passes.";
+
+describe.skipIf(!hasBash)("ExecuteCursor hermetic — deny-and-retry approval round trip", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("pauses on the hook's deny, then completes on the approved re-issue", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const workspaceRoot = sessionWorkspaceDir(env);
+    const hookDecisions: string[] = [];
+    const runHook = (label: string) =>
+      step.effect(label, () => {
+        hookDecisions.push(runWorkspaceHook(workspaceRoot, hookShell(COMMAND)).permission);
+      });
+
+    const ev1 = sdkEvents(AGENT_ID, RUN_1);
+    const ev2 = sdkEvents(AGENT_ID, RUN_2);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_1, RUN_2],
+      observeStep: () => clock.tick(),
+      turns: [
+        // Turn 1: the SDK runs the hook before executing the gated tool; the
+        // hook denies and writes the ledger; the SDK reports the call blocked.
+        [
+          step.event(ev1.init()),
+          step.event(ev1.assistant("I'll run the build now.")),
+          step.event(ev1.toolCall(CALL_TURN_1, "shell", "running", SHELL_ARGS)),
+          runHook("hook: turn 1 (expect deny)"),
+          step.event(ev1.toolCall(CALL_TURN_1, "shell", "error", SHELL_ARGS, "Blocked by hook")),
+          // Never reached: the loop detects the denial on the event above and
+          // cancels the run. Present so a regression that does NOT cancel is
+          // caught by the golden, not by a missing-result throw.
+          step.event(ev1.assistant("The build was blocked.")),
+          step.finished({ result: "The build was blocked." }),
+        ],
+        // Turn 2 (resumed): the hook runs again for the re-issued call and now
+        // allows it (the grant); the tool runs under a FRESH call id.
+        [
+          runHook("hook: turn 2 (expect allow)"),
+          step.event(ev2.toolCall(CALL_TURN_2, "shell", "running", SHELL_ARGS)),
+          step.event(ev2.toolCall(CALL_TURN_2, "shell", "completed", SHELL_ARGS, BUILD_OUTPUT)),
+          step.event(ev2.assistant(FINAL_TEXT)),
+          step.turnEnded({ inputTokens: 3_100, outputTokens: 60 }),
+          step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [agent], catalog: SDK_CATALOG },
+    });
+
+    // ── Act 1: the first invocation ──────────────────────────────────────────
+    const turn1 = await runCursorTurn(scenario, { threadId: "", turnSeq: 0 });
+
+    // ── Assert 1: paused for approval, returned, agent parked ────────────────
+    expect(hookDecisions, "the real hook denied the gated shell call").toEqual(["deny"]);
+    expect(turn1.outcome.kind, "an approval pause RETURNS to the workflow").toBe("returned");
+    expect((turn1.outcome as { value: Record<string, unknown> }).value.phase).toBe(
+      "EXECUTION_WAITING_FOR_APPROVAL",
+    );
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+    ]);
+    expect(agent.runs[0].cancelCalls, "the first denial cancels the run exactly once").toHaveLength(1);
+    expect(agent.closeCalls, "the agent is parked for the resume, not closed").toBe(0);
+
+    const waiting = record.waitingToolCalls();
+    expect(waiting, "exactly one gate row").toHaveLength(1);
+    expect(waiting[0].id).toBe(CALL_TURN_1);
+    expect(waiting[0].name).toBe("shell");
+    expect(waiting[0].requiresApproval).toBe(true);
+    // The gate row carries what the HOOK saw (the ledger's captured tool_input:
+    // command, cwd, timeout), overlaid on the stream's args — the golden pins
+    // the full shape; here only the shared salient field is asserted.
+    expect(waiting[0].args).toMatchObject(SHELL_ARGS);
+    // The model's post-denial narration never reaches the user as fact.
+    expect(record.status?.messages.some((m) => m.content === "The build was blocked.")).toBe(false);
+
+    const turn1Json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(turn1Json).toMatchFileSnapshot("./goldens/deny-and-retry.turn1.status.json");
+
+    // ── The user approves (the server's SubmitApproval effect on the row) ────
+    clock.tick();
+    expect(record.decideWaitingToolCalls(ApprovalAction.APPROVE, new Date().toISOString())).toBe(1);
+
+    // ── Act 2: the reinvocation ──────────────────────────────────────────────
+    const turn2 = await runCursorTurn(scenario, { threadId: AGENT_ID, turnSeq: 1 });
+
+    // ── Assert 2: allowed, reconciled, completed ─────────────────────────────
+    expect(hookDecisions, "the SAME hook allows the approved re-issue").toEqual(["deny", "allow"]);
+    expect(turn2.outcome.kind).toBe("returned");
+    const slim2 = (turn2.outcome as { value: Record<string, unknown> }).value;
+    expect(slim2.phase).toBe("EXECUTION_COMPLETED");
+    expect(slim2.final_text).toBe(FINAL_TEXT);
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+
+    // #215: the resume checks the parked agent out of the session cache; the
+    // SDK is asked to create once for the whole round trip and never to resume.
+    expect(scenario.sdk.resolutions.map((r) => r.kind)).toEqual(["create"]);
+    expect(agent.sends).toHaveLength(2);
+
+    // Each tool gates exactly once: the committed row survives under its
+    // ORIGINAL id, now COMPLETED with the tool's result; the fresh call id the
+    // model emitted is reconciled onto it, never a second row.
+    const rows = record.toolCalls();
+    expect(rows.filter((tc) => tc.name === "shell")).toHaveLength(1);
+    const shell = rows.find((tc) => tc.name === "shell")!;
+    expect(shell.id).toBe(CALL_TURN_1);
+    expect(shell.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(shell.result).toBe(BUILD_OUTPUT);
+    expect(shell.approvalAction, "the decision survives on the row").toBe(ApprovalAction.APPROVE);
+    expect(rows.some((tc) => tc.id === CALL_TURN_2)).toBe(false);
+    expect(record.waitingToolCalls()).toHaveLength(0);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    const turn2Json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(turn2Json).toMatchFileSnapshot("./goldens/deny-and-retry.turn2.status.json");
+  });
+});