@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/checkpointer/sqlite-saver.ts

@@ -0,0 +1,384 @@
+/**
+ * SQLite-backed LangGraph checkpoint saver — the durable checkpointer for the
+ * OSS / local edition.
+ *
+ * Why this exists: the OSS-local default used to be the ephemeral `MemorySaver`,
+ * recreated empty on every `ExecuteDeepAgent` invocation. The Temporal workflow
+ * re-invokes the activity with the SAME `thread_id` on HITL approval, pause/
+ * resume, and transient recovery — but with an empty checkpointer the graph has
+ * nothing to resume from, so it replays from the original user message instead
+ * of continuing after the interrupt. This saver makes the checkpoint survive
+ * across invocations on a single machine, so those re-invocations resume via
+ * `Command(resume)` exactly like the cloud (`http`) path (see stigmer/stigmer#204).
+ *
+ * Implementation notes:
+ * - Backed by Node's built-in `node:sqlite` (`DatabaseSync`). Zero external
+ *   dependencies and bundles cleanly into the slim artifact — `node:`-prefixed
+ *   builtins stay external to esbuild, unlike a native addon such as
+ *   `better-sqlite3` (which the official `@langchain/langgraph-checkpoint-sqlite`
+ *   depends on and which cannot be bundled).
+ * - Schema and the `put` / `putWrites` conflict-resolution semantics mirror the
+ *   official `@langchain/langgraph-checkpoint-sqlite` saver, so a checkpoint
+ *   written here is byte-compatible with the reference implementation.
+ * - Serialization uses the inherited `JsonPlusSerializer` (`this.serde`), exactly
+ *   like {@link HttpCheckpointSaver}. Serialized payloads are stored as raw BLOBs
+ *   and read back as `Uint8Array`, so binary (msgpack) payloads round-trip
+ *   losslessly — this is why writes are read via a dedicated query rather than
+ *   the reference saver's `CAST(value AS TEXT)` JSON aggregation.
+ * - WAL journaling plus a busy timeout make the file safe to open from more than
+ *   one process at once (the CLI daemon and the desktop runner can share a HOME).
+ */
+
+import { DatabaseSync, type StatementSync, type SQLInputValue } from "node:sqlite";
+import type { RunnableConfig } from "@langchain/core/runnables";
+import {
+  BaseCheckpointSaver,
+  WRITES_IDX_MAP,
+  copyCheckpoint,
+  type ChannelVersions,
+  type Checkpoint,
+  type CheckpointListOptions,
+  type CheckpointMetadata,
+  type CheckpointPendingWrite,
+  type CheckpointTuple,
+  type PendingWrite,
+  type SerializerProtocol,
+} from "@langchain/langgraph-checkpoint";
+
+/** Milliseconds SQLite waits on a locked database before erroring (WAL busy handler). */
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+interface CheckpointColumns {
+  thread_id: string;
+  checkpoint_ns: string;
+  checkpoint_id: string;
+  parent_checkpoint_id: string | null;
+  type: string | null;
+  checkpoint: Uint8Array;
+  metadata: Uint8Array;
+}
+
+interface WriteColumns {
+  task_id: string;
+  channel: string;
+  type: string | null;
+  value: Uint8Array;
+}
+
+export class SqliteCheckpointSaver extends BaseCheckpointSaver {
+  private readonly db: DatabaseSync;
+  private isSetup = false;
+
+  constructor(dbPath: string, serde?: SerializerProtocol) {
+    super(serde);
+    this.db = new DatabaseSync(dbPath, { timeout: DEFAULT_BUSY_TIMEOUT_MS });
+  }
+
+  /**
+   * Create the schema on first use. WAL + the constructor's busy timeout make
+   * concurrent readers/writers (across processes sharing the file) safe. The
+   * tables and their primary keys mirror the official
+   * `@langchain/langgraph-checkpoint-sqlite` schema.
+   */
+  private setup(): void {
+    if (this.isSetup) return;
+
+    this.db.exec("PRAGMA journal_mode=WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS checkpoints (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        parent_checkpoint_id TEXT,
+        type TEXT,
+        checkpoint BLOB,
+        metadata BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+      );
+    `);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS writes (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        channel TEXT NOT NULL,
+        type TEXT,
+        value BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+      );
+    `);
+
+    this.isSetup = true;
+  }
+
+  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+    const checkpointId = config.configurable?.checkpoint_id as string | undefined;
+
+    const row = (checkpointId
+      ? this.db
+          .prepare(
+            `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`,
+          )
+          .get(threadId ?? null, checkpointNs, checkpointId)
+      : this.db
+          .prepare(
+            `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ?
+             ORDER BY checkpoint_id DESC LIMIT 1`,
+          )
+          .get(threadId ?? null, checkpointNs)) as unknown as CheckpointColumns | undefined;
+
+    if (row === undefined) return undefined;
+
+    return this.rowToTuple(row);
+  }
+
+  async *list(
+    config: RunnableConfig,
+    options?: CheckpointListOptions,
+  ): AsyncGenerator<CheckpointTuple> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    const checkpointNs = config.configurable?.checkpoint_ns as string | undefined;
+    const before = options?.before?.configurable?.checkpoint_id as string | undefined;
+    const limit = options?.limit;
+
+    // Supported filter subset mirrors HttpCheckpointSaver (thread_id /
+    // checkpoint_ns / before / limit). The runner's resume path reads via
+    // getState -> getTuple, so metadata filtering is not exercised here.
+    const where: string[] = [];
+    const args: SQLInputValue[] = [];
+    if (threadId !== undefined) {
+      where.push("thread_id = ?");
+      args.push(threadId);
+    }
+    if (checkpointNs !== undefined) {
+      where.push("checkpoint_ns = ?");
+      args.push(checkpointNs);
+    }
+    if (before !== undefined) {
+      where.push("checkpoint_id < ?");
+      args.push(before);
+    }
+
+    let sql =
+      `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+       FROM checkpoints`;
+    if (where.length > 0) sql += ` WHERE ${where.join(" AND ")}`;
+    sql += " ORDER BY checkpoint_id DESC";
+    if (limit !== undefined) sql += ` LIMIT ${parseInt(String(limit), 10)}`;
+
+    const rows = this.db.prepare(sql).all(...args) as unknown as CheckpointColumns[];
+    for (const row of rows) {
+      yield await this.rowToTuple(row);
+    }
+  }
+
+  async put(
+    config: RunnableConfig,
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    _newVersions: ChannelVersions,
+  ): Promise<RunnableConfig> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    if (!threadId) {
+      throw new Error(`Missing "thread_id" field in passed "config.configurable".`);
+    }
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+    const parentCheckpointId = config.configurable?.checkpoint_id as string | undefined;
+
+    // Defensive copy before serialization, matching the reference saver.
+    const [[checkpointType, serializedCheckpoint], [metadataType, serializedMetadata]] =
+      await Promise.all([
+        this.serde.dumpsTyped(copyCheckpoint(checkpoint)),
+        this.serde.dumpsTyped(metadata),
+      ]);
+
+    if (checkpointType !== metadataType) {
+      throw new Error("Failed to serialize checkpoint and metadata to the same type.");
+    }
+
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO checkpoints
+           (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        threadId,
+        checkpointNs,
+        checkpoint.id,
+        parentCheckpointId ?? null,
+        checkpointType,
+        serializedCheckpoint,
+        serializedMetadata,
+      );
+
+    return {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_ns: checkpointNs,
+        checkpoint_id: checkpoint.id,
+      },
+    };
+  }
+
+  async putWrites(
+    config: RunnableConfig,
+    writes: PendingWrite[],
+    taskId: string,
+  ): Promise<void> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    if (!threadId) throw new Error("Missing thread_id field in config.configurable.");
+    const checkpointId = config.configurable?.checkpoint_id as string | undefined;
+    if (!checkpointId) throw new Error("Missing checkpoint_id field in config.configurable.");
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+
+    // Conflict resolution matches the reference saver and the
+    // langgraph-checkpoint contract:
+    // - All-special writes (ERROR / SCHEDULED / INTERRUPT / RESUME, each pinned
+    //   to a negative idx by WRITES_IDX_MAP) REPLACE, so e.g. INTERRUPT can be
+    //   overwritten by RESUME.
+    // - Otherwise IGNORE, so a regular write from one task never clobbers a
+    //   regular write another concurrent task already stored at the same
+    //   (task_id, idx).
+    const allSpecial = writes.every(([channel]) => channel in WRITES_IDX_MAP);
+    const stmt: StatementSync = this.db.prepare(
+      `INSERT ${allSpecial ? "OR REPLACE" : "OR IGNORE"} INTO writes
+         (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    const rows = await Promise.all(
+      writes.map(async ([channel, value], idx) => {
+        const [type, serialized] = await this.serde.dumpsTyped(value);
+        return {
+          // Special channels are stored at fixed negative indices so they never
+          // collide with regular per-step writes (whose idx is the ordinal).
+          idx: WRITES_IDX_MAP[channel] ?? idx,
+          channel,
+          type,
+          value: serialized,
+        };
+      }),
+    );
+
+    this.db.exec("BEGIN");
+    try {
+      for (const row of rows) {
+        stmt.run(
+          threadId,
+          checkpointNs,
+          checkpointId,
+          taskId,
+          row.idx,
+          row.channel,
+          row.type,
+          row.value,
+        );
+      }
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  async deleteThread(threadId: string): Promise<void> {
+    this.setup();
+
+    this.db.exec("BEGIN");
+    try {
+      this.db.prepare("DELETE FROM checkpoints WHERE thread_id = ?").run(threadId);
+      this.db.prepare("DELETE FROM writes WHERE thread_id = ?").run(threadId);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  /** Close the underlying database handle. Idempotent and non-throwing. */
+  close(): void {
+    try {
+      this.db.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  /** Deserialize a checkpoint row and hydrate its pending writes. */
+  private async rowToTuple(row: CheckpointColumns): Promise<CheckpointTuple> {
+    const type = row.type ?? "json";
+    const checkpoint = (await this.serde.loadsTyped(type, row.checkpoint)) as Checkpoint;
+    const metadata = (await this.serde.loadsTyped(type, row.metadata)) as CheckpointMetadata;
+
+    const pendingWrites = await this.loadPendingWrites(
+      row.thread_id,
+      row.checkpoint_ns,
+      row.checkpoint_id,
+    );
+
+    return {
+      config: {
+        configurable: {
+          thread_id: row.thread_id,
+          checkpoint_ns: row.checkpoint_ns,
+          checkpoint_id: row.checkpoint_id,
+        },
+      },
+      checkpoint,
+      metadata,
+      parentConfig: row.parent_checkpoint_id
+        ? {
+            configurable: {
+              thread_id: row.thread_id,
+              checkpoint_ns: row.checkpoint_ns,
+              checkpoint_id: row.parent_checkpoint_id,
+            },
+          }
+        : undefined,
+      pendingWrites,
+    };
+  }
+
+  private async loadPendingWrites(
+    threadId: string,
+    checkpointNs: string,
+    checkpointId: string,
+  ): Promise<CheckpointPendingWrite[]> {
+    const writeRows = this.db
+      .prepare(
+        `SELECT task_id, channel, type, value
+         FROM writes
+         WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+         ORDER BY task_id, idx`,
+      )
+      .all(threadId, checkpointNs, checkpointId) as unknown as WriteColumns[];
+
+    return Promise.all(
+      writeRows.map(
+        async (w) =>
+          [
+            w.task_id,
+            w.channel,
+            await this.serde.loadsTyped(w.type ?? "json", w.value),
+          ] as CheckpointPendingWrite,
+      ),
+    );
+  }
+}

package/src/shared/checkpointer/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Configuration for the checkpointer factory.
+ *
+ * Three backends are supported:
+ * - sqlite: durable local file (OSS / local / desktop default) — survives across
+ *   ExecuteDeepAgent invocations so HITL/pause/transient-recovery truly resume.
+ * - http:   routes through the Stigmer Side-Channel Proxy (cloud / managed).
+ * - memory: ephemeral in-process storage — explicit opt-in, used by tests.
+ *
+ * The http backend's credential is a shared ref, never a string: the saver
+ * reads it per request, so a rotation of the runner's control-plane
+ * credential (a pool claim, a sandbox-token renewal) reaches a checkpoint
+ * written after it — including mid-turn, since a saver lives for a whole
+ * turn (config.ts header; the artifact store holds its credential the same
+ * way).
+ */
+
+import type { TokenRef } from "../../config.js";
+
+export interface CheckpointerConfig {
+  readonly type: "memory" | "http" | "sqlite";
+  readonly proxyEndpoint?: string;
+  /** The credential the http saver presents, read per request. Required when type is "http". */
+  readonly authToken?: Readonly<TokenRef>;
+  /** Absolute path to the SQLite database file. Required when type is "sqlite". */
+  readonly sqlitePath?: string;
+}

package/src/shared/cold-start-timing.ts

@@ -0,0 +1,260 @@
+/**
+ * Cold-start timing instrumentation.
+ *
+ * Measures the two previously unmeasured segments of the user-perceived cold
+ * start: the runner PROCESS BOOT (Node start →
+ * worker polling its Temporal queue) and PER-EXECUTION SETUP (activity start →
+ * agent ready to stream), broken down by named phase.
+ *
+ * Emission is a single structured JSON log line per timeline (selector field
+ * `stigmer_timing`), joined to control-plane timestamps by `execution_id`.
+ * Deliberately logs, not proto/status payloads: the status-update path is
+ * size-guarded and UI-coupled, and Temporal history must never carry
+ * telemetry. Cluster logging picks these lines up as-is.
+ *
+ * Failure posture: instrumentation must never affect an execution. All
+ * emission is wrapped; recorders are plain arithmetic and cannot throw in
+ * practice, but callers still treat every function here as best-effort.
+ */
+
+// Static on purpose: the registry module is itself lazy (it dynamic-imports
+// @opentelemetry/api inside getInstruments), so this adds nothing to boot,
+// while per-call dynamic imports raced under concurrent emissions.
+import { getInstruments } from "../otel-metrics.js";
+
+/** One closed segment on a timeline: [startMs, startMs + durationMs). */
+export interface TimingSegment {
+  readonly name: string;
+  /** Offset from the recorder's origin when this segment began (ms). */
+  readonly startMs: number;
+  readonly durationMs: number;
+}
+
+/**
+ * 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
+ * measures, mirroring the existing `reportSetupProgress` phase idiom:
+ *
+ * ```ts
+ * const timing = new TimingRecorder();
+ * 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 {
+  private readonly originMs: number;
+  private readonly segments: TimingSegment[] = [];
+  private lastMarkMs: number;
+  /** Absolute end of the segment that ends latest, by either idiom. */
+  private latestEndMs: number;
+
+  /**
+   * @param originMs absolute `performance.now()`-scale origin. Defaults to
+   *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
+   *   whose offsets are milliseconds since Node start (`performance.now()`
+   *   is measured from `performance.timeOrigin`, i.e. process start).
+   */
+  constructor(originMs: number = 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: string): void {
+    const now = performance.now();
+    this.segments.push({
+      name,
+      startMs: round1(this.lastMarkMs - this.originMs),
+      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: string, startMs: number, endMs: number): void {
+    this.segments.push({
+      name,
+      startMs: round1(startMs - this.originMs),
+      durationMs: round1(endMs - startMs),
+    });
+    if (endMs > this.latestEndMs) this.latestEndMs = endMs;
+  }
+
+  /** Elapsed time from the origin to the latest end on the timeline (ms). */
+  totalMs(): number {
+    return round1(this.latestEndMs - this.originMs);
+  }
+
+  snapshot(): readonly TimingSegment[] {
+    return this.segments;
+  }
+
+  /**
+   * This timeline as plain data that another process can continue: the
+   * agent host marks the engine's setup segments on the timeline the turn
+   * runtime began (`agent-host/codec.ts`). `performance.now()` is measured
+   * from each process's own start, so the three cursors cross on the wall
+   * clock (`performance.timeOrigin`-anchored) and {@link fromWire} rebases
+   * them onto the receiving process's scale; the segments are already
+   * offsets from the origin and cross unchanged.
+   */
+  toWire(): TimingRecorderWire {
+    const wall = (ms: number): number => performance.timeOrigin + ms;
+    return {
+      originWallMs: wall(this.originMs),
+      lastMarkWallMs: wall(this.lastMarkMs),
+      latestEndWallMs: wall(this.latestEndMs),
+      segments: [...this.segments],
+    };
+  }
+
+  /** The timeline {@link toWire} described, on this process's `performance.now()` scale. */
+  static fromWire(wire: TimingRecorderWire): TimingRecorder {
+    const local = (wallMs: number): number => wallMs - performance.timeOrigin;
+    const recorder = new TimingRecorder(local(wire.originWallMs));
+    recorder.segments.push(...wire.segments);
+    recorder.lastMarkMs = local(wire.lastMarkWallMs);
+    recorder.latestEndMs = local(wire.latestEndWallMs);
+    return recorder;
+  }
+}
+
+/** A {@link TimingRecorder} as plain data: its cursors on the wall clock and its closed segments. */
+export interface TimingRecorderWire {
+  readonly originWallMs: number;
+  readonly lastMarkWallMs: number;
+  readonly latestEndWallMs: number;
+  readonly segments: readonly TimingSegment[];
+}
+
+/**
+ * Emit one timeline as a single structured log line.
+ *
+ * Shape (stable — the baseline report and log-based metrics query it):
+ * `{"stigmer_timing":"<event>", ...context, "total_ms":N, "segments":[{"name","start_ms","duration_ms"}]}`
+ *
+ * Each timeline's total is additionally mirrored onto its OTel histogram
+ * (see {@link recordTimingMetric}): the stdout line stays the source of
+ * truth for per-segment forensics (it is the only place segments exist —
+ * cluster workload logs are not ingested anywhere queryable), while the
+ * histogram gives dashboards the aggregate without scraping pods.
+ */
+export function emitTimingLog(
+  event: string,
+  context: Record<string, string | number | boolean | null | undefined>,
+  recorder: TimingRecorder,
+): void {
+  try {
+    console.log(JSON.stringify({
+      stigmer_timing: event,
+      ...context,
+      total_ms: recorder.totalMs(),
+      segments: recorder.snapshot().map((s) => ({
+        name: s.name,
+        start_ms: s.startMs,
+        duration_ms: s.durationMs,
+      })),
+    }));
+  } catch {
+    // Telemetry must never break the runner.
+  }
+  recordTimingMetric(event, context, recorder.totalMs());
+}
+
+/**
+ * Mirror a timeline's total onto its OTel histogram, fire-and-forget.
+ *
+ * Attributes are a per-event WHITELIST (`mode`, `harness`) — never ids or
+ * per-pod values. Unbounded attribute values multiply time series without
+ * limit (the JVM JFR thread_name incident, 2026-07-29: 5k+ series in
+ * 15 minutes), so new attributes here require the same closed-set argument
+ * these two carry. Events without a mapped instrument are control-plane
+ * timelines or future additions and are deliberately not recorded.
+ *
+ * Exported for tests; production callers go through {@link emitTimingLog}.
+ */
+export function recordTimingMetric(
+  event: string,
+  context: Record<string, string | number | boolean | null | undefined>,
+  totalMs: number,
+): void {
+  void (async () => {
+    const instruments = await getInstruments();
+    switch (event) {
+      case "runner_boot":
+        instruments.runnerBootDuration.record(totalMs, pickAttrs(context, "mode"));
+        break;
+      case "execution_setup":
+        instruments.executionSetupDuration.record(totalMs, pickAttrs(context, "harness"));
+        break;
+      case "pool_attach":
+        instruments.poolAttachDuration.record(totalMs);
+        break;
+      default:
+        break;
+    }
+  })().catch(() => {
+    // Telemetry must never break the runner.
+  });
+}
+
+/** Copy only the whitelisted string-valued keys into metric attributes. */
+function pickAttrs(
+  context: Record<string, string | number | boolean | null | undefined>,
+  ...keys: string[]
+): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const key of keys) {
+    const value = context[key];
+    if (typeof value === "string" && value.length > 0) {
+      attrs[key] = value;
+    }
+  }
+  return attrs;
+}
+
+// ─── Process boot timeline ───────────────────────────────────────────────────
+
+// Origin 0 = process start, so the implicit first segment (everything before
+// the first markBoot call) covers Node startup + entrypoint module loading.
+const bootRecorder = new TimingRecorder(0);
+let bootEmitted = false;
+
+/** Record a boot milestone (closes the span since the previous milestone). */
+export function markBoot(name: string): void {
+  if (bootEmitted) return;
+  bootRecorder.mark(name);
+}
+
+/**
+ * Emit the boot timeline once — called when the worker starts polling, the
+ * moment the sandbox can actually receive work. Later calls are no-ops so
+ * worker restarts within one process never emit a bogus second timeline.
+ */
+export function emitRunnerBootTiming(
+  context: Record<string, string | number | boolean | null | undefined>,
+): void {
+  if (bootEmitted) return;
+  bootEmitted = true;
+  emitTimingLog("runner_boot", context, bootRecorder);
+}
+
+function round1(ms: number): number {
+  return Math.round(ms * 10) / 10;
+}