@foldrun/core 2.0.0 → 2.1.0

package/dist/src/translator.js

@@ -22,7 +22,9 @@
 // and their results, streaming — and drops what a Chat-Completions endpoint
 // has no word for (cache_control, top_k, server-side tools, thinking on
 // endpoints that lack reasoning_effort). Anything dropped is said once in
-// the run trace. The translation is pure functions over JSON so the tests
+// the run trace. Those endpoints cache prompt prefixes on their own side;
+// the cached share they report comes back as cache_read_input_tokens, so a
+// step's record says how much of its context was re-read. The translation is pure functions over JSON so the tests
 // can drive every mapping without a network; the server around them is a
 // few dozen lines.
 import http from "node:http";
@@ -31,6 +33,33 @@ import { PROTECTED_PARAMS } from "./providers.js";
 import { viaEgress } from "./egress.js";
 import { trimSlashes } from "./paths.js";
 import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.js";
+/**
+ * An OpenAI-shaped usage object as Anthropic's: fresh input, cached input,
+ * output. Both OpenAI shapes count the cached part INSIDE the prompt total
+ * (Chat's prompt_tokens_details.cached_tokens, Responses'
+ * input_tokens_details.cached_tokens; DeepSeek says prompt_cache_hit_tokens),
+ * so it is taken out of input here or the step would count it twice.
+ */
+export function anthropicUsage(u, wire) {
+    if (!u)
+        return { input: 0, cached: 0, output: 0 };
+    const total = Number((wire === "chat" ? u.prompt_tokens : u.input_tokens) ?? 0);
+    const details = (wire === "chat" ? u.prompt_tokens_details : u.input_tokens_details);
+    const raw = Number(details?.cached_tokens ?? u.prompt_cache_hit_tokens ?? 0);
+    const cached = Number.isFinite(raw) ? Math.max(0, Math.min(raw, total)) : 0;
+    return {
+        input: total - cached,
+        cached,
+        output: Number((wire === "chat" ? u.completion_tokens : u.output_tokens) ?? 0),
+    };
+}
+function usageBlock(u) {
+    return {
+        input_tokens: u?.input ?? 0,
+        output_tokens: u?.output ?? 0,
+        ...(u && u.cached > 0 ? { cache_read_input_tokens: u.cached } : {}),
+    };
+}
 function dropped() {
     const seen = new Set();
     return {
@@ -466,10 +495,7 @@ export function fromChatCompletion(res, requestedModel, stopSequences) {
         content,
         stop_reason: stop.reason,
         stop_sequence: stop.sequence,
-        usage: {
-            input_tokens: Number(usage.prompt_tokens ?? 0),
-            output_tokens: Number(usage.completion_tokens ?? 0),
-        },
+        usage: usageBlock(anthropicUsage(usage, "chat")),
     };
 }
 /**
@@ -532,7 +558,7 @@ export class StreamTranslator {
         const out = this.start(chunk);
         const u = chunk.usage;
         if (u && (u.prompt_tokens !== undefined || u.completion_tokens !== undefined)) {
-            this.usage = { input: Number(u.prompt_tokens ?? 0), output: Number(u.completion_tokens ?? 0) };
+            this.usage = anthropicUsage(u, "chat");
         }
         const choice = (chunk.choices ?? [])[0];
         if (!choice)
@@ -609,7 +635,7 @@ export class StreamTranslator {
         out.push(this.event("message_delta", {
             type: "message_delta",
             delta: { stop_reason: stop.reason, stop_sequence: stop.sequence },
-            usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+            usage: usageBlock(this.usage),
         }));
         out.push(this.event("message_stop", { type: "message_stop" }));
         return out;
@@ -648,10 +674,7 @@ export function fromResponses(res, requestedModel) {
         content,
         stop_reason: stop,
         stop_sequence: null,
-        usage: {
-            input_tokens: Number(usage.input_tokens ?? 0),
-            output_tokens: Number(usage.output_tokens ?? 0),
-        },
+        usage: usageBlock(anthropicUsage(usage, "responses")),
     };
 }
 /**
@@ -768,7 +791,7 @@ export class ResponsesStreamTranslator {
             const r = ev.response ?? {};
             const u = r.usage;
             if (u)
-                this.usage = { input: Number(u.input_tokens ?? 0), output: Number(u.output_tokens ?? 0) };
+                this.usage = anthropicUsage(u, "responses");
             const reason = r.incomplete_details?.reason;
             if (typeof reason === "string")
                 this.incomplete = reason;
@@ -790,7 +813,7 @@ export class ResponsesStreamTranslator {
         out.push(this.event("message_delta", {
             type: "message_delta",
             delta: { stop_reason: reason, stop_sequence: null },
-            usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+            usage: usageBlock(this.usage),
         }));
         out.push(this.event("message_stop", { type: "message_stop" }));
         return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/catalog.ts

@@ -245,13 +245,29 @@ export function clampEffort(
 export function catalogCost(
   catalog: Catalog | null,
   modelId: string,
-  usage: { inputTokens: number; outputTokens: number },
+  usage: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number },
 ): number | null {
   const m = findModel(catalog, modelId);
   if (!m || m.promptPrice == null || m.completionPrice == null) return null;
-  return usage.inputTokens * m.promptPrice + usage.outputTokens * m.completionPrice;
+  // A catalogue quotes one input price; cache traffic is priced off it with
+  // the multipliers every gateway that bills for caching has copied from
+  // Anthropic. Before the counts were split (18 Oct 2026) every cached
+  // token was billed here at the full rate — a long cached step cost ten
+  // times its price on the ledger.
+  // inputTokens is all input; the cache fields are parts of it.
+  const read = usage.cacheReadTokens ?? 0;
+  const written = usage.cacheWriteTokens ?? 0;
+  const fresh = Math.max(0, usage.inputTokens - read - written);
+  const input = fresh + written * CACHE_WRITE_MULTIPLIER + read * CACHE_READ_MULTIPLIER;
+  return input * m.promptPrice + usage.outputTokens * m.completionPrice;
 }
 
+/** Anthropic's cache multipliers over the input price: a write costs a
+ *  quarter more than fresh input, a read a tenth of it. One source for the
+ *  mid-step ceiling (priceTurn) and the record's repricing (catalogCost). */
+export const CACHE_WRITE_MULTIPLIER = 1.25;
+export const CACHE_READ_MULTIPLIER = 0.1;
+
 /** Catalogue entries as completion items: price per MTok, context, and the
  *  one capability that decides agent-worthiness. Tool-capable models first —
  *  on an agent platform they are almost always what the author wants. */

package/src/deploy.ts

@@ -26,6 +26,7 @@ import {
   keptOnDeploy,
   workspaceDir,
   listRunSummaries,
+  listWorkspaceFiles,
   parseFlow,
   parseToolDef,
   WORKSPACE_DIRS,
@@ -460,7 +461,7 @@ export function runsInFlight(tenant: string, workspace: string): string[] {
 }
 
 /** What a deploy would do, without doing it. */
-export function planDeploy(tenant: string, workspace: string, files: DeployFile[]): DeployPlan {
+export function planDeploy(tenant: string, workspace: string, files: DeployFile[], opts: { keepUntracked?: boolean } = {}): DeployPlan {
   const dir = workspaceDir(tenant, workspace);
   const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
 
@@ -498,7 +499,10 @@ export function planDeploy(tenant: string, workspace: string, files: DeployFile[
   // memory, the platform's own files. Reporting these as removals would be
   // a lie, and the alarming kind; one predicate serves both.
   const shippedPaths = new Set(shipped.keys());
-  const removed = [...present].filter((rel) => !shipped.has(rel) && !keptOnDeploy(rel, shippedPaths));
+  // keepUntracked (a restore): what is not editable source stays, as
+  // saveWorkspace keeps it — see its meta.keepUntracked.
+  const tracked = opts.keepUntracked ? new Set(listWorkspaceFiles(tenant, workspace)) : null;
+  const removed = [...present].filter((rel) => !shipped.has(rel) && !keptOnDeploy(rel, shippedPaths) && (!tracked || tracked.has(rel)));
 
   return {
     files,
@@ -528,6 +532,9 @@ export interface DeployOptions {
    * no window between the check and the swap. Absent: no check, as before.
    */
   expectRemoved?: string[];
+  /** Keep what is not editable source (planDeploy, saveWorkspace): a
+   *  restore takes history's tree, and history tracks source only. */
+  keepUntracked?: boolean;
 }
 
 /**
@@ -547,7 +554,7 @@ export function deployWorkspace(
   assertSafeName(tenant, "tenant");
   assertSafeName(workspace, "workspace");
 
-  const plan = planDeploy(tenant, workspace, files);
+  const plan = planDeploy(tenant, workspace, files, { keepUntracked: opts.keepUntracked });
   const blocked = plan.blockedBy.length > 0 && !opts.force;
   if (plan.issues.length > 0 || blocked) {
     return { ...plan, applied: false, commit: null, preserved: 0 };
@@ -560,7 +567,7 @@ export function deployWorkspace(
     }
   }
 
-  const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
+  const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message, keepUntracked: opts.keepUntracked });
   const commit = opts.commit ?? null;
   if (commit) writeDeployedCommit(tenant, workspace, commit);
   return { ...plan, applied: true, commit, preserved }; // saveWorkspace told the platform

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/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";
@@ -184,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;
@@ -1216,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"

package/src/runner.ts

@@ -75,6 +75,7 @@ import {
   type StepRecord,
   type StepAttempt,
   sumAttempts,
+  tokensOf,
   parseSchemaText,
   STORAGE_DIR,
   adoptLegacyVersionKey,
@@ -1712,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
@@ -2064,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);
@@ -2080,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();
@@ -2828,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),
@@ -2872,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));
@@ -3076,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}`);
     }

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 });
@@ -3091,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;
@@ -3109,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;
@@ -3296,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
@@ -3577,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. */

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") {