@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

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

@@ -0,0 +1,142 @@
+/**
+ * Hermetic golden: the simplest possible turn through the whole
+ * `ExecuteDeepAgent` activity — one user message in, one assistant message
+ * out, no tools, no gate, no workspace entries.
+ *
+ * Invariant pinned: the activity resolves the four-resource chain, builds the
+ * REAL deepagents graph, streams it through the v3 protocol into
+ * `V3StatusBuilder`, persists IN_PROGRESS then COMPLETED, and returns the slim
+ * status. The golden (`goldens/plain-turn.status.json`) is the smallest
+ * status the native harness produces: one AI message with the scripted text
+ * and the scripted usage, `startedAt` / `completedAt` on the scripted clock.
+ *
+ * This file is also the PROBE the M0 plan named: no earlier test drove the
+ * real graph through `streamEvents(..., { version: "v3" })`. The scripted
+ * model streams, so the events under this golden are the ones a provider
+ * produces (`scripted-model.ts` header).
+ *
+ * Two shapes of the activity's wire contract ride on the same golden, and
+ * matching the SAME file is the assertion that they are invisible to the
+ * status: the legacy positional `(executionId, threadId)` form the control
+ * planes still may send (`shared/activity-input.ts`), and an empty
+ * `thread_id` (carried from `index.test.ts`: "handles empty threadId
+ * gracefully").
+ *
+ * Since S3 M2a the activity is the turn runtime over the native adapter, and
+ * `streamingUsage` carries the runtime accountant's fields — `model`,
+ * `estimatedCostUsd` priced at the registry's rates, the requested tier and
+ * thinking mode (Q-M2a-2: one writer of the summary, the runtime). Nothing
+ * else in this golden moved with the flip.
+ *
+ * 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 } 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("../../../../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 {
+  FIXTURE,
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+  type DeepAgentTurnOptions,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import { recordedModelBuilds } from "../../__test-utils__/scripted-model-module.js";
+
+const USER_MESSAGE = "Say hello.";
+const ASSISTANT_TEXT = "Hello from the hermetic fixture agent.";
+const GOLDEN = "./goldens/plain-turn.status.json";
+
+describe("ExecuteDeepAgent 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();
+  });
+
+  async function runPlainTurn(turn: DeepAgentTurnOptions = {}) {
+    clock.reset();
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({ turns: [{ text: ASSISTANT_TEXT, usage: { inputTokens: 1_200, outputTokens: 30 } }] }),
+    });
+    const invocation = await runDeepAgentTurn(scenario, turn);
+    return { record, invocation };
+  }
+
+  it("persists IN_PROGRESS then COMPLETED with one assistant message and returns the slim status", async () => {
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const { record, invocation } = await runPlainTurn();
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+
+    // ── Assert: the transcript ───────────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    const ai = final.messages.filter((m) => m.type === MessageType.MESSAGE_AI);
+    expect(ai, "one assistant message, no tool rows").toHaveLength(1);
+    expect(ai[0].content).toBe(ASSISTANT_TEXT);
+    expect(ai[0].toolCalls).toHaveLength(0);
+    expect(final.streamingUsage?.inputTokens).toBe(1_200n);
+    expect(final.streamingUsage?.outputTokens).toBe(30n);
+
+    // ── Assert: hermeticity and what production asked the model client for ──
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+    const primaryBuild = recordedModelBuilds()[0];
+    expect(primaryBuild?.modelName, "the execution's model, not the default").toBe(FIXTURE.model);
+    expect(primaryBuild?.proxyEndpoint, "the OSS posture has no proxy").toBeUndefined();
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot(GOLDEN);
+  });
+
+  it("produces the same status from the legacy positional wire shape", async () => {
+    const { record, invocation } = await runPlainTurn({ positional: true });
+    expect(invocation.outcome.kind).toBe("returned");
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot(GOLDEN);
+  });
+
+  it("produces the same status with an empty thread_id", async () => {
+    const { record, invocation } = await runPlainTurn({ threadId: "" });
+    expect(invocation.outcome.kind).toBe("returned");
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot(GOLDEN);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/platform-stop.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Hermetic golden: the PLATFORM STOP — the control plane answers a mid-stream
+ * persist with `ExecutionControlSignal.STOP`.
+ *
+ * What the arm does: the record's `controlSignal` answers STOP on the first
+ * full write that carries a tool row (the tool-call boundary forces that
+ * persist, `persist-decision.ts` `contentDirty`); the runtime's chokepoint
+ * reads the signal off the write and aborts the adapter's `stopSignal`; the
+ * adapter's loop, which AWAITED that persist, sees the abort before it pulls
+ * the next event, cancels the graph run and settles `interrupted`; the
+ * runtime's table maps the stop to COMPLETED with `platformStopArm`'s one
+ * row, "Execution stopped by the platform.", no `status.error`, and RETURNS.
+ *
+ * Ruled at Q-S3-3 (a platform STOP is the platform saying "stop spending
+ * now"; the runtime's abort is the one stop) and landed at S3 M2a. Until
+ * then the orchestrator answered STOP by activating `graceful-stop.ts`,
+ * which handed the model one more tool-free round: the transcript carried
+ * the model's wrap-up ("Stopping here as asked.") AND the middleware's own
+ * notice rendered as the agent's words (F-M0-7), and the run ended
+ * COMPLETED with no row. The graceful-stop middleware was deleted at S3 M2b
+ * (Q-M2a-4 sequenced it after the legacy loop that activated it); nothing in
+ * the graph answers a STOP any more, so the second scripted turn is never
+ * reached — this golden was byte-identical across the deletion.
+ *
+ * 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 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ExecutionControlSignal,
+  ExecutionPhase,
+  MessageType,
+} 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";
+
+const READ_CALL = { id: "call-hermetic-read-0001", name: "read_file", args: { file_path: "/notes.md" } };
+const WRAP_UP = "Stopping here as asked.";
+
+describe("ExecuteDeepAgent hermetic — platform STOP", () => {
+  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("stops the run at the STOP and completes with the platform-stop row (Q-S3-3)", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    let stopsAnswered = 0;
+    const record = deepAgentExecutionRecord({
+      message: "Look at my notes.",
+      controlSignal: (status) => {
+        if (status.messages.some((m) => m.toolCalls.length > 0)) {
+          stopsAnswered += 1;
+          return ExecutionControlSignal.STOP;
+        }
+        return ExecutionControlSignal.UNSPECIFIED;
+      },
+    });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: [
+          { text: "Let me look.", toolCalls: [READ_CALL], usage: { inputTokens: 1_200, outputTokens: 30 } },
+          { text: WRAP_UP, usage: { inputTokens: 1_400, outputTokens: 10 } },
+        ],
+      }),
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert: the STOP was delivered, and the run stopped there ────────────
+    expect(stopsAnswered, "the platform said STOP at least once").toBeGreaterThan(0);
+    expect(invocation.outcome.kind, "a platform stop RETURNS").toBe("returned");
+    expect((invocation.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases).toEqual([ExecutionPhase.EXECUTION_IN_PROGRESS, ExecutionPhase.EXECUTION_COMPLETED]);
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe("");
+    expect(final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content)).toEqual([
+      "Execution stopped by the platform.",
+    ]);
+    const ai = final.messages.filter((m) => m.type === MessageType.MESSAGE_AI).map((m) => m.content);
+    expect(ai, "no wrap-up round and no injected notice: the run stopped at the STOP").toEqual(["Let me look.", ""]);
+    expect(ai).not.toContain(WRAP_UP);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/platform-stop.status.json");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/recursion-limit.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Hermetic golden: the TOOL-CALL BUDGET — `max_tool_rounds` exhausted by a
+ * model that keeps calling tools.
+ *
+ * What the arm does: `max_tool_rounds = 10` (the clamp floor,
+ * `shared/tool-rounds.ts` MIN_TOOL_ROUNDS) becomes LangGraph's
+ * `recursionLimit = 60` (SUPER_STEPS_PER_ROUND); the script proposes a
+ * DISTINCT `read_file` every round (distinct ids and paths, so the
+ * loop-detection middleware's "repetitive pattern" warning does not end the
+ * run first); the graph throws `GraphRecursionError`; the adapter's turn
+ * classifies it as the `tool_call_limit` outcome (`shared/tool-rounds.ts`
+ * `isGraphRecursionError`), and the runtime's `toolCallLimitArm` writes
+ * TERMINATED with the cross-repo prefix `TOOL_CALL_LIMIT_ERROR_PREFIX`
+ * (matched with `startsWith` by stigmer-cloud's `reply-extractor.ts`) and
+ * its row, PERSISTS it, and returns the slim.
+ *
+ * Ruled at Q-S3-6 and landed at S3 M2a. Until then the orchestrator RETURNED
+ * the TERMINATED status but never PERSISTED it (S3 M0 finding F-M0-4, a
+ * production defect): the last status the control plane held was the
+ * stream's mid-run IN_PROGRESS with no error, and only the activity's return
+ * value carried the truth. The golden
+ * (`goldens/recursion-limit.persisted.status.json`) now records the
+ * TERMINATED status the control plane holds, which is what that fix changed
+ * on purpose.
+ *
+ * Also visible here, F-M0-1 at scale: every tool row of the run sits on ONE
+ * empty AI message, because `ensureAiMessageForToolCall("")` creates it once
+ * and `currentAiMessage[""]` then catches every later row.
+ *
+ * How many rounds fit is the middleware stack's shape, not the knob's
+ * (S3 M2b, owner ruling 2026-09-13 on F-M2b-26): LangChain makes every
+ * middleware hook its own graph node, and `max_tool_rounds` becomes a
+ * super-step budget at the ×6 floor estimate, so a node fewer per round
+ * means more rounds within the same 60 steps. When `graceful-stop.ts` (an
+ * `afterModel` node) was deleted with Q-S3-3, this golden went from 11 tool
+ * calls to 13 before TERMINATED — the only hunk, the copy unchanged. That the
+ * knob counts super-steps and not rounds is recorded as an S5 design item
+ * (a round counter in the budget middleware would make it mean what it
+ * says); this file pins what the stack delivers today.
+ *
+ * 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 } 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("../../../../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 { MIN_TOOL_ROUNDS } from "../../../../shared/tool-rounds.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+import { TOOL_CALL_LIMIT_ERROR_PREFIX } from "../../../../shared/tool-rounds.js";
+
+/** More rounds than the budget allows; the graph stops the script, not the other way round. */
+const SCRIPTED_ROUNDS = 40;
+
+describe("ExecuteDeepAgent hermetic — tool-call budget exhausted", () => {
+  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("returns TERMINATED with the cross-repo prefix, and persists nothing past IN_PROGRESS (F-M0-4)", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const record = deepAgentExecutionRecord({ message: "Keep reading files.", maxToolRounds: MIN_TOOL_ROUNDS });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: Array.from({ length: SCRIPTED_ROUNDS }, (_, i) => ({
+          text: `Reading file ${i}.`,
+          toolCalls: [{ id: `call-hermetic-loop-${String(i).padStart(4, "0")}`, name: "read_file", args: { file_path: `/f${i}.md` } }],
+          usage: { inputTokens: 1_000, outputTokens: 20 },
+        })),
+      }),
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert: the slim the workflow receives ───────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_TERMINATED");
+    expect(String(slim.error).startsWith(TOOL_CALL_LIMIT_ERROR_PREFIX), "the cross-repo prefix").toBe(true);
+
+    // ── Assert: what the control plane holds (F-M0-4 closed) ─────────────────
+    expect(record.persistedPhases, "the TERMINATED terminal is persisted").toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_TERMINATED,
+    ]);
+    const persisted = record.lastFullStatus!;
+    expect(String(persisted.error).startsWith(TOOL_CALL_LIMIT_ERROR_PREFIX), "the persisted error carries the prefix").toBe(true);
+    expect(persisted.error, "the event count left the copy (Q-S3-6)").not.toMatch(/\d+ events?/);
+    expect(persisted.completedAt).not.toBe("");
+    const rows = record.toolCalls();
+    expect(rows.length, "fewer rounds ran than were scripted: the budget stopped the graph").toBeLessThan(SCRIPTED_ROUNDS);
+    expect(rows.length).toBeGreaterThanOrEqual(MIN_TOOL_ROUNDS);
+    const rowHosts = persisted.messages.filter((m) => m.type === MessageType.MESSAGE_AI && m.toolCalls.length > 0);
+    expect(rowHosts, "F-M0-1: every row on one empty AI message").toHaveLength(1);
+    expect(rowHosts[0].content).toBe("");
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, persisted), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/recursion-limit.persisted.status.json");
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/resolution-error.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Hermetic golden: a RESOLUTION ERROR — the control plane rejects a read the
+ * setup depends on (`client.getAgent`) before any graph exists.
+ *
+ * Invariant pinned: the runtime's blueprint phase throws, the runtime's
+ * catch takes its generic-error arm (`terminal-table.ts` `unexpectedErrorArm`),
+ * persists ONE EXECUTION_FAILED status carrying
+ * `status.error = "Execution failed: [Error] <message>"` and two system rows
+ * — the boilerplate "Internal system error occurred. Please contact support
+ * if this issue persists." and `"Error details: [Error] <message>"` — and
+ * RETURNS the slim status (the workflow reads the phase; a throw would make
+ * Temporal retry a deterministic failure). Nothing streamed, no lock taken
+ * (the fault precedes the lock phase), no artifacts.
+ *
+ * The row shape is one of Q-S3-7's ruled alignments, landed at S3 M2a: the
+ * orchestrator wrote one row `"Error: [Error] <message>"`; the runtime's arm
+ * writes the boilerplate plus the details row. `status.error` itself did
+ * not move (the conformance suite pins it). The setup labels are the
+ * runtime's resolution phases' (a stated default of the M2a plan).
+ *
+ * Carried from `index.test.ts` ("returns EXECUTION_FAILED status when setup
+ * fails", "includes error message in failed status", "always returns a
+ * serializable result").
+ *
+ * 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 } 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("../../../../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 { recordedModelBuilds } from "../../__test-utils__/scripted-model-module.js";
+
+const CONTROL_PLANE_FAULT = "hermetic fault injected at getAgent";
+
+describe("ExecuteDeepAgent hermetic — resolution error", () => {
+  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("fails with the fault's message in status.error and one system row, and returns", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const record = deepAgentExecutionRecord({ message: "Never reaches a model." });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => {
+        throw new Error("the model must never be asked on a resolution failure");
+      },
+      clientOverrides: {
+        getAgent: vi.fn(async () => {
+          throw new Error(CONTROL_PLANE_FAULT);
+        }),
+      },
+    });
+
+    // ── Act ──────────────────────────────────────────────────────────────────
+    const invocation = await runDeepAgentTurn(scenario);
+
+    // ── Assert: outcome and phases ───────────────────────────────────────────
+    expect(invocation.outcome.kind, "a deterministic failure RETURNS; a retry would fail the same way").toBe(
+      "returned",
+    );
+    const slim = (invocation.outcome as { value: Record<string, unknown> }).value;
+    expect(slim.phase).toBe("EXECUTION_FAILED");
+    expect(() => JSON.stringify(slim), "the return is serializable").not.toThrow();
+    expect(record.persistedPhases, "the one and only full persist").toEqual([ExecutionPhase.EXECUTION_FAILED]);
+
+    // ── Assert: the copy ─────────────────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    expect(final.error).toBe(`Execution failed: [Error] ${CONTROL_PLANE_FAULT}`);
+    expect(final.messages.filter((m) => m.type === MessageType.MESSAGE_SYSTEM).map((m) => m.content)).toEqual([
+      "Internal system error occurred. Please contact support if this issue persists.",
+      `Error details: [Error] ${CONTROL_PLANE_FAULT}`,
+    ]);
+    expect(final.messages, "the two system rows are the whole transcript").toHaveLength(2);
+
+    // ── Assert: nothing past the fault ───────────────────────────────────────
+    expect(recordedModelBuilds(), "no model was built").toHaveLength(0);
+    expect(record.setupProgress).toEqual(["Fetching execution", "Resolving agent blueprint"]);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/resolution-error.status.json");
+  });
+});