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

package/src/activities/execute-cursor/__tests__/hermetic/stream-self-stop-arms.test.ts

@@ -32,17 +32,17 @@
  *    is the one point a scenario can rely on: the STOP is keyed on the
  *    persisted status's CONTENT (the COMPLETED row), not on which persist
  *    happens to carry it, because a tool-call transition force-flushes
- *    (`contentDirty`) whatever the cadence says. (Until S3 M5 the scheduler
+ *    (the builder's `dirty` flag) whatever the cadence says. (Until #1096 the scheduler
  *    paced text-only persists on REAL `performance.now()` time; the scripted
- *    clock fakes it since Q-M5-7, so every persist is deterministic now.)
+ *    clock fakes it since then, so every persist is deterministic now.)
  *
- * Engine disposition and cancellation since S2 M3 (entry 20260911.03): the
- * adapter cancels the SDK run on EVERY stop (Q-M3-4; before, a platform stop
+ * Engine disposition and cancellation since #1070: the
+ * adapter cancels the SDK run on EVERY stop (before, a platform stop
  * broke the loop and left the run executing) and parks the handle on every
- * non-failed exit (Q-S2-6; before, a stall dropped it — the adapter cannot
+ * non-failed exit (before, a stall dropped it — the adapter cannot
  * tell a stall from a cost cap, and a wedged parked handle is caught by the
  * poisoned-handle recovery on the next turn). The two assertions that moved
- * say so on their line. The cost-cap golden was regenerated at M3b with a
+ * say so on their line. The cost-cap golden was regenerated in #1070 with a
  * timestamp-only diff (every terminal stamp one scripted second earlier):
  * the run is now cancelled the instant the signal aborts, before the SDK
  * double pulls — and the clock ticks on — one more step.
@@ -64,6 +64,9 @@ import {
 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(),
 );
@@ -185,7 +188,7 @@ describe("ExecuteCursor hermetic — the stream loop's self-stop arms", () => {
     // ── Assert: engine disposition ───────────────────────────────────────────
     expect(agent.runs[0].cancelCalls, "the runtime's stop cancelled the run once").toHaveLength(1);
     expect(agent.closeCalls, "the handle is not closed").toBe(0);
-    // Q-S2-6 (S2 M3): parked on every non-failed exit; before M3 a stall dropped it.
+    // Since #1070: parked on every non-failed exit; before, a stall dropped it.
     expect(_parkedAgentCountForTests(), "parked for the session's next turn").toBe(1);
     expect(record.sessionUpdates).toHaveLength(1);
 
@@ -213,7 +216,7 @@ describe("ExecuteCursor hermetic — the stream loop's self-stop arms", () => {
           step.event(ev.init()),
           step.event(ev.assistant("Reading the whole repository first.")),
           // 600 000 input tokens at the fixture's $1/M base rate = $0.60 > $0.50.
-          step.turnEnded({ inputTokens: 600_000, outputTokens: 0 }),
+          step.turnEnded({ inputTokens: 600_000, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.event(ev.assistant(NEVER_SEEN)),
           step.finished({ result: NEVER_SEEN }),
         ],
@@ -315,7 +318,7 @@ describe("ExecuteCursor hermetic — the stream loop's self-stop arms", () => {
     expect(final.messages.some((m) => m.content === NEVER_SEEN), "the event after the STOP is never processed").toBe(false);
 
     // ── Assert: engine disposition ───────────────────────────────────────────
-    // Q-M3-4 (S2 M3): the SDK run is cancelled on every stop; before M3 a
+    // Since #1070: the SDK run is cancelled on every stop; before, a
     // platform stop broke the loop and left the run executing behind the
     // parked handle.
     expect(agent.runs[0].cancelCalls, "the runtime's stop cancelled the run once").toHaveLength(1);

package/src/activities/execute-cursor/__tests__/hermetic/sub-agent-delegation.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Hermetic golden: SUB-AGENT DELEGATION on the Cursor harness — the root agent
+ * hands work to a sub-agent through the SDK's `task` tool, and the sub-agent's
+ * own conversation arrives, whole, in the `task` call's result.
+ *
+ * Invariant pinned: the translator opens a sub-agent for every
+ * `tool_call` named `task` (`sub_agent_started` before the row's own start) as
+ * well as writing the row to the root transcript. The `running` event opens a `SubAgentExecution` keyed by the
+ * task call id (`name` from `subagentType`, `subject` from `description`,
+ * `input` from `prompt`, IN_PROGRESS); the `completed` event closes it
+ * COMPLETED with `output` (the stringified result) and rebuilds its transcript
+ * from the result's `conversationSteps` (`sub-agent-steps.ts`): an
+ * `assistantMessage` step is an AI row, and a `toolCall` step is a tool row on
+ * the transcript's LAST AI message — the assistant step that proposed it — named
+ * from its `<kind>ToolCall` key (`buildSubAgentToolCall`), with the SDK's
+ * `toolCallId` as its id, its status from the `result` oneof, both timestamps,
+ * `args` and `argsPreview`; a tool step with no assistant step before it gets
+ * an empty AI message of its own, the root transcript's rule. The root
+ * transcript carries the `task` row itself (COMPLETED, `result` = the same
+ * stringified object) on the message that proposed it. This is Cursor's
+ * timing — the sub-agent's rows exist only at completion — and stays Cursor's.
+ *
+ * Moved 2026-09-14 (#1097), the ONE hunk this golden was
+ * predicted to take: the sub-agent's `read` row sits on the AI message of the
+ * assistant step that precedes it (`messages[0]`, "Looking at README.md."),
+ * and the `content: ""` message that carried it until then (`messages[1]`) is
+ * gone — the canonical builder attaches a tool row to its scope's current AI
+ * message, the shape native's sub-agent transcripts took in #1096, and the
+ * accumulator's steps extractor was aligned before the swap to the shared
+ * builder so the swap moved nothing.
+ *
+ * On the record as found (#1134): the `task` row's `result` and the
+ * sub-agent's `output` are two copies of one stringified object.
+ *
+ * Why this net exists: none of the seventeen earlier Cursor goldens carried
+ * a sub-agent row, and #1097 deleted the transcript-rebuild whole.
+ *
+ * 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,
+  SubAgentStatus,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { 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-subagent-0001";
+const RUN_ID = "run-hermetic-subagent-0001";
+const TASK_CALL_ID = "call-hermetic-task-0001";
+const SUB_READ_CALL_ID = "call-hermetic-sub-read-0001";
+const USER_MESSAGE = "Ask the helper what README.md says.";
+const ROOT_OPENING = "Delegating to the helper.";
+const TASK_ARGS = {
+  subagentType: "helper",
+  description: "Read README.md and report its content.",
+  prompt: "Read README.md and reply with its content in one line.",
+};
+const HELPER_OPENING = "Looking at README.md.";
+const HELPER_READ_ARGS = { path: "README.md" };
+const HELPER_READ_RESULT = "# Hermetic\n\nA fixture readme.\n";
+const HELPER_ANSWER = "README.md is a one-line fixture description.";
+/** The SDK's task result: the sub-agent's conversation as protobuf-oneof JSON steps. */
+const TASK_RESULT = {
+  conversationSteps: [
+    { type: "assistantMessage", message: { text: HELPER_OPENING } },
+    {
+      toolCall: {
+        toolCallId: SUB_READ_CALL_ID,
+        readToolCall: { args: HELPER_READ_ARGS, result: { success: { content: HELPER_READ_RESULT } } },
+      },
+    },
+    { type: "assistantMessage", message: { text: HELPER_ANSWER } },
+  ],
+};
+const ROOT_CLOSING = "The helper reports: README.md is a one-line fixture description.";
+
+describe("ExecuteCursor hermetic — sub-agent delegation", () => {
+  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("tracks the task as a SubAgentExecution keyed by the call id and rebuilds its transcript at completion", 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(ROOT_OPENING)),
+          step.event(ev.toolCall(TASK_CALL_ID, "task", "running", TASK_ARGS)),
+          step.event(ev.toolCall(TASK_CALL_ID, "task", "completed", TASK_ARGS, TASK_RESULT)),
+          step.event(ev.assistant(ROOT_CLOSING)),
+          step.turnEnded({ inputTokens: 3_900, outputTokens: 102, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: ROOT_CLOSING, 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 root transcript ──────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    expect(record.toolCalls().map((tc) => [tc.id, tc.name, tc.status])).toEqual([
+      [TASK_CALL_ID, "task", ToolCallStatus.TOOL_CALL_COMPLETED],
+    ]);
+    expect(final.messages.map((m) => [m.type, m.content, m.toolCalls.map((tc) => tc.id)])).toEqual([
+      [MessageType.MESSAGE_AI, ROOT_OPENING, [TASK_CALL_ID]],
+      [MessageType.MESSAGE_AI, ROOT_CLOSING, []],
+    ]);
+
+    // ── Assert: the sub-agent execution ──────────────────────────────────────
+    expect(final.subAgentExecutions).toHaveLength(1);
+    const sub = final.subAgentExecutions[0];
+    expect(sub.id, "keyed by the task call id").toBe(TASK_CALL_ID);
+    expect(sub.name).toBe("helper");
+    expect(sub.subject).toBe(TASK_ARGS.description);
+    expect(sub.input).toBe(TASK_ARGS.prompt);
+    expect(sub.status).toBe(SubAgentStatus.SUB_AGENT_COMPLETED);
+    expect(sub.startedAt < sub.completedAt).toBe(true);
+    expect(sub.output, "the stringified task result").toBe(JSON.stringify(TASK_RESULT));
+
+    // The rebuilt transcript: the tool step joins the assistant step that
+    // proposed it, the root transcript's own boundary rule.
+    expect(sub.messages.map((m) => [m.type, m.content, m.toolCalls.map((tc) => tc.id)])).toEqual([
+      [MessageType.MESSAGE_AI, HELPER_OPENING, [SUB_READ_CALL_ID]],
+      [MessageType.MESSAGE_AI, HELPER_ANSWER, []],
+    ]);
+    const subRead = sub.messages[0].toolCalls[0];
+    expect(subRead.name, "the bare tool name from the readToolCall key").toBe("read");
+    expect(subRead.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(subRead.args).toEqual(HELPER_READ_ARGS);
+    expect(subRead.result).toBe(JSON.stringify({ content: HELPER_READ_RESULT }));
+
+    // ── 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/sub-agent-delegation.status.json");
+  });
+});

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

@@ -0,0 +1,145 @@
+/**
+ * Hermetic golden: a turn with MODEL THINKING on both sides of a tool call,
+ * through the whole `ExecuteCursor` activity.
+ *
+ * Invariant pinned (the rule the canonical builder had to reproduce when it
+ * took over in #1097): the Cursor SDK has ONE `run_id` per `send()`, so the transcript's
+ * segmentation is not by run but by tool call — a `tool_call` event closes the
+ * run's streaming AI and THINKING rows (the translator's `message_finish` for
+ * the open segment; until #1097 the accumulator's own finalize on a tool call),
+ * and the thinking or text that follows opens NEW rows. Hence the shape:
+ * THINKING(T1), AI(A1 + the read row), THINKING(T2), AI(A2). The read row lands
+ * on A1 (the last AI message by backward scan; a THINKING row is skipped), and
+ * no row is left `isStreaming` when the turn ends.
+ *
+ * Predicted for the swap to the shared builder (2026-09-14): NO move.
+ * The builder keeps one THINKING row per segment on Cursor (the translator
+ * mints a segment id per text-or-thinking run between tool calls) and keeps
+ * the tool on the message that proposed it. A diff in this golden is a
+ * pause, not a regeneration.
+ *
+ * Why this net exists: none of the seventeen earlier Cursor goldens carried
+ * a THINKING row, and the thinking rule is one #1097 rewrote.
+ *
+ * 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, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("@cursor/sdk", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { 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-thinking-0001";
+const RUN_ID = "run-hermetic-thinking-0001";
+const CALL_ID = "call-hermetic-thinking-read-0001";
+const USER_MESSAGE = "Summarise README.md.";
+const THINKING_BEFORE = "The user wants a summary; I should read the file first.";
+const TEXT_BEFORE = "Reading the file.";
+const READ_ARGS = { path: "README.md" };
+const READ_RESULT = "# Hermetic\n\nA fixture readme.\n";
+const THINKING_AFTER = "One line of content; a one-sentence summary will do.";
+const TEXT_AFTER = "README.md is a one-line fixture description.";
+
+describe("ExecuteCursor hermetic — thinking on both sides of a 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("folds into THINKING, AI+row, THINKING, AI with nothing left streaming 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.thinking(THINKING_BEFORE)),
+          step.event(ev.assistant(TEXT_BEFORE)),
+          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.thinking(THINKING_AFTER)),
+          step.event(ev.assistant(TEXT_AFTER)),
+          step.turnEnded({ inputTokens: 2_400, outputTokens: 140, 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 segmentation ─────────────────────────────────────────────
+    const final = record.lastFullStatus!;
+    expect(
+      final.messages.map((m) => [m.type, m.content]),
+      "a tool call closes the run's THINKING and AI rows; what follows opens new ones",
+    ).toEqual([
+      [MessageType.MESSAGE_THINKING, THINKING_BEFORE],
+      [MessageType.MESSAGE_AI, TEXT_BEFORE],
+      [MessageType.MESSAGE_THINKING, THINKING_AFTER],
+      [MessageType.MESSAGE_AI, TEXT_AFTER],
+    ]);
+    expect(final.messages.every((m) => !m.isStreaming), "finalize clears every streaming flag").toBe(true);
+
+    // ── Assert: the row sits on the text that proposed it ────────────────────
+    const rows = record.toolCalls();
+    expect(rows.map((tc) => [tc.id, tc.status])).toEqual([[CALL_ID, ToolCallStatus.TOOL_CALL_COMPLETED]]);
+    expect(final.messages[1].toolCalls.map((tc) => tc.id), "the read row is on AI(A1), not on a THINKING row").toEqual([CALL_ID]);
+
+    // ── 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/thinking-turn.status.json");
+  });
+});

package/src/activities/execute-cursor/__tests__/hermetic/thrown-error-arms.test.ts

@@ -28,7 +28,7 @@
  * plane ever sees for these executions is EXECUTION_FAILED — `persistedPhases`
  * is `[FAILED]`, not `[IN_PROGRESS, FAILED]`.
  *
- * Golden hunk since S3 M4 (Q-M4-7, ruled Q-M4-12 A): `sdk-error-at-create`
+ * Golden hunk since #1096: `sdk-error-at-create`
  * carries an EMPTY `fileChangeProgress` (`changeSetId`, `capturedAt`, no
  * entries). The runtime refreshes the strip on every write, and this turn's
  * FAILED write is its first write in capture mode (the hermetic environment
@@ -49,6 +49,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/todo-write.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Hermetic golden: the agent's TO-DO LIST — two `updateTodos` tool calls, the
+ * second a `merge`, through the whole `ExecuteCursor` activity.
+ *
+ * Invariant pinned: a todo tool call is a row like any other AND a projection.
+ * The shared builder projects a COMPLETED `ToolKind.TODO` row's `args.todos`
+ * into `status.todos` through the shared `applyTodoUpdate` — a full replace by
+ * default, a MERGE when the SDK's args say `merge: true` (the first write's
+ * `createdAt` survives, `updatedAt` moves) — and the row stays on the message
+ * that proposed it: an `updateTodos`
+ * row (COMPLETED, `toolKind` TODO, `args`, `argsPreview`, `result`) on
+ * `messages[0]` and another on `messages[1]`. So: three AI messages, two
+ * rows, two todos. The web console hides the row (`isInternalTool`); the CLI
+ * TUI shows it, as it does for native.
+ *
+ * Moved 2026-09-14 (#1097), the TWO hunks this golden was
+ * predicted to take: until then the accumulator DROPPED the row (a suppressed-
+ * tool-names set) and the transcript showed three AI messages with
+ * no rows — a per-harness branch on a tool name the canonical builder does
+ * not have (native has always kept its `write_todos` row). The accumulator
+ * was aligned before the swap to the shared builder so the swap moved nothing;
+ * `todos` was and is byte-identical. The todo tracker went at the swap, where
+ * the builder took over projecting the todos from the row.
+ *
+ * Why this net exists: no earlier Cursor golden carried a todo.
+ *
+ * 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, TodoStatus, 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-todo-0001";
+const RUN_ID = "run-hermetic-todo-0001";
+const FIRST_CALL_ID = "call-hermetic-todo-0001";
+const SECOND_CALL_ID = "call-hermetic-todo-0002";
+const USER_MESSAGE = "Plan the two steps, then do the first.";
+const TEXT_PLAN = "Two steps; writing them down.";
+/** The current SDK's `updateTodos` shape: camelCase statuses, no per-item id. */
+const FIRST_WRITE = {
+  todos: [
+    { content: "Read the fixture", status: "pending" },
+    { content: "Summarise it", status: "pending" },
+  ],
+};
+const TEXT_WORK = "First step done.";
+const SECOND_WRITE = {
+  todos: [{ content: "Read the fixture", status: "completed" }],
+  merge: true,
+};
+const TEXT_CLOSING = "The first step is complete; the second is pending.";
+
+describe("ExecuteCursor hermetic — todo writes", () => {
+  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("projects a replace then a merge into status.todos and keeps a row per write in the transcript", 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_PLAN)),
+          step.event(ev.toolCall(FIRST_CALL_ID, "updateTodos", "running", FIRST_WRITE)),
+          step.event(ev.toolCall(FIRST_CALL_ID, "updateTodos", "completed", FIRST_WRITE, "ok")),
+          step.event(ev.assistant(TEXT_WORK)),
+          step.event(ev.toolCall(SECOND_CALL_ID, "updateTodos", "running", SECOND_WRITE)),
+          step.event(ev.toolCall(SECOND_CALL_ID, "updateTodos", "completed", SECOND_WRITE, "ok")),
+          step.event(ev.assistant(TEXT_CLOSING)),
+          step.turnEnded({ inputTokens: 2_600, outputTokens: 160, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: TEXT_CLOSING, 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 transcript — a row per write, on the message that proposed it ──
+    const final = record.lastFullStatus!;
+    expect(
+      final.messages.map((m) => [m.type, m.content, m.toolCalls.length]),
+      "the todo call splits the text like any tool, and its row stays",
+    ).toEqual([
+      [MessageType.MESSAGE_AI, TEXT_PLAN, 1],
+      [MessageType.MESSAGE_AI, TEXT_WORK, 1],
+      [MessageType.MESSAGE_AI, TEXT_CLOSING, 0],
+    ]);
+    const rows = record.toolCalls();
+    expect(rows.map((tc) => [tc.id, tc.toolKind, tc.status])).toEqual([
+      [FIRST_CALL_ID, ToolKind.TODO, ToolCallStatus.TOOL_CALL_COMPLETED],
+      [SECOND_CALL_ID, ToolKind.TODO, ToolCallStatus.TOOL_CALL_COMPLETED],
+    ]);
+
+    // ── Assert: the todos, by key (byte-identical across the swap) ──────────
+    expect(Object.keys(final.todos).sort()).toEqual(["todo-0", "todo-1"]);
+    const first = final.todos["todo-0"];
+    const second = final.todos["todo-1"];
+    expect([first.content, first.status]).toEqual(["Read the fixture", TodoStatus.TODO_COMPLETED]);
+    expect(first.createdAt < first.updatedAt, "the merge kept the first write's createdAt and moved updatedAt").toBe(true);
+    expect([second.content, second.status]).toEqual(["Summarise it", TodoStatus.TODO_PENDING]);
+    expect(second.createdAt, "untouched by the merge").toBe(second.updatedAt);
+
+    // ── 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/todo-write.status.json");
+  });
+});

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

@@ -8,11 +8,11 @@
  * event's args, `result` from the completed event, `startedAt`/`completedAt`
  * from the two events' instants, `toolKind` classified, no approval fields set
  * (a read-only built-in is not gated) — and the turn ends COMPLETED. The golden
- * (`goldens/tool-call.status.json`) is the row shape S4's canonical transcript
- * builder must reproduce byte for byte.
+ * (`goldens/tool-call.status.json`) is the row shape the canonical transcript
+ * builder (#1097) must reproduce byte for byte.
  *
  * Parent phase rows exercised beyond `plain-turn`: run the turn and consume
- * the engine stream (tool-call folding in `message-translator.ts`); the turn
+ * the engine stream (`translator.ts` into the shared `TranscriptBuilder`); the turn
  * boundary with nothing to gate or capture (a read tool writes no file; the
  * per-session workspace is unchanged, so the capture finds no candidate).
  *
@@ -28,6 +28,9 @@ import { ExecutionPhase, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agent
 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(),
 );
@@ -86,7 +89,7 @@ describe("ExecuteCursor hermetic — ungated tool call", () => {
           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(ASSISTANT_TEXT)),
-          step.turnEnded({ inputTokens: 2_000, outputTokens: 90 }),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 90, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: ASSISTANT_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],