@stigmer/runner 3.14.0 → 3.15.0

package/src/activities/execute-cursor/__tests__/hermetic/pause-vs-shutdown.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Hermetic goldens: USER PAUSE versus WORKER SHUTDOWN — the two interruptions
+ * that THROW, and the byte-pinned copy that tells them apart.
+ *
+ * Invariant pinned (the throw-vs-return table the runtime owns,
+ * `harness/terminal-table.ts`; parent §5c): both interruptions end the activity with a thrown Temporal
+ * `CancelledFailure` (never a return), but they persist DIFFERENT terminal
+ * states the control plane keys on:
+ *
+ *  - a user pause (Temporal delivers cancellation, no shutdown signal) persists
+ *    EXECUTION_PAUSED with "Execution paused by user. Use resume to continue."
+ *    and throws "Activity paused by orchestrator";
+ *  - a worker shutdown (the runner's per-queue shutdown signal is aborted AND
+ *    cancellation is delivered) persists EXECUTION_FAILED with the error copy
+ *    "Execution interrupted: runner worker was shut down. Retry or resume." and
+ *    throws "Activity cancelled (worker shutdown, not user pause)".
+ *
+ * The cloud channel decision table matches on that copy, so the goldens
+ * (`goldens/pause.status.json`, `goldens/worker-shutdown.status.json`) are the
+ * wire contract, character for character. Both interruptions are triggered from
+ * a script `effect` step — never a timer — so the instant is deterministic: the
+ * stream loop sees `isCancelled()` on its next iteration and never processes
+ * the event that follows.
+ *
+ * What the goldens ALSO pin: each path appends its system message exactly
+ * ONCE. The orchestrator this net was recorded on appended it twice — once in
+ * `resolvePreBoundaryTerminal` before the throw, once again in the outer
+ * `catch (CancelledFailure)`, which re-stamped and re-persisted — and the
+ * goldens pinned that double on purpose so S2 could reproduce the wire byte
+ * for byte (stigmer#1054, Q-S2-4). The runtime's `settleWith` is now the one
+ * writer of a terminal arm, so a second row has no code path to come from.
+ *
+ * Runtime phases exercised: the adapter's stop-signal cancel; the runtime's
+ * `classifyTurnInterruption`; the terminal table's pause and worker-shutdown
+ * arms through `settleWith`; the `finally` teardown under a thrown exit.
+ *
+ * Regeneration history:
+ *  - S2 M3b (entry 20260911.03): timestamp-only diff — every terminal stamp
+ *    one scripted second earlier: the adapter cancels the SDK run the instant
+ *    the runtime's stop signal aborts (Q-M3-4), before the SDK double pulls,
+ *    and the clock ticks on, one more step. Transcript unchanged.
+ *  - 2026-09-12 (stigmer#1054, the PR after S2): one removed system row per
+ *    golden, nothing else. The transcript now carries each terminal row once.
+ *
+ * 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 { ExecutionPhase, MessageType } 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,
+  threwCancelledFailure,
+  type HermeticEnvironment,
+  type InvocationControls,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const USER_MESSAGE = "Refactor the parser module.";
+const NEVER_SEEN = "This text must never reach the transcript.";
+
+/**
+ * A turn that is interrupted mid-stream by `interrupt(controls)`: one assistant
+ * message lands, then the interruption, then an event the loop must NOT process.
+ */
+function interruptedTurn(
+  agentId: string,
+  runId: string,
+  clock: ScriptedClock,
+  getControls: () => InvocationControls,
+  interrupt: (controls: InvocationControls) => void,
+): ScriptedCursorAgent {
+  const ev = sdkEvents(agentId, runId);
+  return new ScriptedCursorAgent({
+    agentId,
+    runIds: [runId],
+    observeStep: () => clock.tick(),
+    turns: [
+      [
+        step.event(ev.init()),
+        step.event(ev.assistant("Starting on the parser.")),
+        step.effect("interrupt the activity from outside", () => interrupt(getControls())),
+        step.event(ev.assistant(NEVER_SEEN)),
+        step.finished({ result: NEVER_SEEN }),
+      ],
+    ],
+  });
+}
+
+describe("ExecuteCursor hermetic — user pause vs worker shutdown", () => {
+  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("a user pause persists PAUSED and throws CancelledFailure", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset(); // both goldens read from :00
+    let controls: InvocationControls | undefined;
+    const agent = interruptedTurn(
+      "agent-hermetic-pause-0001",
+      "run-hermetic-pause-0001",
+      clock,
+      () => controls!,
+      (c) => c.cancel(),
+    );
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario, { onControls: (c) => (controls = c) });
+
+    // ── Assert: the throw and the persisted state ────────────────────────────
+    expect(threwCancelledFailure(invocation.outcome), "a pause THROWS CancelledFailure").toBe(true);
+    if (!threwCancelledFailure(invocation.outcome)) throw new Error("unreachable");
+    expect(invocation.outcome.error.message).toBe("Activity paused by orchestrator");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_PAUSED,
+    ]);
+    const final = record.lastFullStatus!;
+    expect(final.error, "a pause is not an error").toBe("");
+    expect(final.completedAt, "a paused turn is not complete").toBe("");
+    expect(
+      final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content),
+    ).toEqual(["Execution paused by user. Use resume to continue."]);
+    expect(final.messages.some((m) => m.content === NEVER_SEEN), "nothing after the cancel is processed").toBe(false);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/pause.status.json");
+  });
+
+  it("a worker shutdown persists FAILED with the shutdown copy and throws CancelledFailure", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    clock.reset();
+    let controls: InvocationControls | undefined;
+    const agent = interruptedTurn(
+      "agent-hermetic-shutdown-0001",
+      "run-hermetic-shutdown-0001",
+      clock,
+      () => controls!,
+      (c) => {
+        // The runner-manager drains: the queue's shutdown signal aborts, then
+        // Temporal delivers the cancellation.
+        c.signalWorkerShutdown();
+        c.cancel();
+      },
+    );
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario, { onControls: (c) => (controls = c) });
+
+    // ── Assert: the throw and the persisted state ────────────────────────────
+    expect(threwCancelledFailure(invocation.outcome), "a shutdown THROWS CancelledFailure").toBe(true);
+    if (!threwCancelledFailure(invocation.outcome)) throw new Error("unreachable");
+    expect(invocation.outcome.error.message).toBe("Activity cancelled (worker shutdown, not user pause)");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_FAILED,
+    ]);
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe("Execution interrupted: runner worker was shut down. Retry or resume.");
+    expect(final.completedAt).not.toBe("");
+    expect(
+      final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content),
+    ).toEqual([
+      "Execution interrupted: the runner worker was shut down while the agent was still running. You can retry or resume.",
+    ]);
+    expect(final.messages.some((m) => m.content === NEVER_SEEN)).toBe(false);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/worker-shutdown.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/plain-turn.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Hermetic golden: a PLAIN TURN through the whole `ExecuteCursor` activity.
+ *
+ * Invariant pinned: an execution with no tools, no workspace entries, no MCP
+ * servers and no skills — the user asks, the agent answers — runs the full
+ * setup pipeline and ends COMPLETED with exactly the transcript, usage and
+ * timestamps recorded in `goldens/plain-turn.status.json`, RETURNING a slim
+ * status to the workflow (never throwing). This is the baseline every other
+ * scenario is a delta from, and the first proof that the activity is byte-
+ * stable under the hermetic driver.
+ *
+ * Parent phase rows exercised (20260908.02 `T01_0_plan.md` §3a): normalize
+ * input / heartbeat; artifact storage + the `persist` chokepoint; fetch
+ * execution, session, agent, blueprint; resolve environment (NOT_FOUND ->
+ * empty); provision workspace (per-session dir); workspace turn lock; MCP
+ * resolve (none); skills (none); attachments (none); HITL gate install;
+ * pricing + model id + variant params; create the engine session; write
+ * `harness_state_id` back; prompt composition; usage accumulation; run the
+ * turn; terminal mapping COMPLETED -> return; cleanup.
+ *
+ * Nothing here is a live Cursor agent: `@cursor/sdk` is the scripted double
+ * (`__test-utils__/scripted-sdk.ts`) and the control plane is the in-memory
+ * execution record (`__test-utils__/hermetic-activity.ts`). No network, no
+ * `CURSOR_API_KEY`, no Temporal worker.
+ *
+ * Regenerate the golden 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 { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// Both mocks are hoisted by vitest; they must live in this file. Each factory
+// imports the reusable module and returns its mock surface.
+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 { ScriptedCursorAgent, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const AGENT_ID = "agent-hermetic-plain-0001";
+const RUN_ID = "run-hermetic-plain-0001";
+const USER_MESSAGE = "Say hello in five words or fewer.";
+const ASSISTANT_TEXT = "Hello there, hermetic world.";
+
+describe("ExecuteCursor hermetic — plain turn", () => {
+  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("completes with the golden transcript and returns a slim COMPLETED status", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event({ type: "system", subtype: "init", agent_id: AGENT_ID, run_id: RUN_ID }),
+          step.event({
+            type: "assistant",
+            agent_id: AGENT_ID,
+            run_id: RUN_ID,
+            message: { role: "assistant", content: [{ type: "text", text: ASSISTANT_TEXT }] },
+          }),
+          step.turnEnded({ inputTokens: 1_200, outputTokens: 40 }),
+          step.finished({
+            result: ASSISTANT_TEXT,
+            model: {
+              id: FIXTURE.model,
+              params: [
+                { id: "fast", value: "false" },
+                { id: "thinking", value: "false" },
+              ],
+            },
+          }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [agent], catalog: SDK_CATALOG },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runCursorTurn(scenario);
+
+    // ── Assert: the outcome the workflow sees ────────────────────────────────
+    expect(invocation.outcome.kind, "a completed turn RETURNS, never throws").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(slim.final_text).toBe(ASSISTANT_TEXT);
+    expect(slim, "the slim return carries no transcript").not.toHaveProperty("messages");
+
+    // ── Assert: what the control plane received, in order ────────────────────
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+    expect(record.setupProgress, "the setup pipeline's phase labels, in order").toEqual([
+      "Fetching execution",
+      "Resolving agent blueprint",
+      "Resolving environment",
+      "Provisioning workspace",
+      "Resolving MCP servers",
+      "Resolving skills",
+      "Initializing Cursor agent",
+    ]);
+
+    // ── Assert: what the SDK was asked ───────────────────────────────────────
+    expect(scenario.sdk.resolutions).toHaveLength(1);
+    expect(scenario.sdk.resolutions[0].kind, "a fresh session creates, never resumes").toBe("create");
+    expect(scenario.sdk.resolutions[0].options?.model).toEqual({
+      id: FIXTURE.model,
+      params: [
+        { id: "fast", value: "false" },
+        { id: "thinking", value: "false" },
+      ],
+    });
+    expect(agent.sends).toHaveLength(1);
+    expect(String(agent.sends[0].message), "the prompt carries the user's message").toContain(USER_MESSAGE);
+    expect(agent.sends[0].hasOnDelta).toBe(true);
+
+    // ── Assert: the harness_state_id write-back ─────────────────────────────
+    expect(record.sessionUpdates).toHaveLength(1);
+    expect(record.sessionUpdates[0].spec?.harnessStateId).toBe(AGENT_ID);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(invocation.heartbeats.length, "the whole-activity heartbeat ran").toBeGreaterThan(0);
+    expect(registry.urls.every((u) => u.includes("/model-registry")), "no network beyond the registry").toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const finalStatus = record.lastFullStatus;
+    expect(finalStatus).toBeDefined();
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, finalStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/plain-turn.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/recovery-fresh-agent.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Hermetic golden: POISONED-HANDLE RECOVERY — a resumed agent whose run fails
+ * with a transport error is replaced by a fresh agent, once, and the turn
+ * completes on the replacement.
+ *
+ * Invariant pinned: when `run.wait()` reports `error` on an agent that was
+ * RESUMED (`resolution.reason === "resumed_successfully"`) and the classifier
+ * files the error as `network` or `agent-stale`, the activity closes the stale
+ * handle, calls `Agent.create` for a fresh one, writes the fresh id to the
+ * session's `harness_state_id`, re-runs the turn on the fresh agent through the
+ * IDENTICAL stream loop and boundary, and ends COMPLETED. The retry happens at
+ * most once (`alreadyRetriedWithFreshAgent`). The golden
+ * (`goldens/recovery-fresh-agent.status.json`) pins what the user sees after a
+ * recovered turn.
+ *
+ * Parent phase rows exercised beyond the earlier scenarios: `Agent.resume`
+ * through `resolveAgentWithTransportRecovery` (a second execution in a session:
+ * `thread_id` set, no parked agent); the `status: ERROR` stream event feeding
+ * `streamErrorMessage`; `run.wait()` error mapping; the error classifier
+ * (`error-classifier.ts` NETWORK_PATTERNS, the same shapes its own tests pin);
+ * the fresh-agent recovery spine (`runRecoveryStream`); the second
+ * `harness_state_id` write-back.
+ *
+ * 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 { ExecutionPhase } 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 { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+} from "../../__test-utils__/hermetic-cursor.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+
+const STALE_AGENT_ID = "agent-hermetic-stale-0001";
+const FRESH_AGENT_ID = "agent-hermetic-fresh-0002";
+const RUN_STALE = "run-hermetic-stale-0001";
+const RUN_FRESH = "run-hermetic-fresh-0001";
+const USER_MESSAGE = "Summarize what changed since yesterday.";
+// A real network-class failure shape (error-classifier NETWORK_PATTERNS:
+// "unavailable", "econnreset", "fetch failed").
+const TRANSPORT_ERROR = "UNAVAILABLE: fetch failed (ECONNRESET) while streaming the run";
+const FINAL_TEXT = "Two files changed since yesterday: notes.md and README.md.";
+
+describe("ExecuteCursor hermetic — poisoned-handle recovery on a fresh agent", () => {
+  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("replaces the stale resumed agent once and completes on the fresh one", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const evStale = sdkEvents(STALE_AGENT_ID, RUN_STALE);
+    const evFresh = sdkEvents(FRESH_AGENT_ID, RUN_FRESH);
+    const stale = new ScriptedCursorAgent({
+      agentId: STALE_AGENT_ID,
+      runIds: [RUN_STALE],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(evStale.init()),
+          step.event(evStale.assistant("Let me look at the recent changes.")),
+          step.event(evStale.status("ERROR", TRANSPORT_ERROR)),
+          step.errored({ result: TRANSPORT_ERROR }),
+        ],
+      ],
+    });
+    const fresh = new ScriptedCursorAgent({
+      agentId: FRESH_AGENT_ID,
+      runIds: [RUN_FRESH],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(evFresh.init()),
+          step.event(evFresh.assistant(FINAL_TEXT)),
+          step.turnEnded({ inputTokens: 2_800, outputTokens: 55 }),
+          step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      // `Agent.create` hands out `fresh`; `Agent.resume(STALE)` finds `stale`,
+      // the previous turn's agent the session knows only by harness_state_id.
+      sdk: { agents: [fresh], resumableAgents: [stale], catalog: SDK_CATALOG },
+    });
+
+    // ── Act: the second execution in the session resumes the stale handle ────
+    const invocation = await runCursorTurn(scenario, { threadId: STALE_AGENT_ID, turnSeq: 0 });
+
+    // ── Assert: outcome ──────────────────────────────────────────────────────
+    expect(invocation.outcome.kind, "a recovered turn RETURNS like any completion").toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(slim.final_text).toBe(FINAL_TEXT);
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+
+    // ── Assert: the recovery spine ───────────────────────────────────────────
+    expect(scenario.sdk.resolutions.map((r) => [r.kind, r.agentId])).toEqual([
+      ["resume", STALE_AGENT_ID],
+      ["create", FRESH_AGENT_ID],
+    ]);
+    expect(stale.sends, "the stale handle ran exactly once").toHaveLength(1);
+    expect(stale.closeCalls, "the poisoned handle is disposed").toBe(1);
+    expect(fresh.sends, "the fresh agent ran the turn exactly once — no second retry").toHaveLength(1);
+    expect(String(fresh.sends[0].message), "the rebuilt prompt carries the user's message").toContain(USER_MESSAGE);
+
+    // The session now points at the fresh agent (the stale id is superseded).
+    const lastSessionWrite = record.sessionUpdates.at(-1);
+    expect(lastSessionWrite?.spec?.harnessStateId).toBe(FRESH_AGENT_ID);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/recovery-fresh-agent.status.json");
+  });
+});