@stigmer/runner 3.19.1-dev.20260920100552 → 3.20.0

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

@@ -0,0 +1,118 @@
+/**
+ * Hermetic proof: the native harness gets the runtime's `turn_phases` timing
+ * line without a line of its own.
+ *
+ * Invariant pinned: driving the REAL deepagents graph through the real native
+ * translator, the turn runtime writes exactly one `turn_phases` line for the
+ * turn, and the line reads what the translator's events said — one model
+ * round per LangGraph run (two here: the proposal and the closing text), one
+ * tool span for the `read_file` call, the three root instants present, the
+ * adapter's own name as `harness`. The fold and its rules are
+ * `harness/__tests__/turn-timeline.test.ts`'s; the runtime's act of writing
+ * the line is `harness/__tests__/run-turn.test.ts`'s against the fake. What
+ * only this file can prove is that the native translator emits the events the
+ * fold needs (`message_start`/`message_finish` per run, `tool_started`/
+ * `tool_finished` per call) in the order it needs them, on a real graph.
+ *
+ * Structural assertions only: the scripted clock makes every number
+ * deterministic, but pinning one would pin the clock's tick quantum, not a
+ * behaviour. The status goldens beside this file are untouched by design —
+ * the line is stdout, never the status — and their byte-identity under this
+ * change is proved by running them.
+ *
+ * Same scenario as `tool-call.test.ts`, so the two files read together.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+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 { captureTimingLines } from "../../../../__test-utils__/timing-lines.js";
+import { TURN_PHASES_EVENT } from "../../../../harness/turn-timeline.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+
+const CALL_ID = "call-hermetic-read-0001";
+const USER_MESSAGE = "What is in README.md?";
+const README = "# Hermetic\n\nA fixture readme.\n";
+const ASSISTANT_TEXT = "README.md holds a one-line fixture description.";
+
+describe("ExecuteDeepAgent hermetic — the runtime's turn_phases line", () => {
+  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 one line for the turn, reading the translator's rounds and tool spans", async () => {
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: [
+          {
+            text: "Let me read it.",
+            toolCalls: [{ id: CALL_ID, name: "read_file", args: { file_path: "/README.md" } }],
+            usage: { inputTokens: 1_500, outputTokens: 60 },
+          },
+          { text: ASSISTANT_TEXT, usage: { inputTokens: 1_700, outputTokens: 30 } },
+        ],
+      }),
+    });
+    const workspace = sessionWorkspaceDir(env);
+    mkdirSync(workspace, { recursive: true });
+    writeFileSync(join(workspace, "README.md"), README, "utf-8");
+
+    const lines = await captureTimingLines(TURN_PHASES_EVENT, async () => {
+      const invocation = await runDeepAgentTurn(scenario);
+      expect(invocation.outcome.kind).toBe("returned");
+    });
+
+    expect(lines, "one line per turn").toHaveLength(1);
+    const line = lines[0]!;
+    expect(line.harness, "the adapter's diagnostic name, the runtime's vocabulary").toBe("deep-agent");
+    expect(line.outcome).toBe("completed");
+    expect(line.execution_id).toBe(record.execution.metadata!.id);
+    expect(line.turn_seq).toBeTypeOf("number");
+
+    expect(line.rounds, "the proposing run and the closing run").toBe(2);
+    expect(line.tool_calls).toBe(1);
+    expect(line.sub_agents).toBe(0);
+    expect(line.segments.filter((s) => s.name === "model_round")).toHaveLength(2);
+    expect(line.segments.filter((s) => s.name === "tool:read_file")).toHaveLength(1);
+
+    expect(line.first_event_ms).toBeTypeOf("number");
+    expect(line.first_visible_token_ms).toBeTypeOf("number");
+    expect(line.first_text_ms).toBeTypeOf("number");
+    expect(line.total_ms).toBeGreaterThanOrEqual(line.first_text_ms as number);
+  });
+});

package/src/harness/README.md

@@ -47,6 +47,10 @@ pinned somewhere. Read a row across before searching for anything.
   translator emits.
 - `harness/transcript/builder.ts` — `TranscriptBuilder`, the one builder every
   harness folds its events through.
+- `harness/turn-timeline.ts` — `TurnTimeline`, the runtime's fold over that
+  builder's events into the `turn_phases` timing line every harness gets for
+  free: first visible token, model rounds, tool and sub-agent spans, the
+  longest silence.
 - `harness/capture.ts` — the file-review capture. The runtime owns all of it; an
   adapter supplies one fact, which CAS-owned paths its engine touched.
 - `harness/turn-context.ts` — the resolution phases that build the `TurnInput`
@@ -204,7 +208,6 @@ Every hit falls into one of three classes:
 | `sdk/react/src/workflow/inspector/forms/AgentCallForm.tsx`                                                                                                                     | Two radio buttons, placed by hand.                                                                                                                                                                                                                                                                                            |
 | `sdk/react/src/pricing-governance/BaselineEditor.tsx`                                                                                                                          | A select with one option per harness.                                                                                                                                                                                                                                                                                         |
 | `site/src/components/pages/pricing/ModelPricingTable.tsx`                                                                                                                      | Harness to display label.                                                                                                                                                                                                                                                                                                     |
-| `site/src/data/harness-cost-comparison.json`                                                                                                                                   | Per-harness cost rows.                                                                                                                                                                                                                                                                                                        |
 | `docs/concepts/harnesses.mdx`, `docs/concepts/sessions.mdx`, `docs/guides/runners/cursor-harness.mdx`, `docs/guides/workflows/task-types/agent-call.mdx`, `docs/vocabulary.md` | Hand-authored pages that name the harness set; each has an entry in `docs/_inventory/classification.yaml` to keep current.                                                                                                                                                                                                    |
 
 The cloud composition that serves api.stigmer.ai has sites of the same three

package/src/harness/__tests__/run-turn.test.ts

@@ -53,13 +53,16 @@ import {
   assertFailedSurfaceWritesItsCopy,
   assertNonExecutingDecisionSettlesSkipped,
   assertRejectedBindFails,
+  assertWorkspaceLockTimeoutFails,
   describeHarnessRuntimeContract,
   RuntimeExecutionDriver,
   slimOf,
   systemMessages,
   type RuntimeContractHarness,
 } from "../../__test-utils__/harness-contract/runtime-contract.js";
+import { captureTimingLines } from "../../__test-utils__/timing-lines.js";
 import { TERMINAL_COPY } from "../terminal-table.js";
+import { TURN_PHASES_EVENT } from "../turn-timeline.js";
 import type { HarnessAdapter } from "../types.js";
 
 const TASK_QUEUE = "runtime-test-queue";
@@ -219,6 +222,56 @@ describe("run-turn: the fake adapter through the real runtime", () => {
     });
   });
 
+  describe("the runtime's turn timeline", () => {
+    // `run-turn.ts` emits the `turn_phases` line once, after the adapter
+    // returns and the transcript is finalized, on every outcome; a turn that
+    // never reached the engine emits none. The line's CONTENT is
+    // `turn-timeline.test.ts`'s; what is pinned here is the runtime's act:
+    // that the fold is installed on the one builder the adapter is handed,
+    // that the line names the adapter and the activity's turn, and that it is
+    // written for a failed turn as for a completed one.
+    const turnPhasesLines = (act: () => Promise<void>) => captureTimingLines(TURN_PHASES_EVENT, act);
+
+    it("writes one turn_phases line for a completed turn, naming the adapter, the turn and what the fold saw", async () => {
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(harness, "fake-timeline-completed");
+      const lines = await turnPhasesLines(async () => {
+        const invocation = await driver.turn([scenario.say("Reading it."), scenario.read("t1", "notes.md"), scenario.say("Done.")]);
+        expect(slimOf(subject, invocation).phase).toBe("EXECUTION_COMPLETED");
+      });
+
+      expect(lines).toHaveLength(1);
+      const [line] = lines;
+      expect(line!.harness).toBe(subject.adapter.name);
+      expect(line!.outcome).toBe("completed");
+      expect(line!.turn_seq).toBeTypeOf("number");
+      expect(line!.rounds, "two `say`s, two rounds").toBe(2);
+      expect(line!.tool_calls, "one `read`").toBe(1);
+      expect(line!.first_text_ms).toBeTypeOf("number");
+    });
+
+    it("writes the line for a failed turn too: every outcome is measured", async () => {
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(harness, "fake-timeline-failed");
+      const lines = await turnPhasesLines(async () => {
+        const invocation = await driver.turn([scenario.say("Checking."), scenario.fail("engine gave up")]);
+        expect(slimOf(subject, invocation).phase).toBe("EXECUTION_FAILED");
+      });
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]!.outcome).toBe("failed");
+      expect(lines[0]!.rounds).toBe(1);
+    });
+
+    it("writes no line for a turn that settled during resolution: no engine, no phases", async () => {
+      clock.reset();
+      const lines = await turnPhasesLines(async () => {
+        await assertWorkspaceLockTimeoutFails(harness, "fake-timeline-no-engine");
+      });
+      expect(lines).toEqual([]);
+    });
+  });
+
   describe("the runtime's write-back rule", () => {
     // `run-turn.ts` calls `frame.writeback.finalize()` in exactly two places:
     // once when a completed turn reaches its epilogue, and once when a resumed

package/src/harness/__tests__/turn-timeline.test.ts

@@ -0,0 +1,274 @@
+/**
+ * `TurnTimeline` (`harness/turn-timeline.ts`), driven with `TranscriptEvent`s
+ * on a scripted clock — one arm per rule the module's header lists, in the
+ * order it lists them, plus the shape of the `turn_phases` line it writes.
+ *
+ * What these arms protect: the parity comparison reads this line for both
+ * harnesses, so a rule that quietly favoured one (a tool span closed at the
+ * fold's clock instead of the observed instant; a sub-agent's token counted
+ * as the user's first visible token) would bias a published number. Every
+ * instant here is asserted exactly, which the scripted clock makes possible;
+ * the hermetic proofs under each adapter assert structure only.
+ *
+ * Fence-clean: names the runtime's timing primitive and the transcript's
+ * union, nothing of any engine.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TURN_PHASES_EVENT, TurnTimeline, type TurnTimelineClock } from "../turn-timeline.js";
+import type { TranscriptEvent } from "../transcript/events.js";
+
+/**
+ * A clock the test advances by hand. `performance.now()` scale starts at the
+ * origin 10_000; the wall clock at a fixed epoch, so an `observedAt` stamp can
+ * be written as "origin + N ms" and land exactly.
+ */
+const ORIGIN_MS = 10_000;
+const ORIGIN_WALL_MS = Date.UTC(2026, 8, 18, 12, 0, 0, 0);
+
+class ScriptedClock implements TurnTimelineClock {
+  readonly originMs = ORIGIN_MS;
+  readonly originWallMs = ORIGIN_WALL_MS;
+  private nowMs = ORIGIN_MS;
+
+  readonly now = (): number => this.nowMs;
+
+  /** Move the clock to `offset` ms after the origin. */
+  at(offset: number): void {
+    this.nowMs = ORIGIN_MS + offset;
+  }
+}
+
+/** The ISO stamp a harness would put on a fact it observed `offset` ms after the origin. */
+function observedWall(offset: number): string {
+  return new Date(ORIGIN_WALL_MS + offset).toISOString();
+}
+
+interface EmittedLine {
+  readonly stigmer_timing: string;
+  readonly total_ms: number;
+  readonly segments: Array<{ name: string; start_ms: number; duration_ms: number }>;
+  readonly [key: string]: unknown;
+}
+
+/** Drive `steps` (an offset and the event to observe at it), emit, and parse the one line. */
+function run(steps: Array<[number, TranscriptEvent]>, settleAt: number, context: Record<string, string | number> = {}): EmittedLine {
+  const clock = new ScriptedClock();
+  const timeline = new TurnTimeline(clock);
+  for (const [offset, event] of steps) {
+    clock.at(offset);
+    timeline.observe(event);
+  }
+  clock.at(settleAt);
+  const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+  timeline.emit(context);
+  expect(spy).toHaveBeenCalledTimes(1);
+  return JSON.parse(spy.mock.calls[0]![0] as string) as EmittedLine;
+}
+
+function segment(line: EmittedLine, name: string) {
+  const found = line.segments.filter((s) => s.name === name);
+  expect(found, `one segment named ${name}`).toHaveLength(1);
+  return found[0]!;
+}
+
+const START: TranscriptEvent = { kind: "message_start", runId: "r1" };
+const TEXT: TranscriptEvent = { kind: "text_delta", runId: "r1", text: "hi" };
+const THINK: TranscriptEvent = { kind: "reasoning_delta", runId: "r1", text: "hmm" };
+const FINISH: TranscriptEvent = { kind: "message_finish", runId: "r1" };
+const TOOL_START: TranscriptEvent = { kind: "tool_started", callId: "c1", name: "read_file", input: { path: "a" }, mcpServerSlug: "" };
+const TOOL_DONE: TranscriptEvent = { kind: "tool_finished", callId: "c1", result: "ok" };
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("TurnTimeline — the three root instants", () => {
+  it("first_event is the first event of any kind; visible and text follow the first text delta", () => {
+    const line = run([[100, START], [250, TEXT], [400, FINISH]], 500);
+    expect(line.first_event_ms).toBe(100);
+    expect(line.first_visible_token_ms).toBe(250);
+    expect(line.first_text_ms).toBe(250);
+  });
+
+  it("a reasoning delta is visible but not text: thinking on moves the two instants apart", () => {
+    const line = run([[100, START], [180, THINK], [420, TEXT]], 500);
+    expect(line.first_visible_token_ms).toBe(180);
+    expect(line.first_text_ms).toBe(420);
+  });
+
+  it("a sub-agent's tokens set no root instant: the user watches the thread, not the sub-agent's row", () => {
+    const sub: TranscriptEvent[] = [
+      { kind: "sub_agent_started", subAgentId: "s1", name: "researcher", subject: "look", input: "look" },
+      { kind: "message_start", runId: "sr", subAgentId: "s1" },
+      { kind: "text_delta", runId: "sr", text: "reading", subAgentId: "s1" },
+    ];
+    const line = run([[50, sub[0]!], [60, sub[1]!], [70, sub[2]!], [900, TEXT]], 1000);
+    expect(line.first_event_ms).toBe(50);
+    expect(line.first_visible_token_ms).toBe(900);
+    expect(line.first_text_ms).toBe(900);
+  });
+
+  it("an instant that never happened is null, and an empty turn has zero of everything", () => {
+    const line = run([], 300);
+    expect(line.first_event_ms).toBeNull();
+    expect(line.first_visible_token_ms).toBeNull();
+    expect(line.first_text_ms).toBeNull();
+    expect(line.rounds).toBe(0);
+    expect(line.tool_calls).toBe(0);
+    expect(line.sub_agents).toBe(0);
+    expect(line.max_gap_ms).toBeNull();
+    expect(line.segments).toEqual([]);
+    expect(line.total_ms).toBe(0);
+  });
+});
+
+describe("TurnTimeline — one model_round span per runId", () => {
+  it("opens on message_start and closes on message_finish; two runs are two rounds", () => {
+    const line = run([
+      [100, START], [300, FINISH],
+      [350, { kind: "message_start", runId: "r2" }], [700, { kind: "message_finish", runId: "r2" }],
+    ], 800);
+    expect(line.rounds).toBe(2);
+    expect(line.segments.filter((s) => s.name === "model_round").map((s) => [s.start_ms, s.duration_ms])).toEqual([[100, 200], [350, 350]]);
+  });
+
+  it("a re-emitted start for a known run keeps the first start", () => {
+    const line = run([[100, START], [200, START], [300, FINISH]], 400);
+    expect(segment(line, "model_round")).toEqual({ name: "model_round", start_ms: 100, duration_ms: 200 });
+  });
+});
+
+describe("TurnTimeline — one tool span per callId", () => {
+  it("opens on tool_started and closes on the first tool_finished; the name carries the tool", () => {
+    const line = run([[100, TOOL_START], [340, TOOL_DONE]], 400);
+    expect(line.tool_calls).toBe(1);
+    expect(segment(line, "tool:read_file")).toEqual({ name: "tool:read_file", start_ms: 100, duration_ms: 240 });
+  });
+
+  it("an MCP tool's span names its server, so the MCP phase is legible", () => {
+    const start: TranscriptEvent = { kind: "tool_started", callId: "m1", name: "search", input: {}, mcpServerSlug: "github" };
+    const line = run([[100, start], [500, { kind: "tool_finished", callId: "m1", result: "" }]], 600);
+    expect(segment(line, "tool:github/search").duration_ms).toBe(400);
+  });
+
+  it("a tool_error closes the span like a finish", () => {
+    const line = run([[100, TOOL_START], [150, { kind: "tool_error", callId: "c1", message: "boom" }]], 200);
+    expect(segment(line, "tool:read_file").duration_ms).toBe(50);
+  });
+
+  it("a fact carrying observedAt closes the span at the observed instant, not the fold's", () => {
+    // The Cursor shape: the tool finished at +300 on the delta channel, the
+    // fold applies it at +2_800, after the model narrated for 2.5 seconds.
+    const observed: TranscriptEvent = { kind: "tool_finished", callId: "c1", result: "ok", observedAt: observedWall(300) };
+    const line = run([[100, TOOL_START], [2_800, observed]], 3_000);
+    expect(segment(line, "tool:read_file")).toEqual({ name: "tool:read_file", start_ms: 100, duration_ms: 200 });
+  });
+
+  it("an unparseable observedAt falls back to the fold's clock rather than losing the close", () => {
+    const observed: TranscriptEvent = { kind: "tool_finished", callId: "c1", result: "ok", observedAt: "not a date" };
+    const line = run([[100, TOOL_START], [900, observed]], 1_000);
+    expect(segment(line, "tool:read_file").duration_ms).toBe(800);
+  });
+
+  it("a second finish for a settled span changes nothing (Cursor completes every call twice)", () => {
+    const line = run([[100, TOOL_START], [300, TOOL_DONE], [900, TOOL_DONE]], 1_000);
+    expect(segment(line, "tool:read_file").duration_ms).toBe(200);
+    expect(line.tool_calls).toBe(1);
+  });
+
+  it("a finish for a call that never started is ignored", () => {
+    const line = run([[300, TOOL_DONE]], 400);
+    expect(line.tool_calls).toBe(0);
+    expect(line.segments).toEqual([]);
+  });
+
+  it("approval_proposed opens no span: a held call is not a tool phase", () => {
+    const proposed: TranscriptEvent = { kind: "approval_proposed", callId: "g1", name: "shell", mcpServerSlug: "", message: "Run?" };
+    const line = run([[100, proposed]], 200);
+    expect(line.tool_calls).toBe(0);
+    expect(line.first_event_ms, "it is still an event").toBe(100);
+  });
+
+  it("arg and output deltas are events for the gap but open nothing", () => {
+    const line = run([
+      [100, TOOL_START],
+      [150, { kind: "tool_arg_delta", callId: "c1", argsChunk: "{" }],
+      [200, { kind: "tool_output_delta", callId: "c1", delta: "partial" }],
+      [400, TOOL_DONE],
+    ], 500);
+    expect(line.tool_calls).toBe(1);
+    expect(line.segments).toHaveLength(1);
+  });
+});
+
+describe("TurnTimeline — one sub_agent span per subAgentId", () => {
+  it("opens on sub_agent_started, closes on finished or failed, named after the sub-agent", () => {
+    const line = run([
+      [100, { kind: "sub_agent_started", subAgentId: "s1", name: "researcher", subject: "x", input: "x" }],
+      [900, { kind: "sub_agent_finished", subAgentId: "s1", output: "done" }],
+      [950, { kind: "sub_agent_started", subAgentId: "s2", name: "writer", subject: "y", input: "y" }],
+      [1_000, { kind: "sub_agent_failed", subAgentId: "s2", error: "no" }],
+    ], 1_100);
+    expect(line.sub_agents).toBe(2);
+    expect(segment(line, "sub_agent:researcher").duration_ms).toBe(800);
+    expect(segment(line, "sub_agent:writer").duration_ms).toBe(50);
+  });
+});
+
+describe("TurnTimeline — the longest silence", () => {
+  it("max_gap is the largest wait between two consecutive events, of any kind", () => {
+    const line = run([[100, START], [150, TEXT], [1_350, TOOL_START], [1_400, TOOL_DONE]], 1_500);
+    expect(line.max_gap_ms).toBe(1_200);
+  });
+
+  it("is null under two events", () => {
+    expect(run([[100, START]], 200).max_gap_ms).toBeNull();
+  });
+});
+
+describe("TurnTimeline — settle and the line's shape", () => {
+  it("a span still open at settle closes at settle", () => {
+    const line = run([[100, START], [200, TOOL_START]], 1_000);
+    expect(segment(line, "model_round")).toEqual({ name: "model_round", start_ms: 100, duration_ms: 900 });
+    expect(segment(line, "tool:read_file")).toEqual({ name: "tool:read_file", start_ms: 200, duration_ms: 800 });
+    expect(line.total_ms).toBe(1_000);
+  });
+
+  it("segments overlap and come out in start order; total is the latest end, not a sum", () => {
+    const line = run([
+      [100, START],
+      [200, TOOL_START],
+      [300, { kind: "sub_agent_started", subAgentId: "s1", name: "researcher", subject: "x", input: "x" }],
+      [400, TOOL_DONE],
+      [500, FINISH],
+      [600, { kind: "message_start", runId: "r2" }],
+      [700, { kind: "sub_agent_finished", subAgentId: "s1" }],
+      [800, { kind: "message_finish", runId: "r2" }],
+    ], 850);
+    expect(line.segments.map((s) => s.name)).toEqual(["model_round", "tool:read_file", "sub_agent:researcher", "model_round"]);
+    const sum = line.segments.reduce((acc, s) => acc + s.duration_ms, 0);
+    expect(sum).toBeGreaterThan(line.total_ms);
+    expect(line.total_ms).toBe(800);
+  });
+
+  it("writes the turn_phases selector and the runtime's context beside the fold's facts", () => {
+    const line = run([[100, START], [200, TEXT], [300, FINISH]], 400, {
+      execution_id: "exe_1",
+      session_id: "ses_1",
+      turn_seq: 2,
+      harness: "deep-agent",
+      outcome: "completed",
+    });
+    expect(line.stigmer_timing).toBe(TURN_PHASES_EVENT);
+    expect(line.execution_id).toBe("exe_1");
+    expect(line.session_id).toBe("ses_1");
+    expect(line.turn_seq).toBe(2);
+    expect(line.harness).toBe("deep-agent");
+    expect(line.outcome).toBe("completed");
+    expect(Object.keys(line).sort()).toEqual([
+      "execution_id", "first_event_ms", "first_text_ms", "first_visible_token_ms", "harness", "max_gap_ms",
+      "outcome", "rounds", "segments", "session_id", "stigmer_timing", "sub_agents", "tool_calls", "total_ms", "turn_seq",
+    ]);
+  });
+});

package/src/harness/run-turn.ts

@@ -5,8 +5,9 @@
  * What runs here and nowhere else: the activity's identity and its
  * execution-scoped context; the status, the one transcript builder over it
  * (born with the status, seeded by the reinvocation phase, handed to the
- * adapter as `sink.transcript`, finalized once the adapter returns) and the
- * single persist chokepoint;
+ * adapter as `sink.transcript`, finalized once the adapter returns), the turn
+ * timeline folded from that builder's events and written once at settle
+ * (`turn-timeline.ts`), and the single persist chokepoint;
  * the periodic heartbeat; the stop controller and its four producers (the
  * stall watchdog, the cost cap, the platform STOP, Temporal's cancellation);
  * the resolution phases (`turn-context.ts`) composed into the `TurnInput`;
@@ -85,6 +86,7 @@ import {
 } from "./terminal-table.js";
 import { TranscriptBuilder } from "./transcript/builder.js";
 import { resolveTurnContext, type ResolutionDeps, type TurnFrame, type TurnSettlement } from "./turn-context.js";
+import { TurnTimeline } from "./turn-timeline.js";
 import type { HarnessAdapter, TurnInput, TurnSink } from "./types.js";
 import { UsageAccumulator } from "./usage-accumulator.js";
 
@@ -151,20 +153,34 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     startedAt: utcTimestamp(),
   });
 
+  // The turn's origin, read once on both clocks so the two timelines below
+  // and the harness's observed instants (`transcript/events.ts` `Observed`)
+  // all subtract against the same moment.
+  const originMs = performance.now();
+  const originWallMs = Date.now();
+
+  // The turn timeline (`turn-timeline.ts`): the runtime's fold over every
+  // event the adapter folds through the builder, emitted once at settle as
+  // the `turn_phases` line — first visible token, model rounds, tool and
+  // sub-agent spans, the longest silence — for every harness alike.
+  const timeline = new TurnTimeline({ originMs, originWallMs, now: () => performance.now() });
+
   // The one transcript builder of this turn, born with the status and before
   // any phase, so it exists for everything that writes a row or an output
   // onto the status: the write-back coordinator (phase 2c), the seed of a
   // reinvocation's prior rows (phase 3, through `seed()`, which indexes them
   // as it appends), the adapter (`sink.transcript`), and the epilogue. One
   // constructor call per turn; a second builder over the same status would
-  // index the same rows twice.
-  const transcript = new TranscriptBuilder(executionId, status);
+  // index the same rows twice. The timeline is its observer.
+  const transcript = new TranscriptBuilder(executionId, status, (event) => timeline.observe(event));
 
   // Cold-start timeline of this turn's setup: one mark after each phase, the
   // adapter's own segments marked through the sink, emitted by the adapter
   // once its engine is resolved (an early return skips it — partial setups
-  // are not comparable cold-start samples).
-  const setupTiming = new TimingRecorder();
+  // are not comparable cold-start samples). On the turn's origin, so
+  // `turn_phases.first_visible_token_ms - execution_setup.total_ms` is the
+  // wait after the engine was ready, with no join.
+  const setupTiming = new TimingRecorder(originMs);
 
   // Artifact storage for offloading oversized tool outputs out of the
   // persisted status and for publishing the plan artifact. Resolved once so
@@ -366,6 +382,20 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     // finalizes first, as the Cursor harness does before `run.wait()`.
     transcript.finalize();
 
+    // The engine's turn is over: write its timeline, once, on every outcome.
+    // Here and not in the settles, because this is the one place that sees
+    // every path, and before the epilogue, because the epilogue is the
+    // runtime's, not the turn the user watched. A turn that settled during
+    // resolution never reaches here and gets no line: no engine, no phases.
+    // `harness` is the adapter's diagnostic name, the runtime's vocabulary.
+    timeline.emit({
+      execution_id: executionId,
+      session_id: turn.sessionId,
+      turn_seq: input.turnSeq,
+      harness: adapter.name,
+      outcome: outcome.kind,
+    });
+
     // The capture boundary, ONCE, over whatever the whole turn left on the
     // tree — unless a stop fired mid-turn (`interrupted`: the tree may be
     // mid-edit and the pause or drain reinvokes this same turn). Before the

package/src/harness/transcript/__tests__/builder.test.ts

@@ -17,7 +17,9 @@
  * preview, the todo projection, and the rest of the header's rules —
  * the row per id, the message boundary, the thinking row, the sub-agent
  * rows, finalize, artifacts and write-backs, the dirty flag, the error
- * guard — joined commit by commit in the same PR.
+ * guard — joined commit by commit in the same PR. The observer arm (the
+ * runtime's fold-watcher: told after the fold, guarded apart from the
+ * handlers, silent on seed) joined with the turn timeline.
  */
 
 import { describe, it, expect } from "vitest";
@@ -973,3 +975,69 @@ describe("TranscriptBuilder — the dirty flag and the error guard", () => {
     expect(errors[0]).toContain("property access failed");
   });
 });
+
+describe("TranscriptBuilder — the observer sees every folded event, after the fold, and can break nothing", () => {
+  it("is told every applied event, in order, once the fold has landed", () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    const seen: Array<{ kind: string; rowsAtNotify: number }> = [];
+    const sb = new TranscriptBuilder("exec-observe", status, (event) => {
+      seen.push({ kind: event.kind, rowsAtNotify: status.messages.flatMap((m) => m.toolCalls).length });
+    });
+    for (const e of proposedCall()) sb.apply(e);
+    sb.apply({ kind: "tool_finished", callId: "call-1", result: "ok" });
+
+    expect(seen.map((s) => s.kind)).toEqual(["message_start", "text_delta", "message_finish", "tool_started", "tool_finished"]);
+    // "After the fold": when the observer hears tool_started, the row exists.
+    expect(seen[3]!.rowsAtNotify).toBe(1);
+  });
+
+  it("a throwing observer is logged with the execution and the event kind, and the fold stands", () => {
+    const errors: string[] = [];
+    const original = console.error;
+    console.error = (msg: unknown) => { errors.push(String(msg)); };
+    try {
+      const status = create(AgentExecutionStatusSchema, {});
+      const sb = new TranscriptBuilder("exec-observe", status, () => { throw new Error("observer fell over"); });
+      expect(() => { for (const e of proposedCall()) sb.apply(e); }).not.toThrow();
+      expect(rowOf(status, "call-1").status, "the transcript is whole").toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+    } finally {
+      console.error = original;
+    }
+    expect(errors).toHaveLength(4);
+    expect(errors[0]).toContain("exec-observe");
+    expect(errors[0]).toContain("kind=message_start");
+    expect(errors[0]).toContain("observer fell over");
+  });
+
+  it("still hears an event whose handler threw: the two guards are independent", () => {
+    const original = console.error;
+    console.error = () => {};
+    const seen: string[] = [];
+    try {
+      const { status } = feed(builder(), proposedCall());
+      const sb = new TranscriptBuilder("exec-observe", status, (event) => { seen.push(event.kind); });
+      const poisoned = { kind: "tool_finished", callId: "call-1", get result(): string { throw new Error("property access failed"); } } as TranscriptEvent;
+      sb.apply(poisoned);
+    } finally {
+      console.error = original;
+    }
+    expect(seen).toEqual(["tool_finished"]);
+  });
+
+  it("seed() does not notify: a seeded row is last turn's fact, not an event of this turn", () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    const seen: string[] = [];
+    const sb = new TranscriptBuilder("exec-observe", status, (event) => { seen.push(event.kind); });
+    sb.seed(create(AgentExecutionStatusSchema, {
+      messages: [create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "earlier", toolCalls: [create(ToolCallSchema, { id: "old-1", name: "read_file", status: ToolCallStatus.TOOL_CALL_COMPLETED })] })],
+    }));
+    expect(seen).toEqual([]);
+    expect(status.messages).toHaveLength(1);
+  });
+
+  it("is optional: the two-argument constructor folds exactly as before", () => {
+    const { sb, status } = feed(builder(), proposedCall());
+    sb.apply({ kind: "tool_finished", callId: "call-1", result: "ok" });
+    expect(rowOf(status, "call-1").status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+  });
+});