@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/activities/execute-cursor/__tests__/hermetic/mcp-tool-call.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Hermetic golden: an MCP TOOL CALL — the SDK reports the call as `name: "mcp"`
+ * and packs the real identity into its args — through the whole
+ * `ExecuteCursor` activity.
+ *
+ * Invariant pinned: the translator unwraps
+ * `{ providerIdentifier, toolName, args }` from the event's args
+ * (`extractMcpToolDetails`) and the row is the INNER tool: `name` is `toolName`,
+ * `mcpServerSlug` is `providerIdentifier`, `args` is the inner args,
+ * `toolKind` is MCP, and `argsPreview` is the elided preview of the row's OWN
+ * `args` — `{"query":"fixture"}` — through the platform's one sanitizer. With
+ * no MCP server declared on the record there is no policy for the tool, so it
+ * is not gated; the provenance stamp still names the layer that cleared it.
+ *
+ * Moved 2026-09-14 (#1097), the ONE hunk this golden was
+ * predicted to take: until then the stream path stamped the OUTER
+ * `{ providerIdentifier, toolName, args }` envelope stringified — the
+ * envelope, not the arguments. The canonical builder derives every row's
+ * preview from its `args` and never from an engine's envelope; the
+ * accumulator was aligned to that rule before the swap to the shared builder,
+ * so the swap moved nothing.
+ *
+ * Why this net exists: no earlier Cursor golden carried an MCP-attributed
+ * row, and #1097 moved the unwrapping whole into the Cursor translator.
+ *
+ * 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, ToolCallStatus, ToolKind } 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 AGENT_ID = "agent-hermetic-mcp-0001";
+const RUN_ID = "run-hermetic-mcp-0001";
+const CALL_ID = "call-hermetic-mcp-0001";
+const USER_MESSAGE = "Search the docs for the fixture.";
+const TEXT_BEFORE = "Searching the docs.";
+const MCP_SERVER = "hermetic-docs";
+const MCP_TOOL = "search_docs";
+const INNER_ARGS = { query: "fixture" };
+/** The SDK's MCP envelope: the real identity is inside the `mcp` call's args. */
+const MCP_EVENT_ARGS = { providerIdentifier: MCP_SERVER, toolName: MCP_TOOL, args: INNER_ARGS };
+const MCP_RESULT = "1 result: README.md — A fixture readme.";
+const TEXT_AFTER = "One document mentions the fixture: README.md.";
+
+describe("ExecuteCursor hermetic — MCP tool call", () => {
+  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("writes the row as the inner tool with its server slug and completes", async () => {
+    // ── Arrange ──────────────────────────────────────────────────────────────
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant(TEXT_BEFORE)),
+          step.event(ev.toolCall(CALL_ID, "mcp", "running", MCP_EVENT_ARGS)),
+          step.event(ev.toolCall(CALL_ID, "mcp", "completed", MCP_EVENT_ARGS, MCP_RESULT)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 2_100, outputTokens: 80, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_AFTER, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    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: outcome ──────────────────────────────────────────────────────
+    expect(invocation.outcome.kind).toBe("returned");
+    expect((invocation.outcome as { value: Record<string, unknown> }).value.phase).toBe("EXECUTION_COMPLETED");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+
+    // ── Assert: the attributed row ───────────────────────────────────────────
+    const rows = record.toolCalls();
+    expect(rows).toHaveLength(1);
+    const row = rows[0];
+    expect(row.id).toBe(CALL_ID);
+    expect(row.name, "the inner tool, never the `mcp` envelope").toBe(MCP_TOOL);
+    expect(row.mcpServerSlug).toBe(MCP_SERVER);
+    expect(row.toolKind).toBe(ToolKind.MCP);
+    expect(row.args, "the inner args").toEqual(INNER_ARGS);
+    expect(row.argsPreview, "the row's own args, never the engine's envelope").toBe(
+      JSON.stringify(INNER_ARGS),
+    );
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(row.result).toBe(MCP_RESULT);
+    expect(row.requiresApproval, "no server declared, no policy, not gated").toBe(false);
+
+    // ── Assert: hermeticity ──────────────────────────────────────────────────
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    // ── Assert: the golden ───────────────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, final), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/mcp-tool-call.status.json");
+  });
+});

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

@@ -26,8 +26,8 @@
  * 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
+ * goldens pinned that double on purpose so #1070 could reproduce the wire byte
+ * for byte (removed in stigmer#1054). 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
@@ -35,11 +35,11 @@
  * arms through `settleWith`; the `finally` teardown under a thrown exit.
  *
  * Regeneration history:
- *  - S2 M3b (entry 20260911.03): timestamp-only diff — every terminal stamp
+ *  - #1070: 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,
+ *    the runtime's stop signal aborts, 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
+ *  - 2026-09-12 (stigmer#1054, the PR after #1070): one removed system row per
  *    golden, nothing else. The transcript now carries each terminal row once.
  *
  * Regenerate ONLY after a deliberate behavior change:
@@ -54,6 +54,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );

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

@@ -9,7 +9,8 @@
  * 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
+ * Phase rows of the pre-runtime orchestrator this net was recorded against
+ * (#1048): 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
@@ -37,6 +38,9 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -93,7 +97,7 @@ describe("ExecuteCursor hermetic — plain turn", () => {
             run_id: RUN_ID,
             message: { role: "assistant", content: [{ type: "text", text: ASSISTANT_TEXT }] },
           }),
-          step.turnEnded({ inputTokens: 1_200, outputTokens: 40 }),
+          step.turnEnded({ inputTokens: 1_200, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({
             result: ASSISTANT_TEXT,
             model: {

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

@@ -33,6 +33,9 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -104,7 +107,7 @@ describe("ExecuteCursor hermetic — poisoned-handle recovery on a fresh agent",
         [
           step.event(evFresh.init()),
           step.event(evFresh.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 2_800, outputTokens: 55 }),
+          step.turnEnded({ inputTokens: 2_800, outputTokens: 55, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/run-wait-arms.test.ts

@@ -5,7 +5,8 @@
  * Phase 13 of the activity maps what the SDK's `run.wait()` resolves into a
  * terminal phase, and the `error` case is where the error classifier decides
  * whether the runner tries again on its own. The three scenarios here pin the
- * three outcomes of that decision table that the S0 net did not cover (the
+ * three outcomes of that decision table that the first hermetic net (#1048)
+ * did not cover (the
  * poisoned-handle recovery on a RESUMED agent is `recovery-fresh-agent.test.ts`):
  *
  *  1. A NON-RETRYABLE error (auth class): the classifier files it as
@@ -44,6 +45,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -175,7 +179,7 @@ describe("ExecuteCursor hermetic — the run.wait() arms on a created agent", ()
         [
           step.event(evFresh.init()),
           step.event(evFresh.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 2_200, outputTokens: 30 }),
+          step.turnEnded({ inputTokens: 2_200, outputTokens: 30, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/sdk-task-note.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Hermetic golden: the SDK's `task` event — a status line about the run in
+ * the agent's own voice — between two assistant messages, through the whole
+ * `ExecuteCursor` activity.
+ *
+ * Invariant pinned (#1097; until then this event had no test on either
+ * tier): a `task` event with text becomes ONE SYSTEM
+ * message at its position in the transcript (`translateTask`); it hosts no
+ * tool rows and does not move the AI-message boundary — the tool call that
+ * follows it lands on the assistant message BEFORE the note, and the text
+ * after the tool call is a new message. A `task` event with no text produces
+ * nothing.
+ *
+ * Predicted for the swap to the shared builder: NO move. The translator
+ * maps `task.text` to the union's `system_note`, which the builder
+ * appends as a SYSTEM message in the scope with the same placement rule.
+ *
+ * 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("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
+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 AGENT_ID = "agent-hermetic-tasknote-0001";
+const RUN_ID = "run-hermetic-tasknote-0001";
+const CALL_ID = "call-hermetic-tasknote-read-0001";
+const USER_MESSAGE = "Summarise README.md.";
+const TEXT_BEFORE = "Reading the file first.";
+const TASK_NOTE = "Scanning the workspace for the file.";
+const READ_ARGS = { path: "README.md" };
+const READ_RESULT = "# Hermetic\n\nA fixture readme.\n";
+const TEXT_AFTER = "README.md is a one-line fixture description.";
+
+describe("ExecuteCursor hermetic — the SDK's task event as a system note", () => {
+  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("places the note as a SYSTEM message that hosts no rows and moves no boundary; an empty note produces nothing", async () => {
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant(TEXT_BEFORE)),
+          step.event(ev.task(TASK_NOTE, "running")),
+          step.event(ev.task("", "running")),
+          step.event(ev.toolCall(CALL_ID, "read", "running", READ_ARGS)),
+          step.event(ev.toolCall(CALL_ID, "read", "completed", READ_ARGS, READ_RESULT)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 1_800, outputTokens: 50, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_AFTER, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    const invocation = await runCursorTurn(scenario);
+
+    expect(invocation.outcome.kind).toBe("returned");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+
+    const messages = record.lastFullStatus!.messages;
+    expect(messages.map((m) => m.type), "AI, the note, AI").toEqual([
+      MessageType.MESSAGE_AI,
+      MessageType.MESSAGE_SYSTEM,
+      MessageType.MESSAGE_AI,
+    ]);
+    expect(messages[1].content).toBe(TASK_NOTE);
+    expect(messages[1].toolCalls, "a note hosts no rows").toHaveLength(0);
+    expect(messages[0].toolCalls.map((tc) => tc.id), "the row lands on the assistant message before the note").toEqual([CALL_ID]);
+    expect(messages[2].content).toBe(TEXT_AFTER);
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/sdk-task-note.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/shell-output-delta.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Hermetic goldens: the SDK's DELTA CHANNEL folding onto a shell tool's row —
+ * `tool-call-started`, `shell-output-delta` and `tool-call-completed` fired
+ * through `onDelta` between the stream's own `tool_call` events — through the
+ * whole `ExecuteCursor` activity.
+ *
+ * Why this net exists (#1097): the scripted double emitted only the
+ * `turn-ended` usage delta until then, so the rule that PR changed most —
+ * a completion learned from the timing delta and merged with the stream's
+ * later completion — had no end-to-end net; `delta-enricher.ts`'s
+ * twelve unit arms were the whole of it. The three arms below were pinned
+ * on the enricher's fold before the swap to the shared builder, and each
+ * header states what was predicted to move at the swap and after it.
+ *
+ * Arm 1 — the ordinary order. The stream's `running` creates the row; the
+ * deltas arrive; the stream's `completed` settles it. Pinned: `startedAt` is
+ * the stream's `running` instant; the live output reaches `result`
+ * (`streamingSource: OUTPUT` while it streams, cleared at finalize); the
+ * stream's `completed` stamps `completedAt` and its result wins; the shell
+ * row is a gated built-in (`requiresApproval`, "Run command: …") that the
+ * hook never saw, so no `approvalRequestedAt`. Predicted: NO move (the
+ * translator drains the queued deltas AFTER the stream event of the
+ * same window, as the enricher applied them, so the stream's instant wins
+ * exactly as before).
+ *
+ * Arm 2 — output BEFORE the row exists. A `shell-output-delta` fires before
+ * the stream's `running` for its call. Pinned: nothing is lost — the enricher
+ * buffers the chunk and applies it once the row exists, so the final `result`
+ * carries both chunks in order. Predicted: NO move (the translator holds
+ * a delta for a call the stream has not announced and replays it after the
+ * `tool_started` that announces it).
+ *
+ * Arm 3 — the completion delta reports an ERROR, and a model event sits
+ * between it and the stream's own `error`. Pinned: the translator honours the
+ * delta's `result.status: "error"` — the row is FAILED from the
+ * instant the failure was observed (`completedAt` and, for a gated shell,
+ * `approvalRequestedAt` at the delta's own tick), and the stream's `error`
+ * event that follows supplies the text. Until #1097 (as this net first
+ * pinned it) the enricher promoted every completion delta to
+ * COMPLETED, the monotonic merge then refused the stream's FAILED, and the
+ * row ended COMPLETED carrying an `error` — a row that lied. Moved in #1097
+ * by one line this header had not named when the net was written:
+ * the failure text is `error` alone; and, as predicted, in the
+ * status and in `approvalRequestedAt`.
+ *
+ * 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 type { InteractionUpdate } from "@cursor/sdk";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { 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("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
+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 USER_MESSAGE = "Run the test suite.";
+const COMMAND = "npm test";
+const SHELL_ARGS = { command: COMMAND };
+const CHUNK_1 = "> test\n";
+const CHUNK_2 = "12 passing\n";
+const FULL_OUTPUT = CHUNK_1 + CHUNK_2;
+
+/**
+ * The delta channel's shapes, typed against the SDK so a drift fails `tsc`
+ * (the stigmer#1053 dividend — writing these is how the runner learned the
+ * timing deltas carry `modelCallId`, the LLM call that issued the tool;
+ * nothing in the runner reads it yet).
+ */
+const MODEL_CALL_ID = "model-call-hermetic-shelldelta";
+const deltas = {
+  started(callId: string): InteractionUpdate {
+    return { type: "tool-call-started", callId, modelCallId: MODEL_CALL_ID, toolCall: { type: "shell", args: SHELL_ARGS } };
+  },
+  output(callId: string, data: string): InteractionUpdate {
+    return { type: "shell-output-delta", event: { callId, type: "stdout", data } };
+  },
+  completedOk(callId: string, stdout: string): InteractionUpdate {
+    return {
+      type: "tool-call-completed",
+      callId,
+      modelCallId: MODEL_CALL_ID,
+      toolCall: {
+        type: "shell",
+        args: SHELL_ARGS,
+        result: { status: "success", value: { exitCode: 0, signal: "", stdout, stderr: "", executionTime: 1_200 } },
+      },
+    };
+  },
+  completedError(callId: string, error: string): InteractionUpdate {
+    return {
+      type: "tool-call-completed",
+      callId,
+      modelCallId: MODEL_CALL_ID,
+      toolCall: { type: "shell", args: SHELL_ARGS, result: { status: "error", error } },
+    };
+  },
+};
+
+describe("ExecuteCursor hermetic — the delta channel on a shell row", () => {
+  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("arm 1: started, output and completed deltas between the stream's running and completed fold onto one row", async () => {
+    const AGENT_ID = "agent-hermetic-shelldelta-0001";
+    const RUN_ID = "run-hermetic-shelldelta-0001";
+    const CALL_ID = "call-hermetic-shelldelta-0001";
+    const TEXT_AFTER = "All 12 tests pass.";
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant("Running the tests.")),
+          step.event(ev.toolCall(CALL_ID, "shell", "running", SHELL_ARGS)),
+          step.delta(deltas.started(CALL_ID)),
+          step.delta(deltas.output(CALL_ID, CHUNK_1)),
+          step.delta(deltas.output(CALL_ID, CHUNK_2)),
+          step.delta(deltas.completedOk(CALL_ID, FULL_OUTPUT)),
+          step.event(ev.toolCall(CALL_ID, "shell", "completed", SHELL_ARGS, FULL_OUTPUT)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 60, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_AFTER, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    const invocation = await runCursorTurn(scenario);
+
+    expect(invocation.outcome.kind).toBe("returned");
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    const rows = record.toolCalls();
+    expect(rows, "the stream's two events and the four deltas fold into ONE row").toHaveLength(1);
+    const row = rows[0];
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(row.result, "the live output reached the row").toBe(FULL_OUTPUT);
+    expect(row.isStreaming, "finalize closed the OUTPUT stream").toBe(false);
+    expect(row.startedAt < row.completedAt).toBe(true);
+    expect(row.requiresApproval, "a shell is a gated built-in the hook never saw").toBe(true);
+    expect(row.approvalRequestedAt).toBe("");
+    expect(registry.urls.every((u) => u.includes("/model-registry"))).toBe(true);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/shell-output-delta.status.json");
+  });
+
+  it("arm 2: an output delta that precedes the stream's running is held and lands once the row exists", async () => {
+    const AGENT_ID = "agent-hermetic-shelldelta-0002";
+    const RUN_ID = "run-hermetic-shelldelta-0002";
+    const CALL_ID = "call-hermetic-shelldelta-0002";
+    const TEXT_AFTER = "Done; the suite is green.";
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant("Running the tests.")),
+          step.delta(deltas.started(CALL_ID)),
+          step.delta(deltas.output(CALL_ID, CHUNK_1)),
+          step.event(ev.toolCall(CALL_ID, "shell", "running", SHELL_ARGS)),
+          step.delta(deltas.output(CALL_ID, CHUNK_2)),
+          step.delta(deltas.completedOk(CALL_ID, FULL_OUTPUT)),
+          step.event(ev.toolCall(CALL_ID, "shell", "completed", SHELL_ARGS, FULL_OUTPUT)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 60, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_AFTER, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    await runCursorTurn(scenario);
+
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    const rows = record.toolCalls();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(rows[0].result, "the early chunk was not lost").toBe(FULL_OUTPUT);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/shell-output-delta.output-first.status.json");
+  });
+
+  it("arm 3: an error-status completion delta, with a model event before the stream's error, fails the row from the instant it was observed", async () => {
+    const AGENT_ID = "agent-hermetic-shelldelta-0003";
+    const RUN_ID = "run-hermetic-shelldelta-0003";
+    const CALL_ID = "call-hermetic-shelldelta-0003";
+    const SHELL_ERROR = "sh: npm: command not found";
+    const TEXT_AFTER = "npm is not installed here.";
+    const ev = sdkEvents(AGENT_ID, RUN_ID);
+    const agent = new ScriptedCursorAgent({
+      agentId: AGENT_ID,
+      runIds: [RUN_ID],
+      observeStep: () => clock.tick(),
+      turns: [
+        [
+          step.event(ev.init()),
+          step.event(ev.assistant("Running the tests.")),
+          step.event(ev.toolCall(CALL_ID, "shell", "running", SHELL_ARGS)),
+          step.delta(deltas.started(CALL_ID)),
+          step.delta(deltas.completedError(CALL_ID, SHELL_ERROR)),
+          // The model reacts before the stream reports the tool's own outcome —
+          // the interleaving that lets a completion delta settle the row first.
+          step.event(ev.thinking("The command failed; npm may be missing.")),
+          step.event(ev.toolCall(CALL_ID, "shell", "error", SHELL_ARGS, SHELL_ERROR)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 80, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_AFTER, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({ env, clock, record, sdk: { agents: [agent], catalog: SDK_CATALOG } });
+
+    await runCursorTurn(scenario);
+
+    expect(record.persistedPhases.at(-1)).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    const rows = record.toolCalls();
+    expect(rows).toHaveLength(1);
+    const row = rows[0];
+    // The delta said the tool failed; the row says so from that instant.
+    expect(row.status).toBe(ToolCallStatus.TOOL_CALL_FAILED);
+    expect(row.error, "the stream's error event supplied the text").toBe(SHELL_ERROR);
+    expect(row.result).toBe("");
+    expect(row.approvalRequestedAt, "a gated shell's gate stamp shares the observed instant").toBe(row.completedAt);
+
+    const json = JSON.stringify(toJson(AgentExecutionStatusSchema, record.lastFullStatus!), null, 2) + "\n";
+    await expect(json).toMatchFileSnapshot("./goldens/shell-output-delta.error-delta.status.json");
+  });
+});