@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/src/activities/execute-deep-agent/__tests__/hermetic/harness-contract.test.ts

@@ -0,0 +1,144 @@
+/**
+ * The harness contract kit, BOTH halves, against the REAL native deep-agent
+ * adapter under the sqlite checkpointer.
+ *
+ * The adapter-side half (`__test-utils__/harness-contract/contract.ts`) is the
+ * single statement of what every `HarnessAdapter` owes the runtime;
+ * `src/__tests__/harness-contract.test.ts` runs it against the scripted fake
+ * under both pause primitives, `execute-cursor/__tests__/hermetic/
+ * harness-contract.test.ts` against the real Cursor adapter. The runtime-side
+ * half (`runtime-contract.ts`) is what the turn runtime owes every harness,
+ * through the real activity under `MockActivityEnvironment`. This file runs
+ * BOTH against `createDeepAgentAdapter()` through the native subject
+ * (`__test-utils__/contract-subject.ts`), which translates the kit's
+ * scenarios onto the `ScriptedModel` double and lets deepagents' real
+ * built-ins run over the real approval gate. Nothing of the adapter is
+ * mocked; the model client and the control-plane client are the two doubles
+ * every native hermetic golden already substitutes.
+ *
+ * The posture is sqlite, the production local default (`config.ts`): the
+ * test-only memory saver re-interrupts on replay and duplicates the gated
+ * row (S3 M0 finding F-M0-3), so it cannot carry the HITL arms. One sqlite
+ * file per session lands under the hermetic `HOME`, opened and closed per
+ * turn by the adapter.
+ *
+ * What this subject declares it cannot produce, so the kit reports the arm
+ * SKIPPED and never silently passes: the `engine` and `actionable` failure
+ * surfaces (`turn.ts` classifies every escaped error `internal` — the
+ * adapter has one surface), and an engine-side cancel (no native path ends a
+ * turn `cancelled`).
+ *
+ * Beside the kit, the native-only observations its vocabulary cannot
+ * express — the interrupt primitive's own facts: an APPROVED pending action
+ * executes at the resume, before the model is asked (the order the kit's
+ * invariant 4 used to assert the other way round, until this adapter showed
+ * it is the primitive's and not the contract's — S3 M3 F-M3-1, Q-M3-2); a
+ * REJECT reaches the model as the gate's denial `ToolMessage` in the
+ * conversation, and the model proposes the call exactly once (the denial is
+ * a tool result the model reads, never a second gate); and one sqlite
+ * checkpoint per session lands under the hermetic `HOME`, none for a session
+ * never served.
+ *
+ * No golden: the kit asserts behaviour, the goldens under `goldens/` pin
+ * transcripts. The hermetic environment is created at module level because
+ * the subject's `config` is read at collection time; the forks pool keeps it
+ * private to this file.
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { existsSync } from "node:fs";
+import { isAIMessage, isToolMessage } from "@langchain/core/messages";
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import { ExecutionDriver, describeHarnessContract } from "../../../../__test-utils__/harness-contract/contract.js";
+import { describeHarnessRuntimeContract } from "../../../../__test-utils__/harness-contract/runtime-contract.js";
+import { scenario } from "../../../../__test-utils__/harness-contract/types.js";
+import { ScriptedClock, createHermeticEnvironment } from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import { findToolCallRow } from "../../../../__test-utils__/proto-helpers.js";
+import { getCheckpointDbPath } from "../../../../shared/workspace/platform-dir.js";
+import { createDeepAgentContractSubject } from "../../__test-utils__/contract-subject.js";
+
+const env = createHermeticEnvironment();
+const clock = new ScriptedClock();
+const subject = createDeepAgentContractSubject(env);
+const WRITE_GAMMA = { kind: "write", resource: "/work/gamma.txt" } as const;
+
+describe("ExecuteDeepAgent hermetic — the harness contract kit against the real adapter", () => {
+  let registry: ReturnType<typeof stubRegistryFetch>;
+
+  beforeAll(() => {
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  describeHarnessContract(subject);
+  describeHarnessRuntimeContract({ subject, env, clock }, { failureSurfaces: ["internal"], engineCancel: false });
+
+  describe("native-only observations", () => {
+    beforeAll(async () => {
+      await subject.adapter.boot(subject.config);
+    });
+
+    it("executes an APPROVED pending action at the resume, before the model is asked — even when the model then hangs and the turn is stopped (interrupt order, F-M3-1)", async () => {
+      const driver = new ExecutionDriver(subject, "obs-approved-at-resume");
+      const id = "obs-approved-at-resume-write";
+
+      const proposed = await driver.turn([scenario.propose(id, WRITE_GAMMA)]);
+      expect(proposed.outcome.kind).toBe("awaiting_approval");
+      driver.decide(id, ApprovalAction.APPROVE);
+
+      const hanging = driver.begin([scenario.say("working"), scenario.hang(), scenario.propose(id, WRITE_GAMMA)], { stopWhenHanging: "kit: user pause" });
+      const outcome = await hanging.settled;
+
+      expect(outcome.kind).toBe("interrupted");
+      expect(subject.executionCount(id), "the resume completed the pending task before the hang; the stop came after").toBe(1);
+      expect(findToolCallRow(hanging.sink.status, id)?.status, "and the row on the interrupted turn's status says so").toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    });
+
+    it("hands a REJECT to the model as the gate's denial ToolMessage; the call is proposed exactly once and never re-gated", async () => {
+      const driver = new ExecutionDriver(subject, "obs-reject-as-denial");
+      const id = "obs-reject-as-denial-write";
+
+      const proposed = await driver.turn([scenario.propose(id, WRITE_GAMMA)]);
+      expect(proposed.outcome.kind).toBe("awaiting_approval");
+      driver.decide(id, ApprovalAction.REJECT);
+      const resumed = await driver.turn([scenario.propose(id, WRITE_GAMMA), scenario.say("moving on")]);
+      expect(resumed.outcome.kind).toBe("completed");
+
+      const transcript = subject.lastTranscriptOf(driver.executionId)!;
+      const denials = transcript.filter((m) => isToolMessage(m) && m.tool_call_id === id);
+      const proposals = transcript.filter((m) => isAIMessage(m) && (m.tool_calls ?? []).some((tc) => tc.id === id));
+      expect(denials, "the model read the gate's answer as a tool result").toHaveLength(1);
+      expect(proposals, "and had proposed the call exactly once").toHaveLength(1);
+      expect(subject.executionCount(id)).toBe(0);
+    });
+
+    it("keeps one sqlite checkpoint per session under the hermetic HOME, none for a session never served", async () => {
+      const served = new ExecutionDriver(subject, "obs-sqlite-a");
+      const other = new ExecutionDriver(subject, "obs-sqlite-b");
+      expect((await served.turn([scenario.say("first")])).outcome.kind).toBe("completed");
+      expect((await other.turn([scenario.say("second")])).outcome.kind).toBe("completed");
+
+      const [a, b] = [getCheckpointDbPath(served.sessionId), getCheckpointDbPath(other.sessionId)];
+      expect(a.startsWith(env.home), "the checkpoint lives under the runner-owned HOME tree").toBe(true);
+      expect(a).not.toBe(b);
+      expect(existsSync(a)).toBe(true);
+      expect(existsSync(b)).toBe(true);
+      expect(existsSync(getCheckpointDbPath("ses-never-served")), "a session never served has no checkpoint").toBe(false);
+    });
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/hitl-approve-all-lease.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Hermetic golden: APPROVE_ALL leases the gated action's CLASS for the rest
+ * of the run — two invocations on the durable (sqlite) checkpointer.
+ *
+ * Turn 1: the model thinks (a leading reasoning block, persisted as a
+ * THINKING message), says it will run two commands, and proposes the first
+ * gated `execute`; the gate pauses; WAITING_FOR_APPROVAL.
+ *
+ * Between turns: APPROVE_ALL on the WAITING row. `deriveActiveLeases`
+ * reduces it to the scope of the tool it was made on — for a built-in, its
+ * approval category (`shared/approval-policy.ts` `deriveLeaseScope`), here
+ * SHELL — and the reinvocation's gate carries that lease.
+ *
+ * Turn 2: the graph resumes inside the gate and runs command A; the model
+ * proposes command B; the gate finds SHELL leased and runs B WITHOUT a second
+ * interrupt (`ToolCall.approvalPolicySource` records the lease as the
+ * authorization); the model closes; COMPLETED.
+ *
+ * Invariants carried from the retired `hitl-resume-approve-all.test.ts`
+ * (the user-reported "leading thinking block and the first tool call vanish
+ * after approve-all" regression): the final status is a strict SUPERSET of
+ * run 1's transcript — the THINKING message survives, the gated call is
+ * reconciled in place (exactly one copy, now COMPLETED), and the leased
+ * follow-up is appended COMPLETED with no interrupt. That test leased an MCP
+ * SERVER (`getAppState` on open-computer-use); this arm leases a CATEGORY,
+ * the same `deriveLeaseScope` path with the other scope kind (S3 M0 ruling
+ * Q-M0-4). The server-scoped lease stays pinned by `approval-policy`'s unit
+ * tests and the conformance execution class.
+ *
+ * What every reinvocation golden here shows since S3 M2a (the runtime over
+ * the native adapter; Q-S3-16 and Q-M2a-2): `startedAt` is THIS turn's own,
+ * not turn 1's carried by the orchestrator's whole-status clone; the
+ * `fileReviewEventStream` carries only the events THIS turn authored (the
+ * runtime seeds messages, sub-agents, artifacts, write-backs, todos, usage,
+ * the memory report and the structured output — never the server-owned
+ * ledgers, which the server appends to by event id in `update-status.ts`
+ * `appendRunnerEvents`; the hermetic record replaces wholesale, so a
+ * golden reads as what the runner SENT); and `streamingUsage` carries the
+ * runtime accountant's fields (`model`, `estimatedCostUsd`, the requested
+ * tier and thinking mode).
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import {
+  AgentExecutionStatusSchema,
+  type AgentExecutionStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ApprovalAction,
+  ApprovalPolicySource,
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+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 { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import { CLOSING_TURN, EXECUTE_CALL_A, EXECUTE_CALL_B } from "../../__test-utils__/hitl-script.js";
+
+const USER_MESSAGE = "Run both commands.";
+const REASONING = "Two commands are needed; I will run them in order.";
+const OPENING_TEXT = "I will run the two commands.";
+const DECIDED_AT = "2026-01-01T00:00:30.000Z";
+
+function statusJson(status: AgentExecutionStatus): string {
+  return JSON.stringify(toJson(AgentExecutionStatusSchema, status), null, 2) + "\n";
+}
+
+describe("ExecuteDeepAgent hermetic — APPROVE_ALL leases the class (sqlite)", () => {
+  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("runs the approved call and the leased follow-up in one resume, keeping the leading thinking", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      checkpointer: "sqlite",
+      script: () => ({
+        turns: [
+          {
+            reasoning: REASONING,
+            text: OPENING_TEXT,
+            toolCalls: [EXECUTE_CALL_A],
+            usage: { inputTokens: 1_400, outputTokens: 80 },
+          },
+          { toolCalls: [EXECUTE_CALL_B], usage: { inputTokens: 1_600, outputTokens: 40 } },
+          CLOSING_TURN,
+        ],
+      }),
+    });
+
+    // ── Act 1 ────────────────────────────────────────────────────────────────
+    const turn1 = await runDeepAgentTurn(scenario, { turnSeq: 0 });
+
+    // ── Assert 1: paused on A, the thinking persisted ────────────────────────
+    expect(turn1.outcome.kind).toBe("returned");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL);
+    const run1 = record.lastFullStatus!;
+    const thinking = run1.messages.filter((m) => m.type === MessageType.MESSAGE_THINKING);
+    expect(thinking.map((m) => m.content), "the reasoning block is exactly one THINKING message").toEqual([REASONING]);
+    expect(run1.messages[0].type, "and it leads the transcript").toBe(MessageType.MESSAGE_THINKING);
+    expect(record.waitingToolCalls().map((tc) => tc.id)).toEqual([EXECUTE_CALL_A.id]);
+    await expect(statusJson(run1)).toMatchFileSnapshot("./goldens/approve-all-lease.turn1.status.json");
+
+    // ── Between turns: APPROVE_ALL on A ──────────────────────────────────────
+    expect(record.decideWaitingToolCalls(ApprovalAction.APPROVE_ALL, DECIDED_AT)).toBe(1);
+
+    // ── Act 2 ────────────────────────────────────────────────────────────────
+    const turn2 = await runDeepAgentTurn(scenario, { turnSeq: 1 });
+
+    // ── Assert 2: A ran, B ran under the lease, no second interrupt ──────────
+    expect(turn2.outcome.kind).toBe("returned");
+    expect((turn2.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    expect(record.persistedPhases.filter((p) => p === ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL)).toHaveLength(1);
+
+    const final = record.lastFullStatus!;
+    const rows = final.messages.flatMap((m) => m.toolCalls);
+    expect(rows.map((tc) => tc.id), "A reconciled in place, B appended; one copy each").toEqual([
+      EXECUTE_CALL_A.id,
+      EXECUTE_CALL_B.id,
+    ]);
+    const [a, b] = rows;
+    expect(a.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(a.approvalAction).toBe(ApprovalAction.APPROVE_ALL);
+    expect(a.result).toContain("hermetic-a");
+    expect(b.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(b.requiresApproval, "the leased class needs no interrupt").toBe(false);
+    expect(b.approvalPolicySource, "the lease is B's recorded authorization").toBe(
+      ApprovalPolicySource.APPROVAL_LEASE,
+    );
+    expect(b.approvalAction, "B was never decided by a person").toBe(ApprovalAction.UNSPECIFIED);
+    expect(b.result).toContain("hermetic-b");
+
+    // The superset invariant: every run-1 message survives, in order, at the front.
+    const run1Shape = run1.messages.map((m) => [m.type, m.content]);
+    const finalShape = final.messages.map((m) => [m.type, m.content]);
+    expect(finalShape.slice(0, run1Shape.length), "run 1's transcript is a prefix of the final").toEqual(run1Shape);
+    expect(final.messages[0].type, "the leading thinking survives the resume").toBe(MessageType.MESSAGE_THINKING);
+    expect(finalShape.at(-1)).toEqual([MessageType.MESSAGE_AI, CLOSING_TURN.text]);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    await expect(statusJson(final)).toMatchFileSnapshot("./goldens/approve-all-lease.turn2.status.json");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/hitl-round-trips.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Hermetic goldens: the three HITL round trips — APPROVE, SKIP, REJECT — each
+ * two invocations of the whole `ExecuteDeepAgent` activity on the durable
+ * (sqlite) checkpointer, the production local posture (`config.ts` resolves
+ * `sqlite` in local mode and `http` in cloud; both resume the same way).
+ *
+ * Turn 1 (shared by every arm, ONE golden `gate.turn1.status.json`): the
+ * model proposes a gated `execute`; the gate's `interrupt()` pauses the graph;
+ * the post-stream interrupt detection seeds a WAITING_APPROVAL row carrying
+ * the gate's message and provenance; the activity persists
+ * WAITING_FOR_APPROVAL and RETURNS. That the approve, skip and reject arms all
+ * match the same file is the assertion that the decision to come is invisible
+ * to the first invocation.
+ *
+ * Between turns the test does what the server's `SubmitApproval` does — writes
+ * `approval_action` on the WAITING row (`ExecutionRecord.decideWaitingToolCalls`),
+ * nothing else — and the second invocation reads the real persisted status.
+ *
+ * Turn 2 (one golden per decision): the activity seeds its status from the
+ * persisted transcript (`shouldSeedFromPersistedTranscript`), reads the
+ * checkpoint's pending interrupt, builds `Command({ resume })` from the
+ * decision (`hitl.ts`), and the graph resumes INSIDE the gate:
+ *  - APPROVE: the tool runs; the row is reconciled IN PLACE to COMPLETED with
+ *    the command's output (exactly one copy of the gated call, the run-1
+ *    transcript a strict prefix of the final one — `hitl-resume-history`'s
+ *    invariant), the model closes, COMPLETED.
+ *  - SKIP: the gate returns a "skipped by user" ToolMessage; the tool never
+ *    runs; `reconcileNonExecutingDecisions` stamps the row SKIPPED after the
+ *    stream; COMPLETED.
+ *  - REJECT (issue #197, `hitl-reject`'s invariant): the gate returns a denial
+ *    ToolMessage and the run CONTINUES; the row is stamped SKIPPED with
+ *    `error: "Rejected by user"` and keeps `approvalAction = REJECT` for
+ *    audit; COMPLETED, never stuck at WAITING_APPROVAL.
+ *
+ * Carried from the retired `hitl-reject.test.ts` (both arms), `hitl-resume-
+ * history.test.ts` (seed + single copy), `hitl-resume-approve-all.test.ts`'s
+ * superset assertion (the leased variant lives in `hitl-approve-all-lease`).
+ *
+ * The REJECT arm is what Q-S3-2 aligns the runtime to (REJECT continues on
+ * both harnesses); this golden is the native truth it must reproduce.
+ *
+ * What every reinvocation golden here shows since S3 M2a (the runtime over
+ * the native adapter; Q-S3-16 and Q-M2a-2): `startedAt` is THIS turn's own,
+ * not turn 1's carried by the orchestrator's whole-status clone; the
+ * `fileReviewEventStream` carries only the events THIS turn authored (the
+ * runtime seeds messages, sub-agents, artifacts, write-backs, todos, usage,
+ * the memory report and the structured output — never the server-owned
+ * ledgers, which the server appends to by event id in `update-status.ts`
+ * `appendRunnerEvents`; the hermetic record replaces wholesale, so a
+ * golden reads as what the runner SENT); and `streamingUsage` carries the
+ * runtime accountant's fields (`model`, `estimatedCostUsd`, the requested
+ * tier and thinking mode).
+ *
+ * Regenerate ONLY after a deliberate behavior change:
+ *   npx vitest run src/activities/execute-deep-agent/__tests__/hermetic -u
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { toJson } from "@bufbuild/protobuf";
+import {
+  AgentExecutionStatusSchema,
+  type AgentExecutionStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ApprovalAction,
+  ExecutionPhase,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+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 { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import {
+  CLOSING_TURN,
+  EXECUTE_CALL_A,
+  GATED_OPENING_TURN,
+  GATE_TURN1_GOLDEN,
+  executeApprovalMessage,
+} from "../../__test-utils__/hitl-script.js";
+
+const USER_MESSAGE = "Run the command for me.";
+const DECIDED_AT = "2026-01-01T00:00:30.000Z";
+
+function statusJson(status: AgentExecutionStatus): string {
+  return JSON.stringify(toJson(AgentExecutionStatusSchema, status), null, 2) + "\n";
+}
+
+describe("ExecuteDeepAgent hermetic — HITL round trips (sqlite)", () => {
+  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();
+  });
+
+  describe.each([
+    { name: "approve", action: ApprovalAction.APPROVE },
+    { name: "skip", action: ApprovalAction.SKIP },
+    { name: "reject", action: ApprovalAction.REJECT },
+  ])("$name", ({ name, action }) => {
+    it(`pauses on the gate, then ${name} carries the decision to COMPLETED`, async () => {
+      // ── Arrange ────────────────────────────────────────────────────────────
+      clock.reset();
+      const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+      const scenario = beginDeepAgentScenario({
+        env,
+        clock,
+        record,
+        checkpointer: "sqlite",
+        script: () => ({ turns: [GATED_OPENING_TURN, CLOSING_TURN] }),
+      });
+
+      // ── Act 1: the gate pauses the turn ────────────────────────────────────
+      const turn1 = await runDeepAgentTurn(scenario, { turnSeq: 0 });
+
+      // ── Assert 1: WAITING_FOR_APPROVAL, one WAITING row, returned ──────────
+      expect(turn1.outcome.kind, "an approval pause RETURNS").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,
+      ]);
+      const waiting = record.waitingToolCalls();
+      expect(waiting).toHaveLength(1);
+      expect(waiting[0].id).toBe(EXECUTE_CALL_A.id);
+      expect(waiting[0].name).toBe("execute");
+      expect(waiting[0].requiresApproval).toBe(true);
+      expect(waiting[0].approvalMessage).toBe(executeApprovalMessage(EXECUTE_CALL_A));
+      expect(waiting[0].approvalAction, "no decision yet").toBe(ApprovalAction.UNSPECIFIED);
+      const run1 = record.lastFullStatus!;
+      await expect(statusJson(run1), "every decision's first turn is the same status").toMatchFileSnapshot(
+        GATE_TURN1_GOLDEN,
+      );
+
+      // ── Between turns: what SubmitApproval does to the row ─────────────────
+      expect(record.decideWaitingToolCalls(action, DECIDED_AT)).toBe(1);
+
+      // ── Act 2: the reinvocation resumes inside the gate ────────────────────
+      const turn2 = await runDeepAgentTurn(scenario, { turnSeq: 1 });
+
+      // ── Assert 2: COMPLETED, the row terminal, one copy, run 1 preserved ───
+      expect(turn2.outcome.kind).toBe("returned");
+      expect((turn2.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+      expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+
+      const final = record.lastFullStatus!;
+      const rows = final.messages.flatMap((m) => m.toolCalls).filter((tc) => tc.id === EXECUTE_CALL_A.id);
+      expect(rows, "exactly one copy of the gated call — reconciled in place, never duplicated").toHaveLength(1);
+      const row = rows[0];
+      expect(row.approvalAction, "the decision is preserved for audit").toBe(action);
+      expect(row.approvalDecidedAt).toBe(DECIDED_AT);
+      expect(row.status, "never left at WAITING_APPROVAL").not.toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+      if (action === ApprovalAction.APPROVE) {
+        expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+        expect(row.result, "the command ran").toContain("hermetic-a");
+        expect(row.error).toBe("");
+      } else {
+        expect(row.status).toBe(ToolCallStatus.TOOL_CALL_SKIPPED);
+        expect(row.result, "the tool never ran").toBe("");
+        expect(row.error).toBe(action === ApprovalAction.REJECT ? "Rejected by user" : "");
+      }
+
+      const run1Ai = run1.messages.filter((m) => m.type === MessageType.MESSAGE_AI).map((m) => m.content);
+      const finalAi = final.messages.filter((m) => m.type === MessageType.MESSAGE_AI).map((m) => m.content);
+      expect(finalAi.slice(0, run1Ai.length), "run 1's transcript survives the resume as a prefix").toEqual(run1Ai);
+      expect(finalAi.at(-1)).toBe(CLOSING_TURN.text);
+      expect(final.completedAt).not.toBe("");
+
+      // ── Assert: hermeticity ────────────────────────────────────────────────
+      expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+      // ── Assert: the golden ─────────────────────────────────────────────────
+      await expect(statusJson(final)).toMatchFileSnapshot(`./goldens/${name}.turn2.status.json`);
+    });
+  });
+});