@foldrun/core 1.4.2 → 2.1.0

package/dist/src/run-container.js

@@ -30,6 +30,42 @@ import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKE
 import { egressCaSh } from "./network.js";
 import { isOperatorEvent } from "./operator.js";
 import { parseBrowserPod } from "./browser-pod.js";
+/**
+ * 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",
+];
+/** 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) {
+    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.includes(parsed.name) ? { name: parsed.name, at: parsed.at } : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The one place the timing line is worded, so the docker and k8s traces
  * read the same and a cold-start regression is greppable across both.
@@ -37,7 +73,11 @@ import { parseBrowserPod } from "./browser-pod.js";
 export function timingLine(t) {
     const s = (ms) => `${(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";
 // Paths that must never come back from a container, whatever happened in
@@ -374,7 +414,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
@@ -430,6 +480,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
@@ -512,6 +563,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",
@@ -1016,7 +1068,14 @@ export function parseDriverLine(line) {
                 usage: 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"
                     ? {
@@ -1260,6 +1319,8 @@ export async function runStepInContainer(args) {
             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 = { ready: sandboxMs };
         const cp = (from, to) => {
             const out = spawnSync(cli(), ["cp", from, to], { encoding: "utf8" });
             if (out.status !== 0)
@@ -1268,6 +1329,7 @@ export async function runStepInContainer(args) {
         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.
         let firstOutputAt = null;
@@ -1292,6 +1354,11 @@ export async function runStepInContainer(args) {
                         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;
@@ -1339,6 +1406,7 @@ export async function runStepInContainer(args) {
             sandboxMs,
             firstOutputMs: firstOutputAt === null ? null : firstOutputAt - t0 - sandboxMs,
             totalMs: Date.now() - t0,
+            phases,
         };
         args.emit("info", timingLine(timing));
         return { ...outcome, timing };

package/dist/src/runner.d.ts

@@ -354,6 +354,8 @@ grantsOnly?: boolean): {
 export declare function repriced(catalog: Catalog | null, model: string, usage: {
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
 } | null, sdkCost: number | null, push: (type: "info" | "error", text: string) => void, 
 /** The step's turns each priced at its own model — set when a sub-agent
  *  ran on a different model (ExecOutcome.turnsCostUsd). The lump `usage`

package/dist/src/runner.js

@@ -33,7 +33,7 @@ import { ASK_TOOL, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskToo
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
-import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
 import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.js";
@@ -1876,8 +1876,12 @@ stepIndex) {
         // that names a provider uses its own; otherwise the platform's (in a
         // run container) or this process's — never a login that just happens
         // to be on the machine (model-credential.ts).
-        const credential = providerLabel ? null : resolveModelCredential(isolatedRun() ? platformModelEnv() : process.env);
-        step.credential = credential ? credential.label : `provider: ${providerLabel}`;
+        // An account refused the platform's credential (below) is never shown
+        // running on it: the record said "Claude login token" on a step that
+        // was then refused for having no key (FOL-14, 18 Oct 2026).
+        const noKey = !providerLabel && !platform.platformKeyAllowed(tenant);
+        const credential = providerLabel || noKey ? null : resolveModelCredential(isolatedRun() ? platformModelEnv() : process.env);
+        step.credential = credential ? credential.label : noKey ? "none — this account has no model key" : `provider: ${providerLabel}`;
         if (credential) {
             const line = credentialLine(credential);
             push(line.type, line.text);
@@ -1890,7 +1894,7 @@ stepIndex) {
             const own = Object.values(providerSecrets).concat(Object.values(providerEnv));
             if (!providerLabel) {
                 push("error", `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`);
                 step.status = "failed";
                 save();
                 return;
@@ -2621,7 +2625,7 @@ stepIndex) {
                     step.podLostTry = {
                         status: "lost",
                         costUsd: repriced(catalog, wireModel, first.usage ?? null, first.costUsd, push, first.turnsCostUsd),
-                        tokens: first.usage ? { input: first.usage.inputTokens, output: first.usage.outputTokens } : null,
+                        tokens: tokensOf(first.usage),
                         computeSecs: first.timing ? Math.round(first.timing.totalMs) / 1000 : null,
                         finishedAt: new Date().toISOString(),
                         error: decision.note.slice(0, 500),
@@ -2671,9 +2675,7 @@ stepIndex) {
             if (outcome.data !== undefined)
                 step.data = redactData(outcome.data);
             step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push, outcome.turnsCostUsd);
-            step.tokens = outcome.usage
-                ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
-                : null;
+            step.tokens = tokensOf(outcome.usage);
             step.actual = outcome.res ?? null;
             if (outcome.res?.peakMemBytes || outcome.res?.rxBytes) {
                 const mb = (n) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -2687,6 +2689,12 @@ stepIndex) {
             const secs = (ms) => Math.round(ms) / 1000;
             step.computeSecs = outcome.timing ? secs(outcome.timing.totalMs) : null;
             step.startupSecs = outcome.timing ? secs(outcome.timing.sandboxMs) : null;
+            // Where the start-up went, phase by phase (run-container.ts#STARTUP_PHASES),
+            // in seconds — what the cold-start numbers are computed from.
+            const phases = outcome.timing?.phases;
+            step.startup = phases && Object.keys(phases).length
+                ? Object.fromEntries(Object.entries(phases).map(([k, v]) => [k, secs(v)]))
+                : null;
             // Which reservation those seconds held — as numbers, because the bill
             // is per core-second and per GiB-second, and what was held must come
             // from the record, never from what the config says at billing time.
@@ -2864,9 +2872,7 @@ stepIndex) {
             const consultCost = consultTools.drainCost();
             const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push, outcome.turnsCostUsd);
             step.costUsd = stepCost === null && consultCost === 0 ? null : (stepCost ?? 0) + consultCost;
-            step.tokens = outcome.usage
-                ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
-                : null;
+            step.tokens = tokensOf(outcome.usage);
             for (const line of apiTools.drainLog())
                 push("info", `api: ${line}`);
             for (const line of scriptTools.drainLog())
@@ -4768,7 +4774,9 @@ function lastActivity(run) {
 export function reconcileRuns(tenant, now = Date.now(), live) {
     const closed = [];
     for (const workspace of listWorkspaces(tenant)) {
-        for (const summary of listRuns(tenant, workspace.name)) {
+        // Live runs only, read whole — every other status is passed over below,
+        // and parsing the workspace's whole history every sweep was the cost.
+        for (const summary of liveRuns(tenant, workspace.name)) {
             if (drivingRuns.has(summary.id))
                 continue;
             // Driven by another process — a second worker pod, on a platform with

package/dist/src/secrets.js

@@ -218,11 +218,9 @@ export function setSecretSites(tenant, name, sites, workspace) {
 export function secretSites(tenant, names, workspace) {
     const out = {};
     const own = workspace ? read(tenant, workspace) : {};
-    const source = workspace ? platform.previewSourceOf(tenant, workspace) : null;
-    const inherited = source ? read(tenant, source) : {};
     const account = read(tenant);
     for (const name of names) {
-        const rec = own[name] ?? inherited[name] ?? account[name];
+        const rec = own[name] ?? account[name];
         if (rec?.sites?.length)
             out[name] = [...rec.sites];
     }
@@ -298,15 +296,6 @@ export function getSecret(tenant, name, workspace) {
         const own = decrypt(tenant, read(tenant, workspace)[name]);
         if (own !== null)
             return { value: own, scope: "workspace" };
-        // A preview is a branch of its source workspace, and the branch's
-        // agents need the same credentials the source's do. Its own store is
-        // still consulted first, so a preview can override one on purpose.
-        const source = platform.previewSourceOf(tenant, workspace);
-        if (source) {
-            const inherited = decrypt(tenant, read(tenant, source)[name]);
-            if (inherited !== null)
-                return { value: inherited, scope: "workspace" };
-        }
     }
     const shared = decrypt(tenant, read(tenant)[name]);
     return shared === null ? null : { value: shared, scope: "account" };

package/dist/src/starter.js

@@ -373,8 +373,8 @@ Debugging a failed run is usually: \`runs\` to find it, \`runs/<id>\` to read wh
 step failed and what it cost, fix the markdown, \`deploy\`, then \`rerun\`.
 
 Every route, with request and response shapes, is in \`docs/api.md\` in the
-foldrun repository — including secrets, keys, billing, OAuth, webhooks and the
-git push endpoint.
+foldrun repository — including secrets, keys, billing, OAuth, webhooks and
+restore.
 
 ## Writing a flow
 

package/dist/src/step-exec.d.ts

@@ -6,6 +6,17 @@ import type { OperatorEvent } from "./operator.ts";
 import { type SubagentSpec } from "./subagents.ts";
 import { type Limits } from "./limits.ts";
 import { type BrowserPodOutcome, type ClassifyContext } from "./browser-pod.ts";
+export interface ExecUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** The four counts from one SDK usage object (snake_case, as the API
+ *  reports it). The API counts fresh input apart from the cache's; here
+ *  `inputTokens` is all of it, as it always was on the record, and the
+ *  cache fields say how much of that the cache served or stored. */
+export declare function usageFromSdk(u: Record<string, number | undefined>): ExecUsage;
 export interface ExecOutcome {
     status: "completed" | "failed";
     result: string | null;
@@ -20,11 +31,12 @@ export interface ExecOutcome {
     costUsd: number | null;
     /** Token counts off the SDK's result message. costUsd is priced from
      *  Anthropic's table, which is wrong for a routed model — these are the
-     *  raw numbers a caller with a gateway's own prices can reprice from. */
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-    } | null;
+     *  raw numbers a caller with a gateway's own prices can reprice from.
+     *  `inputTokens` is every input token; `cacheReadTokens` and
+     *  `cacheWriteTokens` are the part of it the prompt cache served or
+     *  stored, so a usage page can say how much of a step's context was
+     *  re-read for a tenth of the price. */
+    usage: ExecUsage | null;
     /** Set only when some turns ran on a different model from the step's — a
      *  sub-agent with its own `model:`. The sum of every turn, each priced at
      *  its own model. `usage` above is one lump and cannot be repriced at the
@@ -178,6 +190,12 @@ export declare function knownPrice(model: string | undefined): {
 /**
  * What one assistant turn cost, from the usage the SDK reports. Pure.
  *
+ * Cache reads and writes are priced at Anthropic's multipliers
+ * (catalog.ts). Counting both at the full input rate — as this did —
+ * makes a long cached prompt read about ten times its price, which on a
+ * ceiling is not "the honest direction to be wrong in", it is a step
+ * killed for spending money it never spent.
+ *
  * A gateway whose cache is priced differently is over- or under-counted
  * here by that difference alone; the run record's own cost is repriced
  * from the catalogue afterwards and stays the authority on the bill. This

package/dist/src/step-exec.js

@@ -12,6 +12,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { CACHE_READ_MULTIPLIER, CACHE_WRITE_MULTIPLIER } from "./catalog.js";
 import { spawn } from "node:child_process";
 import { checkPaths, checkBash, isFilesystemTool, linkWorkspace, workspaceLinkEnv, resolveAgentPath, isWithin } from "./confine.js";
 import { DELEGATE_TOOLS, subagentGuard, toAgentDefinitions } from "./subagents.js";
@@ -19,6 +20,18 @@ import { hostSafeEnv } from "./host-env.js";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.js";
 import { CallCounter, limitKeysFor } from "./limits.js";
 import { classifyCall, podAt, readPodEvents } from "./browser-pod.js";
+/** The four counts from one SDK usage object (snake_case, as the API
+ *  reports it). The API counts fresh input apart from the cache's; here
+ *  `inputTokens` is all of it, as it always was on the record, and the
+ *  cache fields say how much of that the cache served or stored. */
+export function usageFromSdk(u) {
+    return {
+        inputTokens: (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0),
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheWriteTokens: u.cache_creation_input_tokens ?? 0,
+    };
+}
 /** How often the stop flag is read while a step runs. */
 export const STOP_POLL_MS = 2000;
 /** The least a `verify:` gets when the step used up most of its `timeout:` —
@@ -65,17 +78,15 @@ export function knownPrice(model) {
         return null;
     return KNOWN_PRICES.find(([re]) => re.test(model))?.[1] ?? null;
 }
-/** Anthropic's cache multipliers, and the shape every gateway that bills
- *  for caching at all has copied: a write costs a quarter more than fresh
- *  input, a read a tenth of it. Counting both at the full input rate — as
- *  this did — makes a long cached prompt read about ten times its price,
- *  which on a ceiling is not "the honest direction to be wrong in", it is
- *  a step killed for spending money it never spent. */
-const CACHE_WRITE_MULTIPLIER = 1.25;
-const CACHE_READ_MULTIPLIER = 0.1;
 /**
  * What one assistant turn cost, from the usage the SDK reports. Pure.
  *
+ * Cache reads and writes are priced at Anthropic's multipliers
+ * (catalog.ts). Counting both at the full input rate — as this did —
+ * makes a long cached prompt read about ten times its price, which on a
+ * ceiling is not "the honest direction to be wrong in", it is a step
+ * killed for spending money it never spent.
+ *
  * A gateway whose cache is priced differently is over- or under-counted
  * here by that difference alone; the run record's own cost is repriced
  * from the catalogue afterwards and stays the authority on the bill. This
@@ -639,16 +650,10 @@ async function executeStepInner(opts, runQuery) {
                 costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
                 stopReason = "stop_reason" in message && typeof message.stop_reason === "string" ? message.stop_reason : null;
                 if ("usage" in message && message.usage) {
-                    const u = message.usage;
-                    usage = {
-                        // Cache traffic is input the provider still bills (at its own
-                        // rates); folding it into the input count over-approximates for
-                        // gateways with cheaper cache reads, which errs on the honest side.
-                        inputTokens: (u.input_tokens ?? 0) +
-                            (u.cache_creation_input_tokens ?? 0) +
-                            (u.cache_read_input_tokens ?? 0),
-                        outputTokens: u.output_tokens ?? 0,
-                    };
+                    // Cache reads and writes counted beside the input total: with only
+                    // the total (until 18 Oct 2026) the hit rate could not be read and
+                    // the catalogue repriced every cached token at the full rate.
+                    usage = usageFromSdk(message.usage);
                 }
             }
         }
@@ -671,16 +676,18 @@ async function executeStepInner(opts, runQuery) {
     // died — means no total from the SDK. The turns it did take were billed by
     // the provider all the same, so the step's cost is their sum.
     if (costUsd === null && turns.size) {
-        let input = 0;
-        let output = 0;
+        const summed = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
         let priced = 0;
         for (const { u: t, price } of turns.values()) {
-            input += (t.input_tokens ?? 0) + (t.cache_creation_input_tokens ?? 0) + (t.cache_read_input_tokens ?? 0);
-            output += t.output_tokens ?? 0;
+            const one = usageFromSdk(t);
+            summed.inputTokens += one.inputTokens;
+            summed.outputTokens += one.outputTokens;
+            summed.cacheReadTokens += one.cacheReadTokens;
+            summed.cacheWriteTokens += one.cacheWriteTokens;
             priced += priceTurn(t, price);
         }
         costUsd = priced;
-        usage ??= { inputTokens: input, outputTokens: output };
+        usage ??= summed;
         emit("info", `cost from ${turns.size} model turn${turns.size === 1 ? "" : "s"}: $${priced.toFixed(4)} — the step ended before the model's closing total`);
     }
     if (ended === "timeout") {

package/dist/src/store.d.ts

@@ -125,6 +125,11 @@ export declare function saveWorkspace(tenant: string, workspace: string, files:
  *  commit, which becomes the revision's id. */
 meta?: ChangeMeta & {
     commit?: string | null;
+    /** Keep every file that is not editable source — what an agent wrote
+     *  into its own folder at run time (a browser profile, a PDF it
+     *  downloaded). A restore sets it: history holds source, so a file it
+     *  never tracked is not one a restore may take away. */
+    keepUntracked?: boolean;
 }): {
     preserved: number;
 };
@@ -754,15 +759,6 @@ export interface WorkspaceSummary {
     flows: number;
     deployedAt: string;
     runCount: number;
-    /** Set when this workspace is a branch's preview of another (preview.ts):
-     *  which one, which branch, which commit. Read from the marker beside the
-     *  directory here rather than through preview.ts, which imports this file. */
-    preview?: {
-        source: string;
-        branch: string;
-        commit: string;
-        at: string;
-    };
     /** The workspace's picture, as a URL, when the page that lists it looked
      *  one up (avatars.ts) — the store itself does not. */
     avatar?: string | null;
@@ -824,7 +820,7 @@ export interface ChangeMeta {
 }
 export declare function writeWorkspaceFile(tenant: string, workspace: string, rel: string, content: string, meta?: ChangeMeta): void;
 /** Tell the platform, and never let its listener fail a write. */
-declare function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+declare function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "delete"): void;
 export { workspaceChanged as notifyWorkspaceChanged };
 export declare function syncBundleFor(file: string, change?: "Creation" | "Update"): void;
 /**
@@ -957,10 +953,7 @@ export interface StepAttempt {
      *  of its own (image slim), before the full go's. */
     status: "completed" | "failed" | "lost";
     costUsd: number | null;
-    tokens: {
-        input: number;
-        output: number;
-    } | null;
+    tokens: TokenUsage | null;
     computeSecs: number | null;
     startedAt: string;
     finishedAt: string;
@@ -976,6 +969,44 @@ export interface StepAttempt {
  *  attempt reported the figure — an in-process step rents no sandbox, and
  *  billing reads null as zero, not as "unknown, charge something". */
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs">;
+/**
+ * The token counts behind a step's cost. `input` is every input token the
+ * model saw; `cacheRead` and `cacheWrite` are the part of it the prompt
+ * cache served or stored — a read costs a tenth of fresh input, and a usage
+ * page wants to say how much of a step's context was re-read rather than
+ * re-sent. Steps recorded before 18 Oct 2026 have no cache fields: their
+ * `input` is the same total, but how much of it was cached is unknown.
+ */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** The record's shape from what a step reports (ExecOutcome.usage). */
+export declare function tokensOf(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+} | null | undefined): TokenUsage | null;
+/** Field-by-field sum; the cache fields are present in the result whenever
+ *  any input had them, so a run of old and new steps still reads whole. */
+export declare function sumTokens(list: readonly TokenUsage[]): TokenUsage;
+/** The share of all input that the prompt cache served, 0–1; null when
+ *  there was no input, or the record predates the split and cannot say. */
+export declare function cacheHitRate(t: TokenUsage | null | undefined): number | null;
+/** The cache share over several counts, taking only those that report the
+ *  split: a step recorded before it holds its cache traffic inside `input`,
+ *  and counting that as uncached would understate the rate. The rule the
+ *  Usage page and the CLI's totals follow too. */
+export declare function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null;
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export declare function runTokens(run: {
+    steps: readonly {
+        tokens?: TokenUsage | null;
+    }[];
+}): TokenUsage | null;
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1144,6 +1175,12 @@ export interface StepRecord {
      */
     computeSecs?: number | null;
     startupSecs?: number | null;
+    /** When each start-up phase ended, in seconds since the executor began
+     *  the step — `services`, `applied`, `ready`, `files`, `go`, `shim`,
+     *  `system`, `driver`, `imports`, `tools`, `model` (run-container.ts
+     *  #STARTUP_PHASES). Only the phases this step went through; null from
+     *  an executor that marks none, absent on steps from before 17 Oct 2026. */
+    startup?: Record<string, number> | null;
     /** Which reservation class the sandbox held (small | large), and the
      *  actual limits it held, as numbers. Facts of the step: a price is per
      *  core-second, so what was reserved must come from the record, never
@@ -1157,10 +1194,7 @@ export interface StepRecord {
     /** Token counts behind costUsd, kept so usage reports can say "how many"
      *  and not only "how much" — the price of a token changes, the count is
      *  the fact. Absent on steps recorded before this existed. */
-    tokens?: {
-        input: number;
-        output: number;
-    } | null;
+    tokens?: TokenUsage | null;
     /** What the sandbox actually touched, against what it reserved: CPU
      *  busy-seconds and peak memory from the pod's own cgroup, bytes on the
      *  wire from /proc/net/dev. Null per-field where the kernel interface
@@ -1288,6 +1322,14 @@ export declare function listRunOutputs(tenant: string, workspace: string, runId:
 export declare function runOutputPath(tenant: string, workspace: string, runId: string, agent: string, rel: string): string | null;
 export declare function readRun(tenant: string, workspace: string, runId: string): RunRecord | null;
 export declare function writeRun(tenant: string, workspace: string, run: RunRecord): void;
+/**
+ * The workspace's live runs — queued, running, or parked at a gate — read
+ * whole, newest first. Off the run index: only the live records are opened,
+ * where listRuns parses every record the workspace ever kept. What the
+ * periodic sweeps want (reconcile, the watchdog), and on a box that keeps
+ * ninety days of runs that is a handful of files instead of thousands.
+ */
+export declare function liveRuns(tenant: string, workspace: string): RunRecord[];
 export interface RunWithWorkspace extends RunRecord {
     workspace: string;
 }
@@ -1314,10 +1356,7 @@ export interface RunSummaryStep {
     group: number;
     status: StepRecord["status"];
     costUsd: number | null;
-    tokens?: {
-        input: number;
-        output: number;
-    } | null;
+    tokens?: TokenUsage | null;
     computeSecs?: number | null;
     skipReason?: string;
     /** The last error event, for a failed step — what runFailure reads. */