@foldrun/core 2.0.0 → 2.1.0

package/dist/src/catalog.d.ts

@@ -83,7 +83,14 @@ export declare function clampEffort(catalog: Catalog | null, modelId: string, ef
 export declare function catalogCost(catalog: Catalog | null, modelId: string, usage: {
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
 }): number | null;
+/** 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 declare const CACHE_WRITE_MULTIPLIER = 1.25;
+export declare 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/dist/src/catalog.js

@@ -200,8 +200,23 @@ export function catalogCost(catalog, modelId, usage) {
     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/dist/src/deploy.d.ts

@@ -97,7 +97,9 @@ export declare function deployIssues(files: DeployFile[]): DeployIssue[];
  */
 export declare function runsInFlight(tenant: string, workspace: string): string[];
 /** What a deploy would do, without doing it. */
-export declare function planDeploy(tenant: string, workspace: string, files: DeployFile[]): DeployPlan;
+export declare function planDeploy(tenant: string, workspace: string, files: DeployFile[], opts?: {
+    keepUntracked?: boolean;
+}): DeployPlan;
 export interface DeployOptions {
     /** The commit these files came from, recorded so the dashboard can show it. */
     commit?: string | null;
@@ -115,6 +117,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;
 }
 /**
  * Deploy a file list to a workspace, if it checks out.

package/dist/src/deploy.js

@@ -20,7 +20,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { saveWorkspace, keptOnDeploy, workspaceDir, listRunSummaries, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
+import { saveWorkspace, keptOnDeploy, workspaceDir, listRunSummaries, listWorkspaceFiles, parseFlow, parseToolDef, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
 import { lintFlow } from "./flow-lint.js";
 import { refNames } from "./refs.js";
 import matter from "gray-matter";
@@ -438,7 +438,7 @@ export function runsInFlight(tenant, workspace) {
         .map((r) => r.id);
 }
 /** What a deploy would do, without doing it. */
-export function planDeploy(tenant, workspace, files) {
+export function planDeploy(tenant, workspace, files, opts = {}) {
     const dir = workspaceDir(tenant, workspace);
     const shipped = new Map(files.map((f) => [path.normalize(f.path), f.content]));
     const present = new Set();
@@ -480,7 +480,10 @@ export function planDeploy(tenant, workspace, files) {
     // 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,
         added: added.sort(),
@@ -502,7 +505,7 @@ export function planDeploy(tenant, workspace, files) {
 export function deployWorkspace(tenant, workspace, files, opts = {}) {
     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 };
@@ -514,7 +517,7 @@ export function deployWorkspace(tenant, workspace, files, opts = {}) {
             return { ...plan, applied: false, commit: null, preserved: 0, unexpectedRemovals };
         }
     }
-    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);

package/dist/src/model-credential.js

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

package/dist/src/model-env.js

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

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

@@ -1,7 +1,7 @@
 import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type ApiSpec, type Effort } from "./store.ts";
-import type { EventExtra } from "./step-exec.ts";
+import type { EventExtra, ExecUsage } from "./step-exec.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import { type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
@@ -146,10 +146,7 @@ export interface ContainerStepOutcome {
     /** The parsed JSON of an `output: json` step, crossing back as a value. */
     data?: unknown;
     costUsd: number | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-    } | null;
+    usage?: ExecUsage | null;
     /** Every turn priced at its own model, when sub-agents ran on others —
      *  see ExecOutcome.turnsCostUsd. */
     turnsCostUsd?: number;

package/dist/src/run-container.js

@@ -1068,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"
                     ? {

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, liveRuns, 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));
@@ -2870,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())

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;
 };
@@ -948,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;
@@ -967,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;
@@ -1154,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
@@ -1319,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. */

package/dist/src/store.js

@@ -385,7 +385,6 @@ meta = {}) {
     // 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) => 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();
@@ -399,6 +398,7 @@ meta = {}) {
             }
         }
     }
+    const isAgentOwned = (rel) => 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 = [];
     if (snapshot) {
@@ -406,11 +406,15 @@ meta = {}) {
             const rel = String(entry).split(path.sep).join("/");
             const from = path.join(dir, rel);
             try {
-                if (!fs.statSync(from).isFile() || !isAgentOwned(rel))
+                // 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 });
@@ -2573,10 +2577,62 @@ export function sumAttempts(tries) {
     const secs = tries.map((t) => t.computeSecs).filter((c) => 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 record's shape from what a step reports (ExecOutcome.usage). */
+export function tokensOf(usage) {
+    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) {
+    const out = { 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) {
+    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) {
+    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) {
+    const toks = run.steps.map((s) => s.tokens).filter((t) => !!t);
+    return toks.length ? sumTokens(toks) : null;
+}
 export function runFilePath(tenant, workspace, runId) {
     assertSafeName(runId, "run id");
     return path.join(workspaceDir(tenant, workspace), "runs", `${runId}.json`);

package/dist/src/tool-loop.d.ts

@@ -13,9 +13,12 @@ export interface LoopTool {
     run: (args: Record<string, string | undefined>) => Promise<string> | string;
 }
 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;
 }
 export interface LoopResult {

package/dist/src/tool-loop.js

@@ -170,6 +170,8 @@ export async function runToolLoop(o) {
                 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") {

package/dist/src/translator.d.ts

@@ -1,4 +1,16 @@
 type Json = Record<string, unknown>;
+/**
+ * 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 declare function anthropicUsage(u: Json | undefined, wire: TranslatorWire): {
+    input: number;
+    cached: number;
+    output: number;
+};
 export type TranslatorWire = "chat" | "responses";
 export interface TranslatorSpec {
     /** The provider's base, e.g. https://api.openai.com/v1 — `/chat/completions`