@foldrun/core 1.4.2 → 2.1.0

package/src/history.ts

@@ -15,28 +15,29 @@
 // git repository — and when one is connected later, its commits slot into
 // the same series.
 //
-// No git binary, no working copy, no repository on the server. The platform
-// image deliberately has none (deploy.ts explains why); this is a journal of
-// content, which is all the questions above need. Connecting a repository
-// is a separate step and pushes THIS history out, not the other way round.
+// No git. This is a journal of content plus a snapshot of the whole tree at
+// every revision — the platform's own deploy history, the way Vercel and
+// Cloudflare keep theirs: rollback and restore point back to a snapshot and
+// never need a repository. A customer's code history belongs in their own
+// GitHub or GitLab, connected later, and is a separate thing. (Until 17 Oct
+// 2026 this preferred a bare git repository per workspace whenever a git
+// binary existed; that git is gone, and history started fresh from a
+// baseline snapshot.)
 //
-// Storage: <data>/<tenant>/.history/<scope>/<id>.json, one file per revision,
-// plus index.jsonl — one line each, newest last — so listing does not open
-// every revision. Content is stored inline: the files are small, and a
-// content-addressed store would be machinery in search of a problem.
+// Storage, under <data>/<tenant>/.history/<scope>/:
+//   <id>.json      one revision: what changed, from what, to what (inline,
+//                  clipped at 256 KB — what the history page diffs)
+//   index.jsonl    one line per revision, newest last, so listing opens none
+//   trees/<id>.json  the whole tree right after it: { path: sha256 }
+//   blobs/<aa>/<sha256>  each version of a file, once — content-addressed,
+//                  because a snapshot per save is mostly files that did not
+//                  change, and storing them again would be the whole tree
+//                  per save.
 
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { dataRoot } from "./paths.ts";
-import {
-  commitChanges,
-  gitAvailable,
-  headSha,
-  listCommits,
-  readCommit,
-  repoExists,
-} from "./gitrepo.ts";
 
 /**
  * The current tree of a scope, so the first commit can be a full import.
@@ -54,30 +55,6 @@ export function registerTreeReader(fn: TreeReader) {
   readTree = (tenant, scope) => fn(tenant, scope) ?? prev(tenant, scope);
 }
 
-/** Something to do after a commit lands on main — the mirror push. Registered
- *  by mirror.ts; this module cannot import it (secrets, settings). */
-type AfterCommit = (tenant: string, scope: string, sha: string) => void;
-const afterCommit: AfterCommit[] = [];
-export function registerAfterCommit(fn: AfterCommit) {
-  afterCommit.push(fn);
-}
-export function notifyCommit(tenant: string, scope: string, sha: string) {
-  for (const fn of afterCommit) {
-    try {
-      fn(tenant, scope, sha);
-    } catch {
-      // a mirror that fails must not fail the save that triggered it
-    }
-  }
-}
-
-/** Journal or git? Git whenever the binary exists; the journal is the
- *  fallback for an install without one. An install that started on the
- *  journal keeps it readable — both are consulted on read. */
-const useGit = () => process.env.FOLDRUN_HISTORY !== "journal" && gitAvailable();
-
-// Not store's assertSafeName: store imports this module, and a cycle between
-// the two is avoidable for one regex.
 function assertSafeName(v: string, what: string) {
   if (!/^[A-Za-z0-9][A-Za-z0-9._@-]{0,120}$/.test(v)) throw new Error(`illegal ${what}: ${v}`);
 }
@@ -142,37 +119,6 @@ export function recordRevision(
   const changed = files.filter((f) => f.before !== f.after);
   if (changed.length === 0) return null;
 
-  if (useGit()) {
-    // First commit ever for this scope: import the whole tree as it stands
-    // now (the writer has already written), so the repository is complete
-    // from its first commit rather than starting with one file.
-    const first = !headSha(tenant, scope);
-    // Generated bundle files (knowledge/index.md, memory/log.md) are rewritten
-    // by the same save that changed a concept, outside this call. Commit them
-    // as they now stand, or a clone's index disagrees with its own files —
-    // the exact drift the template tests exist to catch.
-    const generated = first
-      ? []
-      : (readTree(tenant, scope) ?? []).filter((f) => /(^|\/)(knowledge|memory)\/(.*\/)?(index|log)\.md$/.test(f.path));
-    const toCommit = first ? (readTree(tenant, scope) ?? changed) : [...changed, ...generated];
-    const sha = commitChanges(tenant, scope, toCommit, {
-      by: meta.by,
-      // Named after what the caller changed, not the generated files that
-      // rode along — "edited knowledge/style.md", not "changed 3 files".
-      message: first ? `initial import${meta.message ? ` — ${meta.message}` : ""}` : (meta.message ?? describe(changed)),
-    });
-    if (!sha) return null;
-    notifyCommit(tenant, scope, sha);
-    return {
-      id: meta.commit ?? sha,
-      at: new Date().toISOString(),
-      by: meta.by ?? "system",
-      message: meta.message ?? describe(changed),
-      commit: sha,
-      files: changed,
-    };
-  }
-
   const dir = historyDir(tenant, scope);
   fs.mkdirSync(dir, { recursive: true });
   const rev: Revision = {
@@ -197,10 +143,169 @@ export function recordRevision(
     commit: rev.commit,
     paths: rev.files.map((f) => f.path),
   };
+  // The tree as it stands now (the writer has already written), so this
+  // revision can be restored to exactly — including files a save rewrote
+  // outside this call, such as a bundle's generated index.
+  snapshot(tenant, scope, rev.id);
   fs.appendFileSync(path.join(dir, "index.jsonl"), `${JSON.stringify(line)}\n`);
   return rev;
 }
 
+// ----------------------------------------------------------------- snapshots
+
+const sha256 = (s: string) => crypto.createHash("sha256").update(s).digest("hex");
+const treePath = (tenant: string, scope: string, id: string) => path.join(historyDir(tenant, scope), "trees", `${id}.json`);
+const blobPath = (tenant: string, scope: string, sha: string) => path.join(historyDir(tenant, scope), "blobs", sha.slice(0, 2), sha);
+
+/** Write the scope's whole tree as revision `id`'s snapshot. False when there
+ *  is no tree to read (a workspace being deleted).
+ *
+ *  What a snapshot is: the tree as it stood just after this revision was
+ *  written — point in time, which is what a restore wants. A revision's
+ *  diff names only its own change; its snapshot is everything on disk at
+ *  that moment, including another writer's change that landed in between,
+ *  part of one if it was mid-write (saves are not transactional across
+ *  files, and never were). Reviewed with Codex, 17 Oct 2026. */
+function snapshot(tenant: string, scope: string, id: string): boolean {
+  const tree = readTree(tenant, scope);
+  if (!tree) return false;
+  const files: Record<string, string> = {};
+  for (const f of tree) {
+    if (f.after === null) continue;
+    const sha = sha256(f.after);
+    const blob = blobPath(tenant, scope, sha);
+    if (!fs.existsSync(blob)) {
+      fs.mkdirSync(path.dirname(blob), { recursive: true });
+      const tmp = `${blob}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, f.after);
+      fs.renameSync(tmp, blob);
+    }
+    files[f.path] = sha;
+  }
+  const file = treePath(tenant, scope, id);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ v: 1, files }));
+  fs.renameSync(tmp, file);
+  return true;
+}
+
+/** Whether a revision can be restored to: it has a snapshot. */
+export function hasSnapshot(tenant: string, scope: string, id: string): boolean {
+  assertSafeName(id, "revision id");
+  return fs.existsSync(treePath(tenant, scope, id));
+}
+
+/** The whole tree at revision `id`, or null when it has no snapshot. */
+export function snapshotAt(tenant: string, scope: string, id: string): { path: string; content: string }[] | null {
+  assertSafeName(id, "revision id");
+  let manifest: { v: number; files: Record<string, string> };
+  try {
+    manifest = JSON.parse(fs.readFileSync(treePath(tenant, scope, id), "utf8"));
+  } catch {
+    return null;
+  }
+  return Object.entries(manifest.files ?? {})
+    .map(([p, sha]) => ({ path: p, content: fs.readFileSync(blobPath(tenant, scope, sha), "utf8") }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** Every revision of the scope that has a snapshot — one listing, rather
+ *  than a stat per revision. */
+function snapshotIds(tenant: string, scope: string): Set<string> {
+  try {
+    return new Set(fs.readdirSync(path.join(historyDir(tenant, scope), "trees")).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)));
+  } catch {
+    return new Set();
+  }
+}
+
+/** The newest revision that can be restored to — what "now" is in history. */
+export function headRevision(tenant: string, scope: string): RevisionSummary | null {
+  const have = snapshotIds(tenant, scope);
+  return journalRevisions(tenant, scope, { limit: Infinity }).find((r) => have.has(r.id)) ?? null;
+}
+
+/**
+ * A scope with no snapshot yet gets one: its tree as it stands, recorded as
+ * a revision of its own — where its history starts. Every workspace that
+ * existed when history moved off git starts here, and so does one created
+ * by a path that never recorded a change. Returns the head's id, or null
+ * when there is nothing to snapshot.
+ */
+export function ensureBaseline(tenant: string, scope: string, by = "foldrun"): string | null {
+  const head = headRevision(tenant, scope);
+  if (head) return head.id;
+  const tree = readTree(tenant, scope);
+  if (!tree || tree.length === 0) return null;
+  const dir = historyDir(tenant, scope);
+  fs.mkdirSync(dir, { recursive: true });
+  const id = newRevisionId();
+  // One baseline even when the web tier and the worker both find none at
+  // once: whoever creates the marker first writes it, the other reads it.
+  const marker = path.join(dir, ".baseline");
+  try {
+    fs.writeFileSync(marker, id, { flag: "wx" });
+  } catch {
+    const held = headRevision(tenant, scope)?.id ?? null;
+    // A marker with no baseline behind it, minutes old, is a process that
+    // died writing one: clear it, and the next call writes the baseline.
+    try {
+      if (!held && Date.now() - fs.statSync(marker).mtimeMs > 5 * 60_000) fs.rmSync(marker, { force: true });
+    } catch {
+      // gone already
+    }
+    return held;
+  }
+  const rev: Revision = {
+    id,
+    at: new Date().toISOString(),
+    by,
+    message: "history starts here",
+    commit: null,
+    files: [],
+  };
+  fs.writeFileSync(path.join(dir, `${rev.id}.json`), JSON.stringify(rev));
+  if (!snapshot(tenant, scope, rev.id)) return null;
+  const line: RevisionSummary = { id: rev.id, at: rev.at, by: rev.by, message: rev.message, commit: null, paths: [] };
+  fs.appendFileSync(path.join(dir, "index.jsonl"), `${JSON.stringify(line)}\n`);
+  return rev.id;
+}
+
+/**
+ * The revision a restore means: an id (or the commit a deploy recorded), a
+ * date (`2026-10-17`, `2026-10-17T09:00Z`) or a span back from now (`90m`,
+ * `12h`, `3d`, `2w`) — the newest revision with a snapshot at or before that
+ * moment. Null when history holds nothing that old. Throws (status 400) on
+ * something that is none of those.
+ */
+export function resolveRevision(
+  tenant: string,
+  scope: string,
+  to: string,
+  now = Date.now(),
+): { id: string; at: string; by: string; message: string } | null {
+  const t = to.trim();
+  if (!t || t.startsWith("-")) throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
+  const have = snapshotIds(tenant, scope);
+  const all = journalRevisions(tenant, scope, { limit: Infinity }).filter((r) => have.has(r.id));
+  const rel = /^(\d+)\s*(m|h|d|w)$/.exec(t);
+  const moment = rel
+    ? now - Number(rel[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[rel[2] as "m" | "h" | "d" | "w"]
+    : /^\d{4}-\d{2}-\d{2}/.test(t)
+      ? Date.parse(t)
+      : null;
+  let hit: RevisionSummary | undefined;
+  if (moment !== null) {
+    if (Number.isNaN(moment)) throw Object.assign(new Error(`not a date: ${to}`), { status: 400 });
+    hit = all.find((r) => Date.parse(r.at) <= moment);
+  } else {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(t)) throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
+    hit = all.find((r) => r.id === t || r.commit === t || (t.length >= 7 && r.commit?.startsWith(t)));
+  }
+  return hit ? { id: hit.id, at: hit.at, by: hit.by, message: hit.message } : null;
+}
+
 const clip = (s: string | null) =>
   s === null ? null : s.length > MAX_INLINE ? `[${s.length} bytes — too large to keep inline]` : s;
 
@@ -225,12 +330,6 @@ export function listRevisions(
   scope: string,
   opts: { forPath?: string; limit?: number } = {},
 ): RevisionSummary[] {
-  if (useGit() && repoExists(tenant, scope)) {
-    const fromGit = listCommits(tenant, scope, opts);
-    // Anything the journal holds from before the repository existed comes
-    // after git's rows: older, and still worth showing.
-    return [...fromGit, ...journalRevisions(tenant, scope, opts)].slice(0, opts.limit ?? 200);
-  }
   return journalRevisions(tenant, scope, opts);
 }
 
@@ -239,45 +338,68 @@ function journalRevisions(
   scope: string,
   opts: { forPath?: string; limit?: number } = {},
 ): RevisionSummary[] {
-  const file = path.join(historyDir(tenant, scope), "index.jsonl");
-  if (!fs.existsSync(file)) return [];
-  const all = fs
-    .readFileSync(file, "utf8")
-    .split("\n")
-    .filter(Boolean)
-    .flatMap((l) => {
-      try {
-        return [JSON.parse(l) as RevisionSummary];
-      } catch {
-        return []; // a torn line from a crash mid-append loses one entry, not the file
-      }
-    })
-    .reverse();
+  const dir = historyDir(tenant, scope);
+  const file = path.join(dir, "index.jsonl");
+  if (!fs.existsSync(dir)) return [];
+  let all = fs.existsSync(file)
+    ? fs
+        .readFileSync(file, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((l) => {
+          try {
+            return [JSON.parse(l) as RevisionSummary];
+          } catch {
+            return []; // a torn line — the rebuild below brings it back
+          }
+        })
+        .reverse()
+    : [];
+  // The revision files are the record; index.jsonl is a cache of them. An
+  // append from two processes on NFS is not atomic across clients, and a
+  // process can die between a revision's file and its line — so when the
+  // two disagree, the index is rebuilt from the files.
+  const recorded = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).length;
+  if (recorded !== new Set(all.map((r) => r.id)).size) all = rebuildIndex(dir);
+  // A line appended just after a rebuild wrote it too: once each.
+  const seen = new Set<string>();
+  all = all.filter((r) => !seen.has(r.id) && seen.add(r.id));
   const narrowed = opts.forPath ? all.filter((r) => r.paths.includes(opts.forPath!)) : all;
   return narrowed.slice(0, opts.limit ?? 200);
 }
 
+/** index.jsonl again, from the revision files themselves, newest first. */
+function rebuildIndex(dir: string): RevisionSummary[] {
+  const rows: (RevisionSummary & { written: number })[] = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const file = path.join(dir, f);
+      const rev = JSON.parse(fs.readFileSync(file, "utf8")) as Revision;
+      rows.push({ id: rev.id, at: rev.at, by: rev.by, message: rev.message, commit: rev.commit, paths: rev.files.map((x) => x.path), written: fs.statSync(file).mtimeMs });
+    } catch {
+      // a revision half-written by a process that died: not one
+    }
+  }
+  // Two saves in one millisecond share an `at`; the order they were written
+  // in breaks the tie (an id's suffix is random, so it cannot).
+  rows.sort((a, b) => a.at.localeCompare(b.at) || a.written - b.written || a.id.localeCompare(b.id));
+  try {
+    const tmp = path.join(dir, `index.jsonl.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, rows.map(({ written: _w, ...r }) => JSON.stringify(r) + "\n").join(""));
+    fs.renameSync(tmp, path.join(dir, "index.jsonl"));
+  } catch {
+    // a read-only volume still gets the answer
+  }
+  return rows.map(({ written: _w, ...r }) => r).reverse();
+}
+
 export function readRevision(tenant: string, scope: string, id: string, forPath?: string): Revision | null {
   assertSafeName(id, "revision id");
-  if (useGit() && repoExists(tenant, scope) && /^[0-9a-f]{7,40}$/.test(id)) {
-    const fromGit = readCommit(tenant, scope, id, forPath);
-    if (fromGit) return fromGit;
-  }
   const file = path.join(historyDir(tenant, scope), `${id}.json`);
   if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, "utf8")) as Revision;
-}
-
-/**
- * Make sure a scope's repository has its initial import, so a clone made
- * right now is complete. A no-op once any commit exists.
- */
-export function ensureImported(tenant: string, scope: string): string | null {
-  if (!useGit()) return null;
-  if (headSha(tenant, scope)) return headSha(tenant, scope);
-  const tree = readTree(tenant, scope);
-  if (!tree || tree.length === 0) return null;
-  return commitChanges(tenant, scope, tree, { by: "foldrun", message: "initial import" });
+  const rev = JSON.parse(fs.readFileSync(file, "utf8")) as Revision;
+  return forPath ? { ...rev, files: rev.files.filter((f) => f.path === forPath) } : rev;
 }
 
 /** The most recent revision id for a scope — what a change is attributed

package/src/library.ts

@@ -435,47 +435,3 @@ registerTreeReader((tenant, scope) => {
 });
 
 
-/**
- * Make the shelf match a tree — what a push to the library repository does.
- * Written with plain fs and recorded as ONE revision at the end: going
- * through writeLibraryFile per file would commit each one on top of the
- * pushed commit, and the history would show a push as fifty edits.
- */
-export function syncLibraryFromTree(tenant: string, files: { path: string; content: string }[], meta: { by?: string; commit?: string | null } = {}) {
-  const wanted = new Map<string, string>();
-  for (const f of files) {
-    const [kind, ...rest] = f.path.split("/");
-    if (!LIBRARY_KINDS.includes(kind as LibraryKind) || rest.length === 0) continue;
-    wanted.set(f.path, f.content);
-  }
-  const changes: { path: string; before: string | null; after: string | null }[] = [];
-  for (const kind of LIBRARY_KINDS) {
-    const dir = libraryDir(tenant, kind);
-    if (!fs.existsSync(dir)) continue;
-    for (const entry of fs.readdirSync(dir, { recursive: true })) {
-      const rel = `${kind}/${String(entry).split(path.sep).join("/")}`;
-      const full = path.join(dir, String(entry));
-      try {
-        if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel)) continue;
-      } catch {
-        continue;
-      }
-      if (!wanted.has(rel)) {
-        changes.push({ path: rel, before: fs.readFileSync(full, "utf8"), after: null });
-        fs.rmSync(full, { force: true });
-      }
-    }
-  }
-  for (const [rel, content] of wanted) {
-    const [kind, ...rest] = rel.split("/");
-    const full = path.join(libraryDir(tenant, kind as LibraryKind), assertLibraryPath(kind as LibraryKind, rest.join("/")));
-    const before = fs.existsSync(full) ? fs.readFileSync(full, "utf8") : null;
-    if (before === content) continue;
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, content);
-    if (kind === "scripts" || /scripts\//.test(rel) || (kind === "tools" && !rel.endsWith(".md"))) fs.chmodSync(full, 0o755);
-    changes.push({ path: rel, before, after: content });
-  }
-  recordRevision(tenant, "@library", changes, { by: meta.by ?? "deploy", message: meta.commit ? `deployed ${meta.commit.slice(0, 7)}` : "synced from push", commit: meta.commit ?? null });
-  return changes.length;
-}

package/src/model-credential.ts

@@ -75,7 +75,7 @@ export function credentialLine(c: ModelCredential): { type: "info" | "error"; te
 //
 // An account brings its own model key without writing a provider: block:
 // three secrets in the ACCOUNT vault (set from Settings → Model, the API's
-// /api/account/model, or `foldrun model set`). A provider: block at any
+// /api/account/model, or `foldrun account model set`). A provider: block at any
 // level still wins; this is what a step falls to when none names one, before
 // the platform's own credential.
 

package/src/model-env.ts

@@ -23,7 +23,7 @@ export class ModelKeyError extends Error {
 
 export const NO_MODEL_KEY =
   "no model key: this account runs on its own API key, and none is set — add one in Settings → Model " +
-  "(or `foldrun model set <provider> --key …`), or write a provider: block in AGENTS.md";
+  "(or `foldrun account model set <provider> --key …`), or write a provider: block in AGENTS.md";
 
 /**
  * `platform` is a function: the caller's own way to build the platform's env

package/src/platform.ts

@@ -109,8 +109,6 @@ export interface PlatformHooks {
   killRunSandboxes(runId: string): void;
   /** Publish storage/public/ as share links after a run. Default: no links. */
   syncPublicShares(tenant: string, workspace: string): Promise<{ added: string[] }>;
-  /** The workspace a preview was branched from, for inherited secrets. Default: none. */
-  previewSourceOf(tenant: string, workspace: string): string | null;
   /** This account's own data key, or null to use the install key. */
   tenantKey(tenant: string): Buffer | null;
   /** The egress proxy — a per-step lease that keeps credentials out of the
@@ -120,7 +118,7 @@ export interface PlatformHooks {
    *  workspace deleted. What a scheduler that keeps flows in memory rather
    *  than re-reading every workspace each tick needs to hear. Default:
    *  nothing — locally the scheduler reads the disk. Never throws. */
-  workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+  workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "delete"): void;
   /** Can a step in this isolation mode be re-attached to after the driver
    *  that started it is gone? True means an orphaned step with a `sandbox`
    *  on its record is resumed rather than destroyed and run again. Default:
@@ -204,7 +202,6 @@ const local: PlatformHooks = {
   isolation: {},
   killRunSandboxes() {},
   syncPublicShares: async () => ({ added: [] }),
-  previewSourceOf: () => null,
   tenantKey: () => null,
   egress: { lease: async () => null },
   workspaceChanged() {},

package/src/run-container.ts

@@ -27,7 +27,7 @@ import { spawn, spawnSync } from "node:child_process";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { isPlatformPath, type ApiSpec, type Effort } from "./store.ts";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
-import type { EventExtra } from "./step-exec.ts";
+import type { EventExtra, ExecUsage } from "./step-exec.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET, type RuntimeSpec } from "./runtime.ts";
 import { egressCaSh, type NetworkLevel } from "./network.ts";
@@ -121,6 +121,47 @@ export interface StepTiming {
   sandboxMs: number;
   firstOutputMs: number | null;
   totalMs: number;
+  /** Where the start-up went, phase by phase — see STARTUP_PHASES. Absent
+   *  from an executor that marks none, and from a resumed driver (the
+   *  first driver's phases are on the record already). */
+  phases?: StartupPhases;
+}
+
+/**
+ * The start-up of one step, in the order it happens. Each is the moment the
+ * phase ENDED, in ms since the executor began the step, so the gap between
+ * two neighbours is what the later one cost (FOL-29: "pod ready" was the
+ * only number, and the six seconds after it had no names).
+ *
+ * The executor marks its own: `services` (the account's search/browser pods
+ * up), `room` (room on the cluster to start — platform pod-room.ts),
+ * `applied` (pod created), `ready`, `files` (the workspace copied in),
+ * `go` (the step released). The sandbox marks the rest as `{"e":"mark"}`
+ * lines: `shim` (the shim saw go), `system` (system packages restored),
+ * `driver` (node up), `imports` (core loaded), `tools` (runtime and tools
+ * built, the SDK about to start) and `model` (the model's first text or tool
+ * call). A worker that predates a mark ignores the line — parseDriverLine
+ * answers null for an `e` it does not know.
+ */
+export const STARTUP_PHASES = [
+  "services", "room", "applied", "ready", "files", "go",
+  "shim", "system", "driver", "imports", "tools", "model",
+] as const;
+export type StartupPhase = (typeof STARTUP_PHASES)[number];
+export type StartupPhases = Partial<Record<StartupPhase, number>>;
+
+/** A sandbox-side mark: which phase ended, and when (epoch ms, the
+ *  sandbox's clock — the same machine's as the worker's on one node). */
+export function parseDriverMark(line: string): { name: StartupPhase; at: number } | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('{"e":"mark"')) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed.e !== "mark" || typeof parsed.at !== "number" || !Number.isFinite(parsed.at)) return null;
+    return (STARTUP_PHASES as readonly string[]).includes(parsed.name) ? { name: parsed.name, at: parsed.at } : null;
+  } catch {
+    return null;
+  }
 }
 
 export interface StepActuals {
@@ -143,7 +184,7 @@ export interface ContainerStepOutcome {
   /** The parsed JSON of an `output: json` step, crossing back as a value. */
   data?: unknown;
   costUsd: number | null;
-  usage?: { inputTokens: number; outputTokens: number } | null;
+  usage?: ExecUsage | null;
   /** Every turn priced at its own model, when sub-agents ran on others —
    *  see ExecOutcome.turnsCostUsd. */
   turnsCostUsd?: number;
@@ -168,7 +209,11 @@ export interface ContainerStepOutcome {
 export function timingLine(t: StepTiming): string {
   const s = (ms: number) => `${(ms / 1000).toFixed(2)}s`;
   const first = t.firstOutputMs === null ? "no output" : `first output +${s(t.firstOutputMs)}`;
-  return `timing: sandbox ready in ${s(t.sandboxMs)}, ${first}, ${s(t.totalMs)} total`;
+  const phases = t.phases
+    ? STARTUP_PHASES.filter((p) => typeof t.phases![p] === "number").map((p) => `${p} ${s(t.phases![p]!)}`)
+    : [];
+  return `timing: sandbox ready in ${s(t.sandboxMs)}, ${first}, ${s(t.totalMs)} total` +
+    (phases.length ? ` · start-up: ${phases.join(" → ")}` : "");
 }
 
 const cli = () => process.env.FOLDRUN_CONTAINER_CLI ?? "docker";
@@ -504,7 +549,17 @@ const DRIVER = `// The runner container's entrypoint. Reads one step, executes i
 // same core the server uses, speaks JSONL on stdout, exits.
 import fs from "node:fs";
 const input = JSON.parse(fs.readFileSync("/opt/runner/job/input.json", "utf8"));
-const emit = (type, text, extra) => process.stdout.write(JSON.stringify({ e: "event", type, text, ...extra }) + "\\n");
+// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,
+// on the sandbox's clock. A worker that does not know a mark skips the line.
+const mark = (name) => process.stdout.write(JSON.stringify({ e: "mark", name, at: Date.now() }) + "\\n");
+mark("driver");
+let modelSpoke = false;
+const emit = (type, text, extra) => {
+  // The model's first text or tool call is where start-up ends and the
+  // step's own work begins — runtime and tool lines before it are set-up.
+  if (!modelSpoke && (type === "text" || type === "tool")) { modelSpoke = true; mark("model"); }
+  process.stdout.write(JSON.stringify({ e: "event", type, text, ...extra }) + "\\n");
+};
 // What this sandbox actually touched, read at the last moment from the
 // kernel's own books: cgroup v2 for CPU busy-time and peak memory,
 // /proc/net/dev for bytes on the wire. Every read is best-effort — gVisor
@@ -560,6 +615,7 @@ try {
   const { prepareRuntime } = await import("@foldrun/core/runtime");
   const { materializeFileSecrets } = await import("@foldrun/core/secret-files");
   const { paidWebActions } = await import("@foldrun/core/browser-pod");
+  mark("imports");
 
   const agentDir = "/workspace/" + input.agentRel;
   // HOME is where a bare relative path lands when anything resolves one
@@ -642,6 +698,7 @@ try {
   const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };
   const inbox = channel ? inboxReader(channel, emit) : undefined;
 
+  mark("tools");
   const outcome = await executeStep({
     agentDir,
     workspaceRoot: "/workspace",
@@ -1159,7 +1216,14 @@ export function parseDriverLine(
           parsed.usage &&
           typeof parsed.usage.inputTokens === "number" &&
           typeof parsed.usage.outputTokens === "number"
-            ? { inputTokens: parsed.usage.inputTokens, outputTokens: parsed.usage.outputTokens }
+            ? {
+                inputTokens: parsed.usage.inputTokens,
+                outputTokens: parsed.usage.outputTokens,
+                // A driver from before the split sends neither; zero, not
+                // unknown, keeps the record's shape one thing.
+                cacheReadTokens: typeof parsed.usage.cacheReadTokens === "number" ? parsed.usage.cacheReadTokens : 0,
+                cacheWriteTokens: typeof parsed.usage.cacheWriteTokens === "number" ? parsed.usage.cacheWriteTokens : 0,
+              }
             : null,
         res:
           parsed.res && typeof parsed.res === "object"
@@ -1470,6 +1534,8 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     if (create.status !== 0) throw new Error(`container create failed:\n${create.stderr}`);
     containerId = create.stdout.trim();
     const sandboxMs = Date.now() - t0;
+    // Docker's phases are measured from create, its rent clock.
+    const phases: StartupPhases = { ready: sandboxMs };
 
     const cp = (from: string, to: string) => {
       const out = spawnSync(cli(), ["cp", from, to], { encoding: "utf8" });
@@ -1478,6 +1544,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     cp(`${wsIn}/.`, `${containerId}:/workspace`);
     cp(`${libIn}/.`, `${containerId}:/library`);
     cp(`${jobIn}/input.json`, `${containerId}:/opt/runner/job/input.json`);
+    phases.files = Date.now() - t0;
 
     // Start attached and read the driver's JSONL. The step timeout gets a
     // backstop out here — a wedged container is killed, not waited on.
@@ -1503,6 +1570,11 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
           if (nl < 0) break;
           const line = buffer.slice(0, nl);
           buffer = buffer.slice(nl + 1);
+          const marked = parseDriverMark(line);
+          if (marked) {
+            phases[marked.name] ??= Math.max(0, marked.at - t0);
+            continue;
+          }
           const parsed = parseDriverLine(line);
           if (!parsed) continue;
           firstOutputAt ??= Date.now();
@@ -1546,6 +1618,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       sandboxMs,
       firstOutputMs: firstOutputAt === null ? null : firstOutputAt - t0 - sandboxMs,
       totalMs: Date.now() - t0,
+      phases,
     };
     args.emit("info", timingLine(timing));
     return { ...outcome, timing };