@foldrun/core 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # foldrun
 
+[![ci](https://github.com/foldrun-io/foldrun-core/actions/workflows/ci.yml/badge.svg)](https://github.com/foldrun-io/foldrun-core/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@foldrun/core)](https://www.npmjs.com/package/@foldrun/core)
+[![licence](https://img.shields.io/badge/licence-Apache--2.0-blue)](LICENSE)
+
 **Agents are just folders. Write them, check them, run them.**
 
 An agent is a folder. Its instructions, skills, knowledge, memory, tools and

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, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
+import { saveWorkspace, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, notifyWorkspaceChanged, } from "./store.js";
 import { conformanceIssues } from "./okf.js";
 import { repoDir } from "./gitrepo.js";
 /** Directories a deploy never reads out of a source tree. */
@@ -307,6 +307,8 @@ export function writePushNote(tenant, workspace, note) {
     catch {
         // The note is a record, not the deploy. Losing it must not fail a push.
     }
+    // A push waiting on a run is the scheduler's to apply; tell it there is one.
+    notifyWorkspaceChanged(tenant, workspace, "push");
 }
 /**
  * A push whose deploy was refused only because a run was in flight is not a
@@ -353,7 +355,7 @@ export function deployWorkspace(tenant, workspace, files, opts = {}) {
     const commit = opts.commit ?? null;
     if (commit)
         writeDeployedCommit(tenant, workspace, commit);
-    return { ...plan, applied: true, commit, preserved };
+    return { ...plan, applied: true, commit, preserved }; // saveWorkspace told the platform
 }
 // Which commit a workspace is running.
 //

package/dist/src/platform.d.ts

@@ -24,6 +24,16 @@ export interface PlatformHooks {
     /** The egress proxy — a per-step lease that keeps credentials out of the
      *  sandbox. Default: none, and the runner materialises as it always did. */
     egress: EgressHooks;
+    /** A workspace's files changed — written, deployed, pushed, or the
+     *  workspace deleted. What a scheduler that keeps flows in memory rather
+     *  than re-reading every workspace each tick needs to hear. Default:
+     *  nothing — locally the scheduler reads the disk. Never throws. */
+    workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+    /** Can a step in this isolation mode be re-attached to after the driver
+     *  that started it is gone? True means an orphaned step with a `sandbox`
+     *  on its record is resumed rather than destroyed and run again. Default:
+     *  nothing is. */
+    sandboxResumable(kind: string): boolean;
 }
 export declare const platform: PlatformHooks;
 /** Install the platform's implementations. Partial: what is not given keeps its local default. */

package/dist/src/platform.js

@@ -24,6 +24,8 @@ const local = {
     previewSourceOf: () => null,
     tenantKey: () => null,
     egress: { lease: async () => null },
+    workspaceChanged() { },
+    sandboxResumable: () => false,
 };
 // One object per PROCESS, not per module instance. A bundler that compiles
 // the boot file and each route handler separately (Next does) gives every

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

@@ -78,6 +78,10 @@ export interface StepActuals {
 export interface ContainerStepOutcome {
     status: "completed" | "failed";
     result: string | null;
+    /** Why the sandbox ended when the step did not: what the cluster said
+     *  (OOMKilled, Evicted, the pod gone). Absent when the driver finished
+     *  and said so itself. A retry policy reads this. */
+    reason?: string | null;
     /** The model's final text block — see StepRecord.conclusion. Crosses the
      *  boundary with the rest of the outcome; the driver spreads it. */
     conclusion?: string | null;
@@ -120,7 +124,14 @@ export declare function allowedBack(rel: string): boolean;
  * the step did not touch it, so it is not ours to write back. Concurrent
  * edits survive, and a step that genuinely changed a file still wins.
  */
-export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string): string[];
+/**
+ * What a workspace copy looked like when it went in: the sha256 of every
+ * file the step could hand back. Small enough to ride into the sandbox
+ * beside the input, so a driver that inherits the step can tell what the
+ * step changed without the staging copy the first driver held in /tmp.
+ */
+export declare function hashTree(dir: string): Record<string, string>;
+export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string | Record<string, string>): string[];
 /**
  * Where the driver builds venvs and npm prefixes, as an absolute path *inside*
  * the runner. Fixed, and it has to be: a venv bakes its own absolute path into
@@ -185,6 +196,18 @@ export interface RunInContainerArgs {
     runId?: string;
     /** The reservation class — which limits this step's sandbox holds. */
     size?: "small" | "large" | "heavy";
+    /** Re-attach to a sandbox a previous driver started, instead of creating
+     *  one: its handle, and how many output lines that driver had applied.
+     *  The executor replays nothing before `consumed`, and reads the step's
+     *  files back from the sandbox's own copy-in snapshot. */
+    resume?: {
+        ref: string;
+        consumed: number;
+    } | null;
+    /** Called by an executor that can be resumed: when its sandbox exists
+     *  (consumed 0), and before each output line it applies. The runner
+     *  records these on the step, so the next driver knows where to attach. */
+    checkpoint?: (ref: string, consumed: number) => void;
 }
 /** The limits a size class reserves. Large is the install's configured
  *  limits unchanged, so existing installs bill and behave identically;

package/dist/src/run-container.js

@@ -95,6 +95,34 @@ export function allowedBack(rel) {
  * the step did not touch it, so it is not ours to write back. Concurrent
  * edits survive, and a step that genuinely changed a file still wins.
  */
+/**
+ * What a workspace copy looked like when it went in: the sha256 of every
+ * file the step could hand back. Small enough to ride into the sandbox
+ * beside the input, so a driver that inherits the step can tell what the
+ * step changed without the staging copy the first driver held in /tmp.
+ */
+export function hashTree(dir) {
+    const out = {};
+    const walk = (d) => {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            const abs = path.join(d, entry.name);
+            const rel = path.relative(dir, abs).replaceAll("\\", "/");
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (allowedBack(rel + "/"))
+                    walk(abs);
+                continue;
+            }
+            if (!allowedBack(rel))
+                continue;
+            out[rel] = crypto.createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+        }
+    };
+    if (fs.existsSync(dir))
+        walk(dir);
+    return out;
+}
 export function applyContainerChanges(hostWs, containerWs, baseline) {
     const applied = [];
     const walk = (dir) => {
@@ -119,11 +147,16 @@ export function applyContainerChanges(hostWs, containerWs, baseline) {
             const next = fs.readFileSync(abs);
             // Untouched by this step: whatever the host says now is more current
             // than what we handed in, including a change made while it ran.
-            if (baseline) {
+            if (typeof baseline === "string") {
                 const was = path.join(baseline, rel);
                 if (fs.existsSync(was) && fs.readFileSync(was).equals(next))
                     continue;
             }
+            else if (baseline) {
+                const was = baseline[rel.replaceAll("\\", "/")];
+                if (was && was === crypto.createHash("sha256").update(next).digest("hex"))
+                    continue;
+            }
             const target = path.join(hostWs, rel);
             if (fs.existsSync(target) && fs.readFileSync(target).equals(next))
                 continue;

package/dist/src/runner.d.ts

@@ -206,7 +206,7 @@ export interface Reconciliation {
  * outlives any process. A run whose person already answered is not waiting,
  * and is picked back up — see below.
  */
-export declare function reconcileRuns(tenant: string, now?: number): Reconciliation[];
+export declare function reconcileRuns(tenant: string, now?: number, live?: ReadonlySet<string>): Reconciliation[];
 /**
  * The same, for every account this installation holds.
  *
@@ -214,7 +214,7 @@ export declare function reconcileRuns(tenant: string, now?: number): Reconciliat
  * one hard-coded account left every other account's interrupted runs marked
  * `running` forever, with no process left to finish them.
  */
-export declare function reconcileAllRuns(now?: number): Reconciliation[];
+export declare function reconcileAllRuns(now?: number, live?: ReadonlySet<string>): Reconciliation[];
 /**
  * Wait for a run to stop being in progress.
  *

package/dist/src/runner.js

@@ -5,7 +5,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { executeStep, extractJson, stepCeiling } from "./step-exec.js";
+import { knownPrice, executeStep, extractJson, stepCeiling } from "./step-exec.js";
 import { eventUrl } from "./webhook.js";
 import { runStepInContainer, sizeLimits, killRunSandboxes } from "./run-container.js";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute } from "./egress.js";
@@ -1158,7 +1158,10 @@ stepBudgetUsd = null) {
         // step: the generic HTTP tool still works without the typed ones.
         for (const w of await prefetchOpenApi(tenant, openApiSources(agentDir, tenant)))
             push("error", `openapi: ${w}`);
-        const { front, clockEnv, systemPrompt, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, translator, fallbackTranslator, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent });
+        const { front, clockEnv, systemPrompt, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size: agentSize, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, translator, fallbackTranslator, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent });
+        // A retry that moved the step up a class (an evicted or OOM-killed
+        // attempt) wins over the agent's own `size:` for the attempts after.
+        const size = step.sizeUp ?? agentSize;
         // oauth2 secrets become live access tokens here — the one async moment
         // in secret resolution, at the last host-side point before anything is
         // injected or substituted. The refresh recipes never leave this process:
@@ -1289,6 +1292,11 @@ stepBudgetUsd = null) {
                 push("info", fitted.note);
             effort = fitted.effort;
         }
+        // No catalogue — the platform's own Anthropic key, or a gateway that
+        // publishes no prices — but the model's NAME is often enough. Without
+        // this the in-pod meter priced haiku and sonnet at Opus rates and a
+        // step was stopped at up to fifteen times what it had spent.
+        tokenPrice ??= knownPrice(wireModel);
         fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
         fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
         // Expose the workspace's shared scripts/ as ./shared so every agent reaches
@@ -1530,6 +1538,19 @@ stepBudgetUsd = null) {
                 // Stamps the sandbox, so stopping this run can destroy it.
                 runId,
                 size,
+                // Resume: a sandbox a previous driver left running, recorded on the
+                // step. Consumed once — a fresh attempt after this one (a retry, a
+                // fallback) starts its own sandbox.
+                resume: step.sandbox && step.sandbox.kind === isolation ? { ref: step.sandbox.ref, consumed: step.sandbox.consumed } : null,
+                // Checkpoint: where the executor is, on the record, so a driver
+                // that inherits this run can attach where this one left off. The
+                // executor calls it before applying each line; the line's own emit
+                // saves the record, so this only updates the fields.
+                checkpoint: (ref, consumed) => {
+                    step.sandbox = { kind: isolation, ref, consumed, since: step.sandbox?.since ?? new Date().toISOString() };
+                    if (consumed === 0)
+                        save();
+                },
             });
             // A busy provider gets another moment on the SAME supply before the
             // fallback is considered: under a fan-out, twenty steps against one
@@ -1539,6 +1560,7 @@ stepBudgetUsd = null) {
             const firstArgs = isolatedArgs(platformModelEnv());
             await lease?.commit();
             let outcome = await runIsolated(firstArgs);
+            step.sandbox = null; // whatever happens next starts its own
             for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
                 const wait = backoffMs(n, lastRefusal);
                 push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
@@ -1587,6 +1609,11 @@ stepBudgetUsd = null) {
             step.status = outcome.status;
             step.result = outcome.result;
             step.conclusion = outcome.conclusion;
+            step.sandbox = null;
+            // The cluster's word on why a sandbox ended without the driver saying
+            // so — OOMKilled, Evicted — on the record, where the retry reads it.
+            if (outcome.status === "failed" && outcome.reason)
+                push("error", `sandbox ended: ${outcome.reason}`);
             if (outcome.data !== undefined)
                 step.data = outcome.data;
             step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push);
@@ -2262,16 +2289,26 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
             // never happened, which reconcile can then never see. Reset it to
             // pending and it simply runs again; driveRun's whole contract is that
             // re-driving a partly-finished record is safe.
+            // Unless the step's sandbox outlived its driver AND the executor can
+            // re-attach to it: then the record carries the pod and how far the
+            // last driver got, runStep passes that as `resume`, and the step
+            // carries on from where it was — a deploy no longer costs the run.
             let orphaned = false;
             for (const step of run.steps) {
                 if (step.status !== "running")
                     continue;
-                orphaned = true;
+                const resumable = !!step.sandbox && platform.sandboxResumable(step.sandbox.kind);
+                if (!resumable) {
+                    orphaned = true;
+                    step.sandbox = null;
+                }
                 step.status = "pending";
                 step.events.push({
                     t: new Date().toISOString(),
                     type: "info",
-                    text: "interrupted mid-step (platform restart) — running again from the start of the step",
+                    text: resumable
+                        ? `driver changed mid-step — re-attaching to the running sandbox (${step.sandbox.ref}, ${step.sandbox.consumed} lines already applied)`
+                        : "interrupted mid-step (platform restart) — running again from the start of the step",
                 });
             }
             if (orphaned) {
@@ -2710,7 +2747,12 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 await Promise.all(launching
                     .map(async (step) => {
                     const attempts = (step.retry ?? 0) + 1;
-                    for (let attempt = 1; attempt <= attempts; attempt++) {
+                    // A step re-attaching to its sandbox is still on the attempt
+                    // that started it; a step re-run after a backoff picks up the
+                    // count it left. Only a step nobody has touched starts at 1.
+                    const interruptedInBackoff = !step.sandbox && !!step.attempts && /retrying in \d+s/.test(step.events[step.events.length - 1]?.text ?? "");
+                    const from = step.sandbox ? Math.max(1, step.attempts ?? 1) : interruptedInBackoff ? Math.min(attempts, step.attempts + 1) : 1;
+                    for (let attempt = from; attempt <= attempts; attempt++) {
                         step.attempts = attempt;
                         step.status = "running";
                         save();
@@ -2727,12 +2769,43 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         save();
                         if (run.stopRequested)
                             break;
+                        // The retry policy. An attempt the cluster ended for want of
+                        // memory or disk is retried one size class up — the same
+                        // size would end the same way. Every retry waits: 15 s, 30 s,
+                        // 1 m, 2 m, 4 m, jittered, so a provider or a site that was
+                        // struggling gets a moment, and twenty fan-out steps do not
+                        // hammer it in lock-step. The wait holds a worker slot, not
+                        // a sandbox — nothing is rented while it waits — and a stop
+                        // ends it. The step is `pending` meanwhile, so a driver that
+                        // inherits the run mid-wait simply runs the attempt.
+                        const last = [...step.events].reverse().find((e) => e.type === "error")?.text ?? "";
+                        let sizeNote = "";
+                        if (/OOMKilled|Evicted|ephemeral-storage|out of memory/i.test(last)) {
+                            const up = step.sizeUp === "large" || (!step.sizeUp && step.size === "large") ? "heavy" : step.sizeUp === "heavy" || step.size === "heavy" ? null : "large";
+                            if (up) {
+                                step.sizeUp = up;
+                                sizeNote = ` at size: ${up}`;
+                            }
+                        }
+                        const waitMs = Math.round(Math.min(retryBaseMs() * 16, retryBaseMs() * 2 ** (attempt - 1)) * (0.75 + Math.random() * 0.5));
+                        step.status = "pending";
                         step.events.push({
                             t: new Date().toISOString(),
                             type: "info",
-                            text: `attempt ${attempt} failed — retrying (${attempts - attempt} left)`,
+                            text: `attempt ${attempt} failed — retrying in ${Math.round(waitMs / 1000)}s${sizeNote} (${attempts - attempt} left)`,
                         });
                         save();
+                        const until = Date.now() + waitMs;
+                        while (Date.now() < until) {
+                            await sleep(Math.min(1000, until - Date.now()));
+                            save();
+                            if (run.stopRequested)
+                                break;
+                        }
+                        if (run.stopRequested) {
+                            step.status = "failed";
+                            break;
+                        }
                     }
                 }));
                 // on-fail: another agent takes the step over. Sequential and rare:
@@ -3051,6 +3124,9 @@ export function loadFlow(tenant, workspace, flowName) {
 // once it has been quiet for two minutes — the margin is for a record
 // written a beat before its driver registered, not a judgement about pace.
 const ABANDONED_AFTER_MS = 2 * 60 * 1000;
+/** The first retry's wait; each one after doubles it, to sixteen times
+ *  this (15 s → 4 min by default). An env, so a test can make it small. */
+const retryBaseMs = () => Number(process.env.FOLDRUN_RETRY_BASE_MS) || 15_000;
 /** The most recent moment a run showed any sign of life. */
 function lastActivity(run) {
     let latest = Date.parse(run.startedAt);
@@ -3082,12 +3158,19 @@ function lastActivity(run) {
  * outlives any process. A run whose person already answered is not waiting,
  * and is picked back up — see below.
  */
-export function reconcileRuns(tenant, now = Date.now()) {
+export function reconcileRuns(tenant, now = Date.now(), live) {
     const closed = [];
     for (const workspace of listWorkspaces(tenant)) {
         for (const summary of listRuns(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
+            // process's judgement only; a worker that boots beside a live one
+            // would otherwise close every long step its neighbour is driving.
+            // The caller says which runs those are (a heartbeated claim).
+            if (live?.has(summary.id))
+                continue;
             if (now - lastActivity(summary) < ABANDONED_AFTER_MS)
                 continue;
             // Approved, then abandoned. Approval only writes to the run record; the
@@ -3168,8 +3251,8 @@ export function reconcileRuns(tenant, now = Date.now()) {
  * one hard-coded account left every other account's interrupted runs marked
  * `running` forever, with no process left to finish them.
  */
-export function reconcileAllRuns(now = Date.now()) {
-    return listTenants().flatMap((tenant) => reconcileRuns(tenant, now));
+export function reconcileAllRuns(now = Date.now(), live) {
+    return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live));
 }
 /**
  * Wait for a run to stop being in progress.

package/dist/src/starter.js

@@ -304,6 +304,7 @@ timezone: Australia/Sydney
 model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
+priority: normal         # high | normal | low — where its runs stand in the queue
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.

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

@@ -70,16 +70,26 @@ export type EventExtra = {
     ms?: number;
     err?: boolean;
 };
-/** Conservative per-token rates for a model the catalogue cannot price —
- *  Opus-class — so a ceiling still means something on an unknown gateway. */
+/** Conservative per-token rates for a model nothing else can price — an
+ *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
+ *  still means something. Only ever reached when `knownPrice` below does
+ *  not recognise the model either. */
 export declare const FALLBACK_PRICE: {
     input: number;
     output: number;
 };
+/** What a token costs on this model, when we can say without a catalogue. */
+export declare function knownPrice(model: string | undefined): {
+    input: number;
+    output: number;
+} | null;
 /**
- * What one assistant turn cost. Cache traffic is counted as input at the
- * input rate, which over-approximates on gateways with cheaper cache reads
- * — on the money side, the honest direction to be wrong in. Pure.
+ * What one assistant turn cost, from the usage the SDK reports. Pure.
+ *
+ * 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
+ * number exists to stop a runaway step mid-turn, and wants to be close.
  */
 export declare function priceTurn(u: Record<string, number | undefined>, price: {
     input: number;

package/dist/src/step-exec.js

@@ -12,19 +12,55 @@ import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { spawn } from "node:child_process";
 import { checkPaths, checkBash, isFilesystemTool } from "./confine.js";
-/** Conservative per-token rates for a model the catalogue cannot price —
- *  Opus-class — so a ceiling still means something on an unknown gateway. */
+/** Conservative per-token rates for a model nothing else can price — an
+ *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
+ *  still means something. Only ever reached when `knownPrice` below does
+ *  not recognise the model either. */
 export const FALLBACK_PRICE = { input: 15e-6, output: 75e-6 };
+/** The rates we know without asking anyone: the tiers this runtime resolves
+ *  (`fast`/`default`/`max` → haiku/sonnet/opus) and the model ids that carry
+ *  those words. A gateway with a catalogue still wins — that is the
+ *  authority — but the platform's own Anthropic key has no catalogue, and
+ *  pricing its steps at Opus rates made every mid-turn ceiling read up to
+ *  fifteen times high: an indexing run was stopped at "$1.17" having
+ *  actually spent $0.15 (2026-09-08). Per token, input/output. */
+const KNOWN_PRICES = [
+    [/haiku/i, { input: 1e-6, output: 5e-6 }],
+    [/sonnet/i, { input: 2e-6, output: 10e-6 }],
+    [/\bopus\b/i, { input: 5e-6, output: 25e-6 }],
+];
+/** What a token costs on this model, when we can say without a catalogue. */
+export function knownPrice(model) {
+    if (!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. Cache traffic is counted as input at the
- * input rate, which over-approximates on gateways with cheaper cache reads
- * — on the money side, the honest direction to be wrong in. Pure.
+ * What one assistant turn cost, from the usage the SDK reports. Pure.
+ *
+ * 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
+ * number exists to stop a runaway step mid-turn, and wants to be close.
  */
 export function priceTurn(u, price) {
-    const inTok = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
-    const outTok = u.output_tokens ?? 0;
     const p = price ?? FALLBACK_PRICE;
-    return inTok * p.input + outTok * p.output;
+    const fresh = u.input_tokens ?? 0;
+    const written = u.cache_creation_input_tokens ?? 0;
+    const read = u.cache_read_input_tokens ?? 0;
+    const outTok = u.output_tokens ?? 0;
+    return (fresh * p.input +
+        written * p.input * CACHE_WRITE_MULTIPLIER +
+        read * p.input * CACHE_READ_MULTIPLIER +
+        outTok * p.output);
 }
 /**
  * Each step launched together gets an equal share of what is left of the

package/dist/src/store.d.ts

@@ -378,6 +378,12 @@ export interface FlowInfo {
      *  overlap) — a default that changed underfoot would surprise every flow
      *  that legitimately runs in parallel. */
     overlap: "skip" | "queue" | null;
+    /** Where this flow's runs stand in the queue against everyone else's:
+     *  "high" is claimed before the round-robin, "low" after it. Adds to the
+     *  account's own priority; the account's cap still bounds how many run
+     *  at once, so a high lane never starves the rest outright. Unset is
+     *  normal — first come, fair across accounts. */
+    priority: "high" | "normal" | "low" | null;
     /** The most one run of this flow may spend, in USD. A literal, never an
      *  expression — the cap is readable off the file, which is the property
      *  the whole grammar exists to keep. Checked between groups: the group
@@ -565,6 +571,9 @@ export interface ChangeMeta {
     message?: string;
 }
 export declare function writeWorkspaceFile(tenant: string, workspace: string, rel: string, content: string, meta?: ChangeMeta): void;
+/** Tell the platform, and never let its listener fail a write. */
+declare function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+export { workspaceChanged as notifyWorkspaceChanged };
 export declare function syncBundleFor(file: string, change?: "Creation" | "Update"): void;
 /**
  * Rename one editable file. Both ends pass the same gate as a write — a
@@ -653,6 +662,21 @@ export interface StepRecord {
     verify?: string;
     /** Attempts made so far, for the run trace. */
     attempts?: number;
+    /** The sandbox this step is executing in, while it is: which executor,
+     *  its handle (a pod name), and how many of its output lines the driver
+     *  has already applied to this record. What a driver that inherits the
+     *  run — after a deploy rolled the last one, or it crashed — needs to
+     *  re-attach and carry on rather than run the step again. Cleared when
+     *  the step settles. */
+    sandbox?: {
+        kind: string;
+        ref: string;
+        consumed: number;
+        since: string;
+    } | null;
+    /** A size class a retry moved the step up to (an evicted or OOM-killed
+     *  attempt), overriding the agent's own `size:` for the attempts after. */
+    sizeUp?: "large" | "heavy";
     /** When the step actually started and finished executing — not when the
      *  run reached it. A step's events approximate this (first and last), but
      *  a model can think for minutes before its first tool call, and a step

package/dist/src/store.js

@@ -23,6 +23,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
 import { dataRoot, singleWorkspace } from "./paths.js";
+import { platform } from "./platform.js";
 import matter from "gray-matter";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
@@ -413,6 +414,12 @@ meta = {}) {
     // them are not bundles until their index.md exists to carry okf_version. A
     // deploy writes straight to disk, so nothing else would generate them.
     syncWorkspaceBundles(dir);
+    // Here, not in deployWorkspace: a workspace CREATED with files (the API's
+    // create, the CLI's first deploy, a template) comes through this function
+    // without going through deployWorkspace, and the first live check found
+    // exactly that — a new desk's cron was seen on the five-minute rescan, not
+    // the next tick.
+    workspaceChanged(tenant, workspace, "deploy");
     return { preserved: preserved.length };
 }
 // The prompt-facing index for an OKF bundle (memory/ or knowledge/).
@@ -1052,6 +1059,7 @@ export function parseFlow(file, raw) {
         model: data.model ?? null,
         effort: data.effort ?? null,
         overlap: data.overlap === "skip" || data.overlap === "queue" ? data.overlap : null,
+        priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
         budget: Number(data.budget) > 0 ? Number(data.budget) : null,
         // `after: [[flow:publish]]` — a link or a bare name, read the same way
         // as every other file-naming field (refs.ts).
@@ -1606,7 +1614,18 @@ export function writeWorkspaceFile(tenant, workspace, rel, content, meta = {}) {
     // The revision: what it was, what it is now. Identical content records
     // nothing — see history.ts.
     recordRevision(tenant, workspace, [{ path: norm, before, after: fs.readFileSync(p, "utf8") }], meta);
+    workspaceChanged(tenant, workspace, "write");
 }
+/** Tell the platform, and never let its listener fail a write. */
+function workspaceChanged(tenant, workspace, why) {
+    try {
+        platform.workspaceChanged(tenant, workspace, why);
+    }
+    catch {
+        // a scheduler that could not be told will find out on its next rescan
+    }
+}
+export { workspaceChanged as notifyWorkspaceChanged };
 // memory/ and knowledge/ are OKF bundles, so index.md has to stay current —
 // a generated index that drifts is the same class of bug as a memory index
 // naming files that don't exist.
@@ -1697,6 +1716,7 @@ export function renameWorkspaceFile(tenant, workspace, from, to, meta = {}) {
     ], { message: `renamed ${from} → ${to}`, ...meta });
     syncBundleFor(src);
     syncBundleFor(dst, "Update");
+    workspaceChanged(tenant, workspace, "write");
 }
 /** Every text file under a path, as revision entries recording deletion. */
 function deletionsUnder(dir, norm) {
@@ -1759,12 +1779,14 @@ export function deleteWorkspacePath(tenant, workspace, rel, meta = {}) {
     recordRevision(tenant, workspace, gone, meta);
     // A bundle's index must stop naming what is gone.
     syncBundleFor(p);
+    workspaceChanged(tenant, workspace, "write");
 }
 export function deleteWorkspace(tenant, workspace) {
     const dir = workspaceDir(tenant, workspace);
     if (!fs.existsSync(dir))
         throw new Error(`workspace ${workspace} not found`);
     fs.rmSync(dir, { recursive: true, force: true });
+    workspaceChanged(tenant, workspace, "delete");
 }
 /**
  * What a rename would break, so the caller can say so before doing it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,8 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run build",
     "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test *.test.ts $(ls tests/*.test.ts | grep -v e2e)",
-    "container": "FOLDRUN_CONTAINER_E2E=1 node scripts/ts-test.mjs tests/container-e2e.test.ts --test-timeout=600000"
+    "container": "FOLDRUN_CONTAINER_E2E=1 node scripts/ts-test.mjs tests/container-e2e.test.ts --test-timeout=600000",
+    "release": "node scripts/release.mjs"
   },
   "engines": {
     "node": ">=22"

package/src/deploy.ts

@@ -29,6 +29,7 @@ import {
   WORKSPACE_DIRS,
   assertSafeName,
   type DeployFile,
+  notifyWorkspaceChanged,
 } from "./store.ts";
 import { conformanceIssues } from "./okf.ts";
 import { repoDir } from "./gitrepo.ts";
@@ -373,6 +374,8 @@ export function writePushNote(tenant: string, workspace: string, note: PushNote)
   } catch {
     // The note is a record, not the deploy. Losing it must not fail a push.
   }
+  // A push waiting on a run is the scheduler's to apply; tell it there is one.
+  notifyWorkspaceChanged(tenant, workspace, "push");
 }
 
 /**
@@ -428,7 +431,7 @@ export function deployWorkspace(
   const { preserved } = saveWorkspace(tenant, workspace, files, { commit: opts.commit ?? null, by: opts.by ?? "deploy", message: opts.message });
   const commit = opts.commit ?? null;
   if (commit) writeDeployedCommit(tenant, workspace, commit);
-  return { ...plan, applied: true, commit, preserved };
+  return { ...plan, applied: true, commit, preserved }; // saveWorkspace told the platform
 }
 
 // Which commit a workspace is running.

package/src/platform.ts

@@ -45,6 +45,16 @@ export interface PlatformHooks {
   /** The egress proxy — a per-step lease that keeps credentials out of the
    *  sandbox. Default: none, and the runner materialises as it always did. */
   egress: EgressHooks;
+  /** A workspace's files changed — written, deployed, pushed, or the
+   *  workspace deleted. What a scheduler that keeps flows in memory rather
+   *  than re-reading every workspace each tick needs to hear. Default:
+   *  nothing — locally the scheduler reads the disk. Never throws. */
+  workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+  /** Can a step in this isolation mode be re-attached to after the driver
+   *  that started it is gone? True means an orphaned step with a `sandbox`
+   *  on its record is resumed rather than destroyed and run again. Default:
+   *  nothing is. */
+  sandboxResumable(kind: string): boolean;
 }
 
 const local: PlatformHooks = {
@@ -60,6 +70,8 @@ const local: PlatformHooks = {
   previewSourceOf: () => null,
   tenantKey: () => null,
   egress: { lease: async () => null },
+  workspaceChanged() {},
+  sandboxResumable: () => false,
 };
 
 // One object per PROCESS, not per module instance. A bundler that compiles

package/src/run-container.ts

@@ -106,6 +106,10 @@ export interface StepActuals {
 export interface ContainerStepOutcome {
   status: "completed" | "failed";
   result: string | null;
+  /** Why the sandbox ended when the step did not: what the cluster said
+   *  (OOMKilled, Evicted, the pod gone). Absent when the driver finished
+   *  and said so itself. A retry policy reads this. */
+  reason?: string | null;
   /** The model's final text block — see StepRecord.conclusion. Crosses the
    *  boundary with the rest of the outcome; the driver spreads it. */
   conclusion?: string | null;
@@ -186,10 +190,35 @@ export function allowedBack(rel: string): boolean {
  * the step did not touch it, so it is not ours to write back. Concurrent
  * edits survive, and a step that genuinely changed a file still wins.
  */
+/**
+ * What a workspace copy looked like when it went in: the sha256 of every
+ * file the step could hand back. Small enough to ride into the sandbox
+ * beside the input, so a driver that inherits the step can tell what the
+ * step changed without the staging copy the first driver held in /tmp.
+ */
+export function hashTree(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (d: string) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const abs = path.join(d, entry.name);
+      const rel = path.relative(dir, abs).replaceAll("\\", "/");
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (allowedBack(rel + "/")) walk(abs);
+        continue;
+      }
+      if (!allowedBack(rel)) continue;
+      out[rel] = crypto.createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir);
+  return out;
+}
+
 export function applyContainerChanges(
   hostWs: string,
   containerWs: string,
-  baseline?: string,
+  baseline?: string | Record<string, string>,
 ): string[] {
   const applied: string[] = [];
   const walk = (dir: string) => {
@@ -211,9 +240,12 @@ export function applyContainerChanges(
       const next = fs.readFileSync(abs);
       // Untouched by this step: whatever the host says now is more current
       // than what we handed in, including a change made while it ran.
-      if (baseline) {
+      if (typeof baseline === "string") {
         const was = path.join(baseline, rel);
         if (fs.existsSync(was) && fs.readFileSync(was).equals(next)) continue;
+      } else if (baseline) {
+        const was = baseline[rel.replaceAll("\\", "/")];
+        if (was && was === crypto.createHash("sha256").update(next).digest("hex")) continue;
       }
       const target = path.join(hostWs, rel);
       if (fs.existsSync(target) && fs.readFileSync(target).equals(next)) continue;
@@ -625,6 +657,15 @@ export interface RunInContainerArgs {
   runId?: string;
   /** The reservation class — which limits this step's sandbox holds. */
   size?: "small" | "large" | "heavy";
+  /** Re-attach to a sandbox a previous driver started, instead of creating
+   *  one: its handle, and how many output lines that driver had applied.
+   *  The executor replays nothing before `consumed`, and reads the step's
+   *  files back from the sandbox's own copy-in snapshot. */
+  resume?: { ref: string; consumed: number } | null;
+  /** Called by an executor that can be resumed: when its sandbox exists
+   *  (consumed 0), and before each output line it applies. The runner
+   *  records these on the step, so the next driver knows where to attach. */
+  checkpoint?: (ref: string, consumed: number) => void;
 }
 
 /** The limits a size class reserves. Large is the install's configured

package/src/runner.ts

@@ -7,7 +7,8 @@ import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import { spawn } from "node:child_process";
-import { executeStep, extractJson, stepCeiling, type EventExtra } from "./step-exec.ts";
+import {
+  knownPrice, executeStep, extractJson, stepCeiling, type EventExtra } from "./step-exec.ts";
 import { eventUrl } from "./webhook.ts";
 import { runStepInContainer, sizeLimits, killRunSandboxes, type StepTiming } from "./run-container.ts";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute, type EgressGrant } from "./egress.ts";
@@ -1297,11 +1298,14 @@ async function runStep(
       front, clockEnv, systemPrompt, allowed, disabled, apiTools, scriptTools,
       secretEnv, secretScopes, missingSecrets, missingTools, runtime,
       unknownTools, shadowed, legacyUse, mcpServers, mcpNames,
-      apiSpecs, scriptSpecs, brokenTools, size,
+      apiSpecs, scriptSpecs, brokenTools, size: agentSize,
       providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning,
       fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools,
       translator, fallbackTranslator,
     } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent });
+    // A retry that moved the step up a class (an evicted or OOM-killed
+    // attempt) wins over the agent's own `size:` for the attempts after.
+    const size = step.sizeUp ?? agentSize;
 
     // oauth2 secrets become live access tokens here — the one async moment
     // in secret resolution, at the last host-side point before anything is
@@ -1439,6 +1443,11 @@ async function runStep(
       if (fitted.note) push("info", fitted.note);
       effort = fitted.effort;
     }
+    // No catalogue — the platform's own Anthropic key, or a gateway that
+    // publishes no prices — but the model's NAME is often enough. Without
+    // this the in-pod meter priced haiku and sonnet at Opus rates and a
+    // step was stopped at up to fifteen times what it had spent.
+    tokenPrice ??= knownPrice(wireModel);
 
     fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
     fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
@@ -1690,6 +1699,18 @@ async function runStep(
         // Stamps the sandbox, so stopping this run can destroy it.
         runId,
         size,
+        // Resume: a sandbox a previous driver left running, recorded on the
+        // step. Consumed once — a fresh attempt after this one (a retry, a
+        // fallback) starts its own sandbox.
+        resume: step.sandbox && step.sandbox.kind === isolation ? { ref: step.sandbox.ref, consumed: step.sandbox.consumed } : null,
+        // Checkpoint: where the executor is, on the record, so a driver
+        // that inherits this run can attach where this one left off. The
+        // executor calls it before applying each line; the line's own emit
+        // saves the record, so this only updates the fields.
+        checkpoint: (ref: string, consumed: number) => {
+          step.sandbox = { kind: isolation!, ref, consumed, since: step.sandbox?.since ?? new Date().toISOString() };
+          if (consumed === 0) save();
+        },
       });
 
       // A busy provider gets another moment on the SAME supply before the
@@ -1700,6 +1721,7 @@ async function runStep(
       const firstArgs = isolatedArgs(platformModelEnv());
       await lease?.commit();
       let outcome = await runIsolated(firstArgs);
+      step.sandbox = null; // whatever happens next starts its own
       for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
         const wait = backoffMs(n, lastRefusal);
         push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
@@ -1752,6 +1774,10 @@ async function runStep(
       step.status = outcome.status;
       step.result = outcome.result;
       step.conclusion = outcome.conclusion;
+      step.sandbox = null;
+      // The cluster's word on why a sandbox ended without the driver saying
+      // so — OOMKilled, Evicted — on the record, where the retry reads it.
+      if (outcome.status === "failed" && outcome.reason) push("error", `sandbox ended: ${outcome.reason}`);
       if (outcome.data !== undefined) step.data = outcome.data;
       step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push);
       step.tokens = outcome.usage
@@ -2450,15 +2476,25 @@ function driveRunInner(
       // never happened, which reconcile can then never see. Reset it to
       // pending and it simply runs again; driveRun's whole contract is that
       // re-driving a partly-finished record is safe.
+      // Unless the step's sandbox outlived its driver AND the executor can
+      // re-attach to it: then the record carries the pod and how far the
+      // last driver got, runStep passes that as `resume`, and the step
+      // carries on from where it was — a deploy no longer costs the run.
       let orphaned = false;
       for (const step of run.steps) {
         if (step.status !== "running") continue;
-        orphaned = true;
+        const resumable = !!step.sandbox && platform.sandboxResumable(step.sandbox.kind);
+        if (!resumable) {
+          orphaned = true;
+          step.sandbox = null;
+        }
         step.status = "pending";
         step.events.push({
           t: new Date().toISOString(),
           type: "info",
-          text: "interrupted mid-step (platform restart) — running again from the start of the step",
+          text: resumable
+            ? `driver changed mid-step — re-attaching to the running sandbox (${step.sandbox!.ref}, ${step.sandbox!.consumed} lines already applied)`
+            : "interrupted mid-step (platform restart) — running again from the start of the step",
         });
       }
       if (orphaned) {
@@ -2908,7 +2944,13 @@ function driveRunInner(
           launching
             .map(async (step) => {
               const attempts = (step.retry ?? 0) + 1;
-              for (let attempt = 1; attempt <= attempts; attempt++) {
+              // A step re-attaching to its sandbox is still on the attempt
+              // that started it; a step re-run after a backoff picks up the
+              // count it left. Only a step nobody has touched starts at 1.
+              const interruptedInBackoff =
+                !step.sandbox && !!step.attempts && /retrying in \d+s/.test(step.events[step.events.length - 1]?.text ?? "");
+              const from = step.sandbox ? Math.max(1, step.attempts ?? 1) : interruptedInBackoff ? Math.min(attempts, step.attempts! + 1) : 1;
+              for (let attempt = from; attempt <= attempts; attempt++) {
                 step.attempts = attempt;
                 step.status = "running";
                 save();
@@ -2935,12 +2977,42 @@ function driveRunInner(
                 // more. save() merges the flag from the record.
                 save();
                 if (run.stopRequested) break;
+                // The retry policy. An attempt the cluster ended for want of
+                // memory or disk is retried one size class up — the same
+                // size would end the same way. Every retry waits: 15 s, 30 s,
+                // 1 m, 2 m, 4 m, jittered, so a provider or a site that was
+                // struggling gets a moment, and twenty fan-out steps do not
+                // hammer it in lock-step. The wait holds a worker slot, not
+                // a sandbox — nothing is rented while it waits — and a stop
+                // ends it. The step is `pending` meanwhile, so a driver that
+                // inherits the run mid-wait simply runs the attempt.
+                const last = [...step.events].reverse().find((e) => e.type === "error")?.text ?? "";
+                let sizeNote = "";
+                if (/OOMKilled|Evicted|ephemeral-storage|out of memory/i.test(last)) {
+                  const up = step.sizeUp === "large" || (!step.sizeUp && step.size === "large") ? "heavy" : step.sizeUp === "heavy" || step.size === "heavy" ? null : "large";
+                  if (up) {
+                    step.sizeUp = up;
+                    sizeNote = ` at size: ${up}`;
+                  }
+                }
+                const waitMs = Math.round(Math.min(retryBaseMs() * 16, retryBaseMs() * 2 ** (attempt - 1)) * (0.75 + Math.random() * 0.5));
+                step.status = "pending";
                 step.events.push({
                   t: new Date().toISOString(),
                   type: "info",
-                  text: `attempt ${attempt} failed — retrying (${attempts - attempt} left)`,
+                  text: `attempt ${attempt} failed — retrying in ${Math.round(waitMs / 1000)}s${sizeNote} (${attempts - attempt} left)`,
                 });
                 save();
+                const until = Date.now() + waitMs;
+                while (Date.now() < until) {
+                  await sleep(Math.min(1000, until - Date.now()));
+                  save();
+                  if (run.stopRequested) break;
+                }
+                if (run.stopRequested) {
+                  step.status = "failed";
+                  break;
+                }
               }
             }),
         );
@@ -3270,6 +3342,10 @@ export function loadFlow(tenant: string, workspace: string, flowName: string) {
 // written a beat before its driver registered, not a judgement about pace.
 const ABANDONED_AFTER_MS = 2 * 60 * 1000;
 
+/** The first retry's wait; each one after doubles it, to sixteen times
+ *  this (15 s → 4 min by default). An env, so a test can make it small. */
+const retryBaseMs = () => Number(process.env.FOLDRUN_RETRY_BASE_MS) || 15_000;
+
 /** The most recent moment a run showed any sign of life. */
 function lastActivity(run: RunRecord): number {
   let latest = Date.parse(run.startedAt);
@@ -3311,12 +3387,18 @@ export interface Reconciliation {
  * outlives any process. A run whose person already answered is not waiting,
  * and is picked back up — see below.
  */
-export function reconcileRuns(tenant: string, now = Date.now()): Reconciliation[] {
+export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlySet<string>): Reconciliation[] {
   const closed: Reconciliation[] = [];
 
   for (const workspace of listWorkspaces(tenant)) {
     for (const summary of listRuns(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
+      // process's judgement only; a worker that boots beside a live one
+      // would otherwise close every long step its neighbour is driving.
+      // The caller says which runs those are (a heartbeated claim).
+      if (live?.has(summary.id)) continue;
       if (now - lastActivity(summary) < ABANDONED_AFTER_MS) continue;
 
       // Approved, then abandoned. Approval only writes to the run record; the
@@ -3396,8 +3478,8 @@ export function reconcileRuns(tenant: string, now = Date.now()): Reconciliation[
  * one hard-coded account left every other account's interrupted runs marked
  * `running` forever, with no process left to finish them.
  */
-export function reconcileAllRuns(now = Date.now()): Reconciliation[] {
-  return listTenants().flatMap((tenant) => reconcileRuns(tenant, now));
+export function reconcileAllRuns(now = Date.now(), live?: ReadonlySet<string>): Reconciliation[] {
+  return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live));
 }
 
 /**

package/src/starter.ts

@@ -319,6 +319,7 @@ timezone: Australia/Sydney
 model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
+priority: normal         # high | normal | low — where its runs stand in the queue
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.

package/src/step-exec.ts

@@ -79,20 +79,60 @@ export interface ExecOptions {
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
 export type EventExtra = { call?: string; ms?: number; err?: boolean };
 
-/** Conservative per-token rates for a model the catalogue cannot price —
- *  Opus-class — so a ceiling still means something on an unknown gateway. */
+/** Conservative per-token rates for a model nothing else can price — an
+ *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
+ *  still means something. Only ever reached when `knownPrice` below does
+ *  not recognise the model either. */
 export const FALLBACK_PRICE = { input: 15e-6, output: 75e-6 };
 
+/** The rates we know without asking anyone: the tiers this runtime resolves
+ *  (`fast`/`default`/`max` → haiku/sonnet/opus) and the model ids that carry
+ *  those words. A gateway with a catalogue still wins — that is the
+ *  authority — but the platform's own Anthropic key has no catalogue, and
+ *  pricing its steps at Opus rates made every mid-turn ceiling read up to
+ *  fifteen times high: an indexing run was stopped at "$1.17" having
+ *  actually spent $0.15 (2026-09-08). Per token, input/output. */
+const KNOWN_PRICES: [RegExp, { input: number; output: number }][] = [
+  [/haiku/i, { input: 1e-6, output: 5e-6 }],
+  [/sonnet/i, { input: 2e-6, output: 10e-6 }],
+  [/\bopus\b/i, { input: 5e-6, output: 25e-6 }],
+];
+
+/** What a token costs on this model, when we can say without a catalogue. */
+export function knownPrice(model: string | undefined): { input: number; output: number } | null {
+  if (!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. Cache traffic is counted as input at the
- * input rate, which over-approximates on gateways with cheaper cache reads
- * — on the money side, the honest direction to be wrong in. Pure.
+ * What one assistant turn cost, from the usage the SDK reports. Pure.
+ *
+ * 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
+ * number exists to stop a runaway step mid-turn, and wants to be close.
  */
 export function priceTurn(u: Record<string, number | undefined>, price: { input: number; output: number } | null): number {
-  const inTok = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
-  const outTok = u.output_tokens ?? 0;
   const p = price ?? FALLBACK_PRICE;
-  return inTok * p.input + outTok * p.output;
+  const fresh = u.input_tokens ?? 0;
+  const written = u.cache_creation_input_tokens ?? 0;
+  const read = u.cache_read_input_tokens ?? 0;
+  const outTok = u.output_tokens ?? 0;
+  return (
+    fresh * p.input +
+    written * p.input * CACHE_WRITE_MULTIPLIER +
+    read * p.input * CACHE_READ_MULTIPLIER +
+    outTok * p.output
+  );
 }
 
 /**

package/src/store.ts

@@ -24,6 +24,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader, type RevisionFile } from "./history.ts";
 import { dataRoot, singleWorkspace } from "./paths.ts";
+import { platform } from "./platform.ts";
 import matter from "gray-matter";
 
 /**
@@ -452,6 +453,13 @@ export function saveWorkspace(
   // deploy writes straight to disk, so nothing else would generate them.
   syncWorkspaceBundles(dir);
 
+  // Here, not in deployWorkspace: a workspace CREATED with files (the API's
+  // create, the CLI's first deploy, a template) comes through this function
+  // without going through deployWorkspace, and the first live check found
+  // exactly that — a new desk's cron was seen on the five-minute rescan, not
+  // the next tick.
+  workspaceChanged(tenant, workspace, "deploy");
+
   return { preserved: preserved.length };
 }
 
@@ -1083,6 +1091,12 @@ export interface FlowInfo {
    *  overlap) — a default that changed underfoot would surprise every flow
    *  that legitimately runs in parallel. */
   overlap: "skip" | "queue" | null;
+  /** Where this flow's runs stand in the queue against everyone else's:
+   *  "high" is claimed before the round-robin, "low" after it. Adds to the
+   *  account's own priority; the account's cap still bounds how many run
+   *  at once, so a high lane never starves the rest outright. Unset is
+   *  normal — first come, fair across accounts. */
+  priority: "high" | "normal" | "low" | null;
   /** The most one run of this flow may spend, in USD. A literal, never an
    *  expression — the cap is readable off the file, which is the property
    *  the whole grammar exists to keep. Checked between groups: the group
@@ -1313,6 +1327,7 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     model: data.model ?? null,
     effort: data.effort ?? null,
     overlap: data.overlap === "skip" || data.overlap === "queue" ? data.overlap : null,
+    priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
     budget: Number(data.budget) > 0 ? Number(data.budget) : null,
     // `after: [[flow:publish]]` — a link or a bare name, read the same way
     // as every other file-naming field (refs.ts).
@@ -1895,7 +1910,18 @@ export function writeWorkspaceFile(
   // The revision: what it was, what it is now. Identical content records
   // nothing — see history.ts.
   recordRevision(tenant, workspace, [{ path: norm, before, after: fs.readFileSync(p, "utf8") }], meta);
+  workspaceChanged(tenant, workspace, "write");
+}
+
+/** Tell the platform, and never let its listener fail a write. */
+function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete") {
+  try {
+    platform.workspaceChanged(tenant, workspace, why);
+  } catch {
+    // a scheduler that could not be told will find out on its next rescan
+  }
 }
+export { workspaceChanged as notifyWorkspaceChanged };
 
 // memory/ and knowledge/ are OKF bundles, so index.md has to stay current —
 // a generated index that drifts is the same class of bug as a memory index
@@ -1990,6 +2016,7 @@ export function renameWorkspaceFile(tenant: string, workspace: string, from: str
   );
   syncBundleFor(src);
   syncBundleFor(dst, "Update");
+  workspaceChanged(tenant, workspace, "write");
 }
 
 /** Every text file under a path, as revision entries recording deletion. */
@@ -2051,12 +2078,14 @@ export function deleteWorkspacePath(tenant: string, workspace: string, rel: stri
   recordRevision(tenant, workspace, gone, meta);
   // A bundle's index must stop naming what is gone.
   syncBundleFor(p);
+  workspaceChanged(tenant, workspace, "write");
 }
 
 export function deleteWorkspace(tenant: string, workspace: string) {
   const dir = workspaceDir(tenant, workspace);
   if (!fs.existsSync(dir)) throw new Error(`workspace ${workspace} not found`);
   fs.rmSync(dir, { recursive: true, force: true });
+  workspaceChanged(tenant, workspace, "delete");
 }
 
 /**
@@ -2235,6 +2264,16 @@ export interface StepRecord {
   verify?: string;
   /** Attempts made so far, for the run trace. */
   attempts?: number;
+  /** The sandbox this step is executing in, while it is: which executor,
+   *  its handle (a pod name), and how many of its output lines the driver
+   *  has already applied to this record. What a driver that inherits the
+   *  run — after a deploy rolled the last one, or it crashed — needs to
+   *  re-attach and carry on rather than run the step again. Cleared when
+   *  the step settles. */
+  sandbox?: { kind: string; ref: string; consumed: number; since: string } | null;
+  /** A size class a retry moved the step up to (an evicted or OOM-killed
+   *  attempt), overriding the agent's own `size:` for the attempts after. */
+  sizeUp?: "large" | "heavy";
   /** When the step actually started and finished executing — not when the
    *  run reached it. A step's events approximate this (first and last), but
    *  a model can think for minutes before its first tool call, and a step