@foldrun/core 1.4.2 → 2.1.0

package/src/runner.ts

@@ -49,6 +49,7 @@ import {
   listWorkspaces,
   listTenants,
   listRuns,
+  liveRuns,
   syncBundleFor,
   parseToolDef,
   type ToolDef,
@@ -74,6 +75,7 @@ import {
   type StepRecord,
   type StepAttempt,
   sumAttempts,
+  tokensOf,
   parseSchemaText,
   STORAGE_DIR,
   adoptLegacyVersionKey,
@@ -1711,7 +1713,7 @@ async function publishPublicDir(
 export function repriced(
   catalog: Catalog | null,
   model: string,
-  usage: { inputTokens: number; outputTokens: number } | null,
+  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
@@ -2063,8 +2065,12 @@ async function runStep(
     // 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);
@@ -2079,7 +2085,7 @@ async function runStep(
         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();
@@ -2827,7 +2833,7 @@ async function runStep(
           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),
@@ -2871,9 +2877,7 @@ async function runStep(
       if (outcome.status === "failed" && outcome.reason) push("error", `sandbox ended: ${outcome.reason}`);
       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: number | null) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
@@ -2890,6 +2894,12 @@ async function runStep(
       const secs = (ms: number) => 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.
@@ -3069,9 +3079,7 @@ async function runStep(
       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()) push("info", `script: ${line}`);
     }
@@ -5054,7 +5062,9 @@ export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlyS
   const closed: Reconciliation[] = [];
 
   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
       // more than one. The idle window protects a quiet step from THIS

package/src/secrets.ts

@@ -252,11 +252,9 @@ export function setSecretSites(tenant: string, name: string, sites: string[], wo
 export function secretSites(tenant: string, names: string[], workspace?: string): Record<string, string[]> {
   const out: Record<string, string[]> = {};
   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];
   }
   return out;
@@ -349,14 +347,6 @@ export function getSecret(
   if (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/src/starter.ts

@@ -389,8 +389,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/src/step-exec.ts

@@ -15,6 +15,7 @@ import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { HookInput, McpServerConfig, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import { CACHE_READ_MULTIPLIER, CACHE_WRITE_MULTIPLIER } from "./catalog.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
 import { spawn } from "node:child_process";
@@ -25,6 +26,26 @@ import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-sc
 import { CallCounter, limitKeysFor, type Limits } from "./limits.ts";
 import { classifyCall, podAt, readPodEvents, type BrowserPodOutcome, type CallKind, 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 function usageFromSdk(u: Record<string, number | undefined>): ExecUsage {
+  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,
+  };
+}
+
 export interface ExecOutcome {
   status: "completed" | "failed";
   result: string | null;
@@ -39,8 +60,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
@@ -201,18 +226,15 @@ export function knownPrice(model: string | undefined): { input: number; output:
   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
@@ -762,17 +784,10 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       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 as unknown as Record<string, number | undefined>;
-        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 as unknown as Record<string, number | undefined>);
       }
     }
   }
@@ -790,16 +805,18 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // 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: ExecUsage = { 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/src/store.ts

@@ -369,7 +369,14 @@ export function saveWorkspace(
   files: DeployFile[],
   /** Attribution for the revision this save records. A deploy passes the
    *  commit, which becomes the revision's id. */
-  meta: ChangeMeta & { commit?: string | null } = {},
+  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;
+  } = {},
 ) {
   if (files.length > 500) throw new Error("too many files");
   for (const f of files) {
@@ -424,8 +431,6 @@ export function saveWorkspace(
   // about it. Before this, every deploy silently erased everything the agents
   // had learned.
   const shipped = new Set(files.map((f) => path.normalize(f.path)));
-  const isAgentOwned = (rel: string) => keptOnDeploy(rel, shipped);
-
   // What is there now, for the revision: every editable file's content
   // before this save replaces the tree.
   const before = new Map<string, string>();
@@ -439,6 +444,8 @@ export function saveWorkspace(
     }
   }
 
+  const isAgentOwned = (rel: string) => keptOnDeploy(rel, shipped) || (meta.keepUntracked === true && !before.has(rel) && !shipped.has(rel));
+
   const snapshot = fs.existsSync(dir) ? fs.mkdtempSync(path.join(dataRoot(), ".keep-")) : null;
   const preserved: string[] = [];
   if (snapshot) {
@@ -446,9 +453,13 @@ export function saveWorkspace(
       const rel = String(entry).split(path.sep).join("/");
       const from = path.join(dir, rel);
       try {
-        if (!fs.statSync(from).isFile() || !isAgentOwned(rel)) continue;
+        // lstat, never stat: a link is never followed. An agent folder's link
+        // to a file outside the workspace was copied in as that file's
+        // contents — on a restore with keepUntracked, any such link
+        // (Codex, 18 Oct 2026).
+        if (!fs.lstatSync(from).isFile() || !isAgentOwned(rel)) continue;
       } catch {
-        continue; // a broken link or a file that vanished mid-deploy
+        continue; // a file that vanished mid-deploy
       }
       const to = path.join(snapshot, rel);
       fs.mkdirSync(path.dirname(to), { recursive: true });
@@ -2095,7 +2106,7 @@ export function mayApprove(
 
 /** A live run of this flow — the fact overlap: decisions are made on. */
 export function flowHasLiveRun(tenant: string, workspace: string, flowName: string): boolean {
-  return listRuns(tenant, workspace).some(
+  return listRunSummaries(tenant, workspace).some(
     (r) => r.flow === flowName && (r.status === "running" || r.status === "queued" || r.status === "awaiting-approval"),
   );
 }
@@ -2396,10 +2407,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;
@@ -2460,12 +2467,6 @@ export function listWorkspaces(tenant: string): WorkspaceSummary[] {
         }
       }
       const runsDir = path.join(pDir, "runs");
-      let preview: WorkspaceSummary["preview"];
-      try {
-        preview = JSON.parse(fs.readFileSync(path.join(dir, `.${name}.preview.json`), "utf8"));
-      } catch {
-        // not a preview
-      }
       return {
         name,
         description,
@@ -2473,7 +2474,6 @@ export function listWorkspaces(tenant: string): WorkspaceSummary[] {
         flows: listFlows(tenant, name).length,
         deployedAt: fs.statSync(pDir).mtime.toISOString(),
         runCount: fs.existsSync(runsDir) ? fs.readdirSync(runsDir).filter((f) => f.endsWith(".json") && !f.startsWith(".")).length : 0,
-        ...(preview ? { preview } : {}),
       };
     })
     .sort((a, b) => b.deployedAt.localeCompare(a.deployedAt));
@@ -2709,7 +2709,7 @@ export function writeWorkspaceFile(
 }
 
 /** Tell the platform, and never let its listener fail a write. */
-function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete") {
+function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "delete") {
   try {
     platform.workspaceChanged(tenant, workspace, why);
   } catch {
@@ -3102,7 +3102,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;
@@ -3120,15 +3120,84 @@ export interface StepAttempt {
  *  billing reads null as zero, not as "unknown, charge something". */
 export function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs"> {
   const costs = tries.map((t) => t.costUsd).filter((c): c is number => typeof c === "number");
-  const toks = tries.map((t) => t.tokens).filter((t): t is { input: number; output: number } => !!t);
+  const toks = tries.map((t) => t.tokens).filter((t): t is TokenUsage => !!t);
   const secs = tries.map((t) => t.computeSecs).filter((c): c is number => typeof c === "number");
   return {
     costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
-    tokens: toks.length ? toks.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output }), { input: 0, output: 0 }) : null,
+    tokens: toks.length ? sumTokens(toks) : null,
     computeSecs: secs.length ? secs.reduce((a, b) => a + b, 0) : null,
   };
 }
 
+/**
+ * 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 function tokensOf(usage: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number } | null | undefined): TokenUsage | null {
+  if (!usage) return null;
+  return {
+    input: usage.inputTokens,
+    output: usage.outputTokens,
+    cacheRead: usage.cacheReadTokens ?? 0,
+    cacheWrite: usage.cacheWriteTokens ?? 0,
+  };
+}
+
+/** 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 function sumTokens(list: readonly TokenUsage[]): TokenUsage {
+  const out: TokenUsage = { input: 0, output: 0 };
+  for (const t of list) {
+    out.input += t.input;
+    out.output += t.output;
+    if (t.cacheRead !== undefined || t.cacheWrite !== undefined) {
+      out.cacheRead = (out.cacheRead ?? 0) + (t.cacheRead ?? 0);
+      out.cacheWrite = (out.cacheWrite ?? 0) + (t.cacheWrite ?? 0);
+    }
+  }
+  return out;
+}
+
+/** 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 function cacheHitRate(t: TokenUsage | null | undefined): number | null {
+  if (!t || t.cacheRead === undefined) return null;
+  return t.input > 0 ? Math.min(1, t.cacheRead / t.input) : 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 function measuredHitRate(list: readonly (TokenUsage | null | undefined)[]): number | null {
+  let read = 0;
+  let all = 0;
+  for (const t of list) {
+    if (!t || t.cacheRead === undefined) continue;
+    read += t.cacheRead;
+    all += t.input;
+  }
+  return all > 0 ? read / all : null;
+}
+
+/** A run's token counts, summed over its steps; null when no step reported any. */
+export function runTokens(run: { steps: readonly { tokens?: TokenUsage | null }[] }): TokenUsage | null {
+  const toks = run.steps.map((s) => s.tokens).filter((t): t is TokenUsage => !!t);
+  return toks.length ? sumTokens(toks) : null;
+}
+
 export interface StepRecord {
   agent: string;
   instruction: string;
@@ -3291,6 +3360,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
@@ -3301,7 +3376,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
@@ -3512,6 +3587,23 @@ export function writeRun(tenant: string, workspace: string, run: RunRecord) {
   noteRunWritten(path.dirname(p), run, p);
 }
 
+/**
+ * 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 function liveRuns(tenant: string, workspace: string): RunRecord[] {
+  const out: RunRecord[] = [];
+  for (const s of listRunSummaries(tenant, workspace)) {
+    if (!LIVE_STATUSES.has(s.status)) continue;
+    const run = readRun(tenant, workspace, s.id);
+    if (run) out.push(run);
+  }
+  return out;
+}
+
 // Every run in an account, each tagged with the workspace it belongs to —
 // the observability surface.
 export interface RunWithWorkspace extends RunRecord {
@@ -3565,7 +3657,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. */
@@ -3603,7 +3695,18 @@ export interface RunSummary {
 interface RunIndexRow extends RunSummary {
   /** mtime of the record this row was made from; a moved mtime means re-read. */
   mtimeMs: number;
+  /** mtime, inode and size together (fileStamp) — what freshness is decided
+   *  on now. A row from before it has none and is re-read once. */
+  stamp?: string;
 }
+
+/**
+ * Which version of a file this is. mtime alone missed a rewrite inside one
+ * mtime tick (coarse on some NFS servers), leaving a stale row that the
+ * sweeps act on; every write here is a rename to a new file, so the inode
+ * moves on each write whatever the clock says, and the size usually does.
+ */
+const fileStamp = (st: fs.Stats) => `${st.mtimeMs}:${st.ino}:${st.size}`;
 interface RunIndex {
   v: 1;
   runs: Record<string, RunIndexRow>;
@@ -3668,23 +3771,23 @@ export function runFromSummary(s: RunSummary): RunRecord {
   };
 }
 
-const runIndexCache = new Map<string, { index: RunIndex; mtimeMs: number }>();
+const runIndexCache = new Map<string, { index: RunIndex; stamp: string }>();
 
 function readRunIndex(dir: string): RunIndex | null {
   const file = path.join(dir, RUN_INDEX);
-  let mtimeMs: number;
+  let stamp: string;
   try {
-    mtimeMs = fs.statSync(file).mtimeMs;
+    stamp = fileStamp(fs.statSync(file));
   } catch {
     runIndexCache.delete(dir);
     return null;
   }
   const cached = runIndexCache.get(dir);
-  if (cached && cached.mtimeMs === mtimeMs) return cached.index;
+  if (cached && cached.stamp === stamp) return cached.index;
   try {
     const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as RunIndex;
     if (parsed?.v !== 1 || typeof parsed.runs !== "object" || !parsed.runs) return null;
-    runIndexCache.set(dir, { index: parsed, mtimeMs });
+    runIndexCache.set(dir, { index: parsed, stamp });
     return parsed;
   } catch {
     return null;
@@ -3697,14 +3800,17 @@ function writeRunIndex(dir: string, index: RunIndex) {
   fs.writeFileSync(tmp, JSON.stringify(index));
   fs.renameSync(tmp, file);
   try {
-    runIndexCache.set(dir, { index, mtimeMs: fs.statSync(file).mtimeMs });
+    runIndexCache.set(dir, { index, stamp: fileStamp(fs.statSync(file)) });
   } catch {
     runIndexCache.delete(dir);
   }
 }
 
-const sameRow = (a: RunIndexRow | undefined, b: RunSummary) =>
-  !!a && JSON.stringify({ ...a, mtimeMs: 0 }) === JSON.stringify({ ...b, mtimeMs: 0 });
+const sameRow = (a: RunIndexRow | undefined, b: RunSummary) => {
+  if (!a) return false;
+  const { mtimeMs: _m, stamp: _s, ...row } = a;
+  return JSON.stringify(row) === JSON.stringify(b);
+};
 
 /** writeRun just saved `run` at `file`: bring its row up to date. The file
  *  is rewritten only when the row's content moved — a live step appends an
@@ -3717,7 +3823,8 @@ function noteRunWritten(dir: string, run: RunRecord, file: string) {
     if (!index) return; // no index yet — the first reader builds it whole
     const row = summarizeRun(run);
     if (sameRow(index.runs[run.id], row)) return;
-    index.runs[run.id] = { ...row, mtimeMs: fs.statSync(file).mtimeMs };
+    const st = fs.statSync(file);
+    index.runs[run.id] = { ...row, mtimeMs: st.mtimeMs, stamp: fileStamp(st) };
     writeRunIndex(dir, index);
   } catch {
     // the index is a cache; the record is the truth and it is already on disk
@@ -3752,17 +3859,18 @@ export function listRunSummaries(tenant: string, workspace: string): RunSummary[
     if (!f.endsWith(".json") || f.startsWith(".")) continue;
     const id = f.slice(0, -".json".length);
     present.add(id);
-    let mtimeMs: number;
+    let st: fs.Stats;
     try {
-      mtimeMs = fs.statSync(path.join(dir, f)).mtimeMs;
+      st = fs.statSync(path.join(dir, f));
     } catch {
       continue; // pruned between the listing and the stat
     }
+    const stamp = fileStamp(st);
     const row = index.runs[id];
-    if (row && row.mtimeMs === mtimeMs) continue;
+    if (row && row.stamp === stamp) continue;
     try {
       const run = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")) as RunRecord;
-      index.runs[id] = { ...summarizeRun(run), mtimeMs };
+      index.runs[id] = { ...summarizeRun(run), mtimeMs: st.mtimeMs, stamp };
       changed = true;
     } catch {
       // a torn or foreign file is not a run; leave whatever row it had
@@ -3781,7 +3889,7 @@ export function listRunSummaries(tenant: string, workspace: string): RunSummary[
     }
   }
   return Object.values(index.runs)
-    .map(({ mtimeMs: _m, ...row }) => row)
+    .map(({ mtimeMs: _m, stamp: _s, ...row }) => row)
     .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
 

package/src/tool-loop.ts

@@ -34,9 +34,12 @@ export interface LoopTool {
 }
 
 export interface LoopUsage {
-  /** Everything sent, cache reads and writes included. */
+  /** Everything sent, cache reads and writes included; the two cache
+   *  fields say how much of it the prompt cache served or stored. */
   inputTokens: number;
   outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
   costUsd: number;
 }
 
@@ -221,6 +224,8 @@ export async function runToolLoop(o: LoopOptions): Promise<LoopResult> {
         usage = {
           inputTokens: models.reduce((n, m) => n + (m.inputTokens ?? 0) + (m.cacheReadInputTokens ?? 0) + (m.cacheCreationInputTokens ?? 0), 0),
           outputTokens: models.reduce((n, m) => n + (m.outputTokens ?? 0), 0),
+          cacheReadTokens: models.reduce((n, m) => n + (m.cacheReadInputTokens ?? 0), 0),
+          cacheWriteTokens: models.reduce((n, m) => n + (m.cacheCreationInputTokens ?? 0), 0),
           costUsd,
         };
         if (message.subtype === "success") {