@stigmer/runner 3.19.0 → 3.20.0

package/dist/harness/turn-timeline.js

@@ -0,0 +1,213 @@
+/**
+ * The turn runtime's timeline of one engine turn, folded from the transcript
+ * events every harness already emits, and written once at settle as the
+ * `turn_phases` `stigmer_timing` line.
+ *
+ * What it answers, for every harness alike and for any harness added later
+ * without a line in an adapter: when the user first saw something happen,
+ * how many model rounds and tool calls the turn took, where the sub-agents
+ * ran, and where the turn's longest silence was. It is the per-turn,
+ * CLIENT-PERCEIVED measurement from the runner's vantage, from the turn's
+ * origin (the activity's start, the same origin `execution_setup` counts
+ * from, so the two lines subtract without a join) to the adapter's return;
+ * the completion epilogue and the terminal persist that follow are the
+ * client's own end-to-end, read at `subscribe`. Its counterpart is the cloud
+ * proxy's `ProxyTiming` (`agentexecution/v1/usage.proto`): per model CALL,
+ * server-side, what the provider did. Neither restates the other; a report
+ * that wants both joins them by `execution_id`.
+ *
+ * Why a fold over the transcript events and not a mark in each adapter: the
+ * transcript builder (`transcript/builder.ts`) is the one view the runtime
+ * has of every harness's turn — model rounds, text, tools, sub-agents all
+ * reach it as a translator's output on one union — so a fold over it is
+ * written once and holds for the Cursor adapter, the native adapter and the
+ * next one. `UsageAccumulator` (`usage-accumulator.ts`) is the same shape
+ * for the usage deltas; this is that shape for the events.
+ *
+ * The fold's rules, each with an arm in `__tests__/turn-timeline.test.ts`:
+ *
+ *   - Three instants, ROOT scope only (a sub-agent's text is not what the
+ *     user is watching): `first_event_ms`, the first event of any kind;
+ *     `first_visible_token_ms`, the first `text_delta` or `reasoning_delta`
+ *     (both stream into the console as tokens); `first_text_ms`, the first
+ *     `text_delta`. The two token instants are the cross-harness axes: with
+ *     extended thinking on, the visible instant moves earlier and the text
+ *     instant later, and a comparison needs both. `first_event_ms` is
+ *     harness-relative — on native the first event is `message_start`, the
+ *     model stream opening; on Cursor it is whatever the SDK delivered first —
+ *     and is kept as a forensic (engine-ready to first model event), never as
+ *     an axis. An instant that never happened is `null`.
+ *   - One `model_round` span per `runId`, `message_start` to `message_finish`.
+ *     What a `runId` is belongs to the translator: LangGraph's LLM-call run on
+ *     native, one model round; a minted segment `<run>:<n>` on Cursor, a
+ *     stretch of assistant output between tool calls, which the SDK does not
+ *     let us tell apart from a provider round. The line's `rounds` reads the
+ *     same way.
+ *   - One `tool:<name>` span per `callId` (`tool:<slug>/<name>` for an MCP
+ *     tool, so the MCP phase the runner skill's law asks for is legible),
+ *     `tool_started` to the FIRST `tool_finished` or `tool_error`; a later
+ *     fact for a settled span changes nothing, the builder's own upsert rule
+ *     (Cursor completes every call twice). `approval_proposed` opens nothing:
+ *     a call the engine held before it ran is not a tool phase.
+ *   - One `sub_agent:<name>` span per `subAgentId`, opened by
+ *     `sub_agent_started`, closed by `finished` or `failed`.
+ *   - A fact that carries `observedAt` is placed at that instant, everything
+ *     else at the fold's clock — the builder's rule for `completedAt`
+ *     (`transcript/events.ts`, `Observed`), restated here because the
+ *     alternative repeats the error #1097 fixed, for tool phases and on Cursor
+ *     alone: a completion the SDK's delta channel reported is folded one
+ *     stream event later, seconds while the model narrates, and a comparison
+ *     that read the fold's clock would charge those seconds to Cursor's tools.
+ *     Placing an observed instant needs a wall-clock origin beside the
+ *     `performance.now()` one; the runtime captures both together.
+ *   - `max_gap_ms`, the longest wait between two consecutive events, whatever
+ *     their kind: the turn's longest silence as the user experienced it.
+ *     `null` under two events.
+ *   - A span still open at settle closes at settle: an interrupted turn's
+ *     spans end where the turn did.
+ *
+ * The line: `emitTimingLog("turn_phases", context, recorder)` over a
+ * `TimingRecorder` on the turn's origin, every span appended in start order
+ * through `span()`. This is the first `stigmer_timing` event whose segments
+ * OVERLAP (a tool inside a round, a sub-agent across rounds); the recorder's
+ * `total_ms` is the latest end, not a sum, and a reader that summed the
+ * other timelines' segments must not sum this one's. No histogram mirrors it
+ * yet: the benchmark report is its reader and reads the log; an aggregate
+ * earns its instrument when a dashboard asks.
+ *
+ * Failure posture, the timing module's: the fold is arithmetic over the
+ * event and cannot affect a turn; `emit` is best-effort through
+ * `emitTimingLog`. Nothing here is persisted, and nothing branches on it.
+ */
+import { TimingRecorder, emitTimingLog } from "../shared/cold-start-timing.js";
+/** The `stigmer_timing` selector of the line this module emits. */
+export const TURN_PHASES_EVENT = "turn_phases";
+export class TurnTimeline {
+    clock;
+    firstEventMs;
+    firstVisibleTokenMs;
+    firstTextMs;
+    lastEventMs;
+    maxGapMs;
+    rounds = new Map();
+    tools = new Map();
+    subAgents = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    /** The builder's observer: place one folded event on the timeline. */
+    observe(event) {
+        const at = this.clock.now();
+        this.noteEvent(at);
+        // Root scope only: a sub-agent's tokens stream into its own row, not the
+        // thread the user is watching.
+        if ((event.kind === "text_delta" || event.kind === "reasoning_delta") && event.subAgentId === undefined) {
+            this.firstVisibleTokenMs ??= at;
+            if (event.kind === "text_delta")
+                this.firstTextMs ??= at;
+        }
+        switch (event.kind) {
+            case "message_start":
+                this.open(this.rounds, event.runId, "model_round", at);
+                return;
+            case "message_finish":
+                this.close(this.rounds, event.runId, at);
+                return;
+            case "tool_started":
+                this.open(this.tools, event.callId, toolSpanName(event.name, event.mcpServerSlug), at);
+                return;
+            case "tool_finished":
+            case "tool_error":
+                this.close(this.tools, event.callId, this.placeObserved(event.observedAt, at));
+                return;
+            case "sub_agent_started":
+                this.open(this.subAgents, event.subAgentId, `sub_agent:${event.name}`, at);
+                return;
+            case "sub_agent_finished":
+            case "sub_agent_failed":
+                this.close(this.subAgents, event.subAgentId, at);
+                return;
+            case "text_delta":
+            case "reasoning_delta":
+            case "tool_arg_delta":
+            case "tool_output_delta":
+            case "approval_proposed":
+            case "system_note":
+                return;
+            default: {
+                const exhaustive = event;
+                throw new Error(`unknown transcript event ${String(exhaustive.kind)}`);
+            }
+        }
+    }
+    /**
+     * Write the line, once, at settle. Spans still open close now; the
+     * runtime's context (`execution_id`, `session_id`, `turn_seq`, `harness`,
+     * `outcome`) rides beside the fold's facts.
+     */
+    emit(context) {
+        const settledAt = this.clock.now();
+        const recorder = new TimingRecorder(this.clock.originMs);
+        const spans = [...this.rounds.values(), ...this.tools.values(), ...this.subAgents.values()]
+            .sort((a, b) => a.startMs - b.startMs);
+        for (const span of spans) {
+            recorder.span(span.name, span.startMs, span.endMs ?? settledAt);
+        }
+        emitTimingLog(TURN_PHASES_EVENT, {
+            ...context,
+            first_event_ms: this.offset(this.firstEventMs),
+            first_visible_token_ms: this.offset(this.firstVisibleTokenMs),
+            first_text_ms: this.offset(this.firstTextMs),
+            rounds: this.rounds.size,
+            tool_calls: this.tools.size,
+            sub_agents: this.subAgents.size,
+            max_gap_ms: this.maxGapMs === undefined ? null : round1(this.maxGapMs),
+        }, recorder);
+    }
+    noteEvent(at) {
+        this.firstEventMs ??= at;
+        if (this.lastEventMs !== undefined) {
+            const gap = at - this.lastEventMs;
+            if (this.maxGapMs === undefined || gap > this.maxGapMs)
+                this.maxGapMs = gap;
+        }
+        this.lastEventMs = at;
+    }
+    /** A span per identity: a re-emitted start (a resumed seeded call) keeps the first start. */
+    open(spans, id, name, at) {
+        if (spans.has(id))
+            return;
+        spans.set(id, { name, startMs: at, endMs: undefined });
+    }
+    /** The FIRST close settles a span; a later fact for it changes nothing. A close for an unknown id is ignored. */
+    close(spans, id, at) {
+        const span = spans.get(id);
+        if (!span || span.endMs !== undefined)
+            return;
+        span.endMs = at;
+    }
+    /**
+     * Where a fact goes on the `performance.now()` scale: its observed instant
+     * translated through the paired origins when it carries one, else the fold's
+     * clock. An unparseable stamp falls back to the fold's clock rather than
+     * losing the fact.
+     */
+    placeObserved(observedAt, foldAt) {
+        if (observedAt === undefined)
+            return foldAt;
+        const wallMs = Date.parse(observedAt);
+        if (Number.isNaN(wallMs))
+            return foldAt;
+        return this.clock.originMs + (wallMs - this.clock.originWallMs);
+    }
+    offset(absoluteMs) {
+        return absoluteMs === undefined ? null : round1(absoluteMs - this.clock.originMs);
+    }
+}
+function toolSpanName(name, mcpServerSlug) {
+    return mcpServerSlug ? `tool:${mcpServerSlug}/${name}` : `tool:${name}`;
+}
+function round1(ms) {
+    return Math.round(ms * 10) / 10;
+}
+//# sourceMappingURL=turn-timeline.js.map

package/dist/harness/turn-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-timeline.js","sourceRoot":"","sources":["../../src/harness/turn-timeline.ts"],"names":[],"mappings":"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"}

package/dist/shared/cold-start-timing.d.ts

@@ -24,7 +24,7 @@ export interface TimingSegment {
     readonly durationMs: number;
 }
 /**
- * Records a linear sequence of named segments.
+ * Records named segments on one timeline, two ways.
  *
  * `mark(name)` closes the span from the previous mark (or the origin) and
  * names it — so instrumentation reads as one line placed AFTER the work it
@@ -35,11 +35,22 @@ export interface TimingSegment {
  * const execution = await client.getExecution(executionId);
  * timing.mark("fetch_execution");
  * ```
+ *
+ * `span(name, startMs, endMs)` records a segment with explicit bounds, for a
+ * timeline whose phases OVERLAP (a tool call inside a model round, a
+ * sub-agent across two rounds) and so cannot be written as a chain of marks.
+ * A span never moves the mark cursor: a `mark` after a `span` still measures
+ * from the previous MARK, so the two idioms compose on one recorder without
+ * either changing what the other means. `totalMs()` is the latest end on the
+ * timeline, whichever way it was recorded — for a mark-only recorder that is
+ * the last mark, as it always was.
  */
 export declare class TimingRecorder {
     private readonly originMs;
     private readonly segments;
     private lastMarkMs;
+    /** Absolute end of the segment that ends latest, by either idiom. */
+    private latestEndMs;
     /**
      * @param originMs absolute `performance.now()`-scale origin. Defaults to
      *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
@@ -49,7 +60,12 @@ export declare class TimingRecorder {
     constructor(originMs?: number);
     /** Close the span since the previous mark (or origin) and name it. */
     mark(name: string): void;
-    /** Total elapsed time from the origin to the latest mark (ms). */
+    /**
+     * Record a segment with explicit absolute bounds (`performance.now()`
+     * scale, like the origin). Leaves the mark cursor where it was.
+     */
+    span(name: string, startMs: number, endMs: number): void;
+    /** Elapsed time from the origin to the latest end on the timeline (ms). */
     totalMs(): number;
     snapshot(): readonly TimingSegment[];
 }

package/dist/shared/cold-start-timing.js

@@ -21,7 +21,7 @@
 // while per-call dynamic imports raced under concurrent emissions.
 import { getInstruments } from "../otel-metrics.js";
 /**
- * Records a linear sequence of named segments.
+ * Records named segments on one timeline, two ways.
  *
  * `mark(name)` closes the span from the previous mark (or the origin) and
  * names it — so instrumentation reads as one line placed AFTER the work it
@@ -32,11 +32,22 @@ import { getInstruments } from "../otel-metrics.js";
  * const execution = await client.getExecution(executionId);
  * timing.mark("fetch_execution");
  * ```
+ *
+ * `span(name, startMs, endMs)` records a segment with explicit bounds, for a
+ * timeline whose phases OVERLAP (a tool call inside a model round, a
+ * sub-agent across two rounds) and so cannot be written as a chain of marks.
+ * A span never moves the mark cursor: a `mark` after a `span` still measures
+ * from the previous MARK, so the two idioms compose on one recorder without
+ * either changing what the other means. `totalMs()` is the latest end on the
+ * timeline, whichever way it was recorded — for a mark-only recorder that is
+ * the last mark, as it always was.
  */
 export class TimingRecorder {
     originMs;
     segments = [];
     lastMarkMs;
+    /** Absolute end of the segment that ends latest, by either idiom. */
+    latestEndMs;
     /**
      * @param originMs absolute `performance.now()`-scale origin. Defaults to
      *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
@@ -46,6 +57,7 @@ export class TimingRecorder {
     constructor(originMs = performance.now()) {
         this.originMs = originMs;
         this.lastMarkMs = originMs;
+        this.latestEndMs = originMs;
     }
     /** Close the span since the previous mark (or origin) and name it. */
     mark(name) {
@@ -56,10 +68,25 @@ export class TimingRecorder {
             durationMs: round1(now - this.lastMarkMs),
         });
         this.lastMarkMs = now;
+        if (now > this.latestEndMs)
+            this.latestEndMs = now;
+    }
+    /**
+     * Record a segment with explicit absolute bounds (`performance.now()`
+     * scale, like the origin). Leaves the mark cursor where it was.
+     */
+    span(name, startMs, endMs) {
+        this.segments.push({
+            name,
+            startMs: round1(startMs - this.originMs),
+            durationMs: round1(endMs - startMs),
+        });
+        if (endMs > this.latestEndMs)
+            this.latestEndMs = endMs;
     }
-    /** Total elapsed time from the origin to the latest mark (ms). */
+    /** Elapsed time from the origin to the latest end on the timeline (ms). */
     totalMs() {
-        return round1(this.lastMarkMs - this.originMs);
+        return round1(this.latestEndMs - this.originMs);
     }
     snapshot() {
         return this.segments;

package/dist/shared/cold-start-timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"cold-start-timing.js","sourceRoot":"","sources":["../../src/shared/cold-start-timing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cold-start-timing.js","sourceRoot":"","sources":["../../src/shared/cold-start-timing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -104,10 +104,10 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/outbound": "3.19.0",
-    "@stigmer/protos": "3.19.0",
-    "@stigmer/temporal-codecs": "3.19.0",
-    "@stigmer/zip-structure": "3.19.0",
+    "@stigmer/outbound": "3.20.0",
+    "@stigmer/protos": "3.20.0",
+    "@stigmer/temporal-codecs": "3.20.0",
+    "@stigmer/zip-structure": "3.20.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/common": "1.16.2",
     "@temporalio/interceptors-opentelemetry": "1.16.2",

package/src/__test-utils__/timing-lines.ts

@@ -0,0 +1,43 @@
+/**
+ * Reads the `stigmer_timing` lines a test subject writes to `console.log`
+ * while it runs, parsed, so a test can assert on a timeline the way the
+ * cluster's log reader will (`shared/cold-start-timing.ts`: the stdout line
+ * is the only place a timeline's segments exist).
+ *
+ * One helper for every suite that asserts on an emitted timeline (the
+ * runtime's `run-turn.test.ts`, each adapter's hermetic `turn-phases` proof),
+ * so the way a line is recognised — the selector as the FIRST key, the way
+ * `emitTimingLog` writes it — is decided once. Other log lines pass through
+ * to the real console untouched; nothing here silences the run.
+ */
+
+/** One parsed timeline line: the selector, `total_ms`, `segments`, and whatever context the emitter added. */
+export interface TimingLine {
+  readonly stigmer_timing: string;
+  readonly total_ms: number;
+  readonly segments: ReadonlyArray<{ readonly name: string; readonly start_ms: number; readonly duration_ms: number }>;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Run `act` with `console.log` observed; return every `stigmer_timing` line
+ * whose selector is `event`, in the order they were written.
+ */
+export async function captureTimingLines(event: string, act: () => Promise<void>): Promise<TimingLine[]> {
+  const prefix = `{"stigmer_timing":${JSON.stringify(event)}`;
+  const lines: TimingLine[] = [];
+  const original = console.log;
+  console.log = (...args: unknown[]): void => {
+    const first = args[0];
+    if (typeof first === "string" && first.startsWith(prefix)) {
+      lines.push(JSON.parse(first) as TimingLine);
+    }
+    original(...args);
+  };
+  try {
+    await act();
+  } finally {
+    console.log = original;
+  }
+  return lines;
+}

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

@@ -0,0 +1,136 @@
+/**
+ * Hermetic proof: the Cursor harness gets the runtime's `turn_phases` timing
+ * line without a line of its own.
+ *
+ * Invariant pinned: driving the scripted Cursor SDK through the real Cursor
+ * 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 minted segment (two here: the text before the tool call and the
+ * text after it; the SDK's one `run_id` per `send()` is cut at every tool
+ * call, `translator.ts`), one tool span for the `read` call closed at the
+ * instant the SDK reported, 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 Cursor translator emits the events the
+ * fold needs, in the order it needs them, from the SDK's own stream shape.
+ *
+ * This line is the runtime's; the adapter's own `turn_first_event` line
+ * (`turn-settle.ts`) measures the SDK's `send()` window, which the runtime
+ * cannot see, and is not asserted here.
+ *
+ * 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 { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+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 { 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 { ScriptedCursorAgent, sdkEvents, step } from "../../__test-utils__/scripted-agent.js";
+import {
+  FIXTURE,
+  SDK_CATALOG,
+  beginCursorScenario,
+  cursorExecutionRecord,
+  runCursorTurn,
+} from "../../__test-utils__/hermetic-cursor.js";
+
+const AGENT_ID = "agent-hermetic-tool-0001";
+const RUN_ID = "run-hermetic-tool-0001";
+const CALL_ID = "call-hermetic-read-0001";
+const USER_MESSAGE = "What is in README.md?";
+const READ_ARGS = { path: "README.md" };
+const READ_RESULT = "# Hermetic\n\nA fixture readme.\n";
+const ASSISTANT_TEXT = "README.md holds a one-line fixture description.";
+
+describe("ExecuteCursor 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 segments and tool spans", 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("Let me read it.")),
+          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, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+          step.finished({ result: ASSISTANT_TEXT, model: { id: FIXTURE.model, params: [] } }),
+        ],
+      ],
+    });
+    const record = cursorExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginCursorScenario({
+      env,
+      clock,
+      record,
+      sdk: { agents: [agent], catalog: SDK_CATALOG },
+    });
+
+    const lines = await captureTimingLines(TURN_PHASES_EVENT, async () => {
+      const invocation = await runCursorTurn(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").toBe("cursor");
+    expect(line.outcome).toBe("completed");
+    expect(line.execution_id).toBe(record.execution.metadata!.id);
+    expect(line.turn_seq).toBeTypeOf("number");
+
+    expect(line.rounds, "the segment before the tool call and the one after it").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);
+    const toolSpan = line.segments.filter((s) => s.name === "tool:read");
+    expect(toolSpan).toHaveLength(1);
+    expect(toolSpan[0]!.duration_ms, "a span, not a point: the SDK's running and completed instants differ").toBeGreaterThan(0);
+
+    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/activities/execute-cursor/turn-settle.ts

@@ -122,7 +122,10 @@ export async function streamAndSettle(frame: CursorTurnFrame): Promise<TurnOutco
   // `send_returned` covers the send() call itself, `first_delta` the wait
   // until the SDK's first delta. Primary send only — the recovery retries
   // below rebuild the agent and would skew the user-perceived turn start
-  // this measures. No delta (immediate pause/failure) → no line.
+  // this measures. No delta (immediate pause/failure) → no line. This line is
+  // the SDK's send window and nothing else: the cross-harness instants (first
+  // visible token, rounds, tool spans) are the runtime's `turn_phases` line
+  // (`harness/turn-timeline.ts`), written for every harness alike.
   const turnStartTiming = new TimingRecorder();
   let turnFirstEventEmitted = false;
   const primaryOnDelta = makeCursorTurnOnDelta(onDeltaDeps);