@foldrun/core 1.4.2 → 2.1.0

package/dist/src/history.js

@@ -15,45 +15,33 @@
 // 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.js";
-import { commitChanges, gitAvailable, headSha, listCommits, readCommit, repoExists, } from "./gitrepo.js";
 let readTree = () => null;
 export function registerTreeReader(fn) {
     const prev = readTree;
     readTree = (tenant, scope) => fn(tenant, scope) ?? prev(tenant, scope);
 }
-const afterCommit = [];
-export function registerAfterCommit(fn) {
-    afterCommit.push(fn);
-}
-export function notifyCommit(tenant, scope, sha) {
-    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, what) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._@-]{0,120}$/.test(v))
         throw new Error(`illegal ${what}: ${v}`);
@@ -82,37 +70,6 @@ export function recordRevision(tenant, scope, files, meta = {}) {
     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 = {
@@ -137,9 +94,168 @@ export function recordRevision(tenant, scope, files, meta = {}) {
         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) => crypto.createHash("sha256").update(s).digest("hex");
+const treePath = (tenant, scope, id) => path.join(historyDir(tenant, scope), "trees", `${id}.json`);
+const blobPath = (tenant, scope, sha) => 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, scope, id) {
+    const tree = readTree(tenant, scope);
+    if (!tree)
+        return false;
+    const files = {};
+    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, scope, id) {
+    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, scope, id) {
+    assertSafeName(id, "revision id");
+    let manifest;
+    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, scope) {
+    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, scope) {
+    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, scope, by = "foldrun") {
+    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 = {
+        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 = { 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, scope, to, now = Date.now()) {
+    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]]
+        : /^\d{4}-\d{2}-\d{2}/.test(t)
+            ? Date.parse(t)
+            : null;
+    let hit;
+    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) => s === null ? null : s.length > MAX_INLINE ? `[${s.length} bytes — too large to keep inline]` : s;
 /** "edited tools/x/run.py", "created 3 files", "deleted flows/old.md". */
 function describe(files) {
@@ -157,59 +273,76 @@ function describe(files) {
 }
 /** Newest first. `forPath` narrows to revisions that touched one file. */
 export function listRevisions(tenant, scope, opts = {}) {
-    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);
 }
 function journalRevisions(tenant, scope, opts = {}) {
-    const file = path.join(historyDir(tenant, scope), "index.jsonl");
-    if (!fs.existsSync(file))
+    const dir = historyDir(tenant, scope);
+    const file = path.join(dir, "index.jsonl");
+    if (!fs.existsSync(dir))
         return [];
-    const all = fs
-        .readFileSync(file, "utf8")
-        .split("\n")
-        .filter(Boolean)
-        .flatMap((l) => {
+    let all = fs.existsSync(file)
+        ? fs
+            .readFileSync(file, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .flatMap((l) => {
+            try {
+                return [JSON.parse(l)];
+            }
+            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();
+    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) {
+    const rows = [];
+    for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
         try {
-            return [JSON.parse(l)];
+            const file = path.join(dir, f);
+            const rev = JSON.parse(fs.readFileSync(file, "utf8"));
+            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 {
-            return []; // a torn line from a crash mid-append loses one entry, not the file
+            // a revision half-written by a process that died: not one
         }
-    })
-        .reverse();
-    const narrowed = opts.forPath ? all.filter((r) => r.paths.includes(opts.forPath)) : all;
-    return narrowed.slice(0, opts.limit ?? 200);
+    }
+    // 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, scope, id, forPath) {
     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"));
-}
-/**
- * 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, scope) {
-    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"));
+    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
  *  to when nothing more specific (a deployed commit) is on record. */

package/dist/src/library.d.ts

@@ -88,16 +88,3 @@ export interface LibraryUse {
     relation: "use" | "shadowed";
 }
 export declare function libraryUsage(tenant: string, kind: LibraryKind, name: string): LibraryUse[];
-/**
- * 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 declare function syncLibraryFromTree(tenant: string, files: {
-    path: string;
-    content: string;
-}[], meta?: {
-    by?: string;
-    commit?: string | null;
-}): number;

package/dist/src/library.js

@@ -344,53 +344,3 @@ registerTreeReader((tenant, scope) => {
     }
     return out;
 });
-/**
- * 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, files, meta = {}) {
-    const wanted = new Map();
-    for (const f of files) {
-        const [kind, ...rest] = f.path.split("/");
-        if (!LIBRARY_KINDS.includes(kind) || rest.length === 0)
-            continue;
-        wanted.set(f.path, f.content);
-    }
-    const changes = [];
-    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), assertLibraryPath(kind, 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/dist/src/model-credential.js

@@ -60,7 +60,7 @@ export function credentialLine(c) {
 //
 // 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.
 /** The account vault names the account's own model key lives under. */

package/dist/src/model-env.js

@@ -19,7 +19,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
  * (a step's, or the SDK's host env), called only when this account may use

package/dist/src/platform.d.ts

@@ -90,8 +90,6 @@ export interface PlatformHooks {
     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
@@ -101,7 +99,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:

package/dist/src/platform.js

@@ -25,7 +25,6 @@ const local = {
     isolation: {},
     killRunSandboxes() { },
     syncPublicShares: async () => ({ added: [] }),
-    previewSourceOf: () => null,
     tenantKey: () => null,
     egress: { lease: async () => null },
     workspaceChanged() { },

package/dist/src/run-container.d.ts

@@ -1,7 +1,7 @@
 import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type ApiSpec, type Effort } from "./store.ts";
-import type { EventExtra } from "./step-exec.ts";
+import type { EventExtra, ExecUsage } from "./step-exec.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import { type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
@@ -97,7 +97,36 @@ 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 declare const STARTUP_PHASES: readonly ["services", "room", "applied", "ready", "files", "go", "shim", "system", "driver", "imports", "tools", "model"];
+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 declare function parseDriverMark(line: string): {
+    name: StartupPhase;
+    at: number;
+} | null;
 export interface StepActuals {
     busyCpuSecs: number | null;
     peakMemBytes: number | null;
@@ -117,10 +146,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;