@foldrun/core 2.12.0 → 2.13.0

package/dist/src/runner.js

@@ -16,7 +16,8 @@ import { cascadeLimits, toolOwners } from "./limits.js";
 import { resolveAgentPath } from "./confine.js";
 import { browserPodLine, podLossDecision, RERAN_ON_FULL } from "./browser-pod.js";
 import { eventUrl } from "./webhook.js";
-import { runStepInContainer, sizeLimits, killRunSandboxes } from "./run-container.js";
+import { runStepInContainer, resolveResources, memoryGiB, killRunSandboxes } from "./run-container.js";
+import { readResources, hasOverride } from "./resources.js";
 import { hostSafeEnv, platformApiUrl } from "./host-env.js";
 import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken, isModelEnvName, DECLARED_ENV_PREFIX } from "./model-credential.js";
 import { parseJudge } from "./judge-verdict.js";
@@ -1157,9 +1158,10 @@ grantsOnly = false) {
     // is large — the install's configured limits — so existing agents change
     // nothing. `size: small` is the opt-in for agents that wait on APIs more
     // than they work; `size: heavy` for a rendered browser or real data in
-    // memory. Memory is a hard ceiling per class; CPU bursts uncapped and bills
-    // at the class rate, so heavy both may use more and costs more. The actuals
-    // line in any trace is the evidence for right-sizing.
+    // memory. Memory and cores are hard ceilings per class and bill at the
+    // class rate (cores capped since 26 Oct 2026), so heavy both may use more
+    // and costs more. The actuals line in any trace — busy, throttled, peak —
+    // is the evidence for right-sizing.
     const size = front.size === "small" ? "small" : front.size === "heavy" ? "heavy" : "large";
     // Provider: which endpoint the model calls run against. Anthropic by
     // default; an Anthropic-compatible gateway (z.ai, LiteLLM, OpenRouter) by
@@ -2117,6 +2119,17 @@ delegateJob) {
         // 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;
+        // `resources:` over the class's figures, key by key. A value check would
+        // refuse is dropped here too (the class's figure holds) and said so, so
+        // `foldrun check` and the sandbox never disagree. After a retry moved up
+        // a class, an override never holds the step below the new class.
+        const asked = readResources(front.resources);
+        for (const p of asked.problems)
+            push("error", `resources: ${p}`);
+        const limits = resolveResources(size, asked.value, { atLeastClass: !!step.sizeUp });
+        // What the sandbox holds while it exists — `step.holding`, what the
+        // account's compute in use sums (Settings, `foldrun usage compute`).
+        const held = { cpus: Number(limits.cpus) || 2, memGiB: memoryGiB(limits.memory) };
         // 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:
@@ -2150,7 +2163,10 @@ delegateJob) {
         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) {
+        // Core's own Docker container has no login to fall back to (below):
+        // there, "none set" is refused with what to do, not described.
+        const noCredentialInContainer = credential?.kind === "none" && process.env.FOLDRUN_RUN_ISOLATION === "container";
+        if (credential && !noCredentialInContainer) {
             const line = credentialLine(credential);
             push(line.type, line.text);
         }
@@ -2174,6 +2190,21 @@ delegateJob) {
                 return;
             }
         }
+        // A step in core's own Docker container (self-hosting) has no machine
+        // login to fall back to: with no credential at all it could only fail at
+        // the model, with Claude Code's own "Not logged in · Please run /login".
+        // Refused here, before a sandbox is rented, saying what to set (a
+        // self-hosted install with no key, 26 Oct 2026). A local `foldrun run`
+        // keeps the machine's login; a registered executor brings its own.
+        if (noCredentialInContainer) {
+            push("error", "no model credential: this install has none and the account has no key of its own. Set ANTHROPIC_API_KEY " +
+                "(or CLAUDE_CODE_OAUTH_TOKEN from `claude setup-token`) in the platform's environment — for Docker Compose, " +
+                "self-hosting/.env, then `docker compose up -d` — or add the account's key in Settings → Model " +
+                "(`foldrun account model set <provider> --key …`)");
+            step.status = "failed";
+            save();
+            return;
+        }
         for (const w of providerWarnings)
             push("error", w);
         // A level that wrote a language nobody can read was skipped, not obeyed.
@@ -2869,6 +2900,7 @@ delegateJob) {
                 // executor asks this before it creates one (pod-room.ts).
                 ...(stopRequested ? { stopRequested } : {}),
                 size,
+                limits,
                 // The pod's network, for the executor's own wall (the k8s tier's
                 // network policy): a filtered pod reaches the proxy and DNS only.
                 network: { level: network.level, enforced: forward?.enforce === true },
@@ -2885,6 +2917,9 @@ delegateJob) {
                 // 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() };
+                    // The sandbox exists: past the room gate, it now holds its figures.
+                    if (consumed === 0)
+                        step.holding = held;
                     if (consumed === 0)
                         save();
                 },
@@ -2900,9 +2935,24 @@ delegateJob) {
             // The arguments of the attempt whose outcome is current — what a
             // re-run on the full image repeats, on the same model supply.
             let lastArgs = firstArgs;
-            const runTracked = (a) => {
+            const runTracked = async (a) => {
                 lastArgs = a;
-                return runIsolated(a);
+                // An executor that cannot report its sandbox (Docker: no room gate,
+                // it starts at once) holds from the call; one that can says so at
+                // its first checkpoint, after any wait for room.
+                if (!platform.sandboxResumable(isolation)) {
+                    step.holding = held;
+                    save();
+                }
+                try {
+                    return await runIsolated(a);
+                }
+                finally {
+                    // Saved now: the clean-up after an attempt (the log drain, the
+                    // lease, publishing) can take a while, and the sandbox is gone.
+                    step.holding = null;
+                    save();
+                }
             };
             let attemptFrom = step.events.length;
             let outcome = await runTracked(firstArgs);
@@ -3096,6 +3146,7 @@ delegateJob) {
             if (outcome.res?.peakMemBytes || outcome.res?.rxBytes) {
                 const mb = (n) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
                 push("info", `resources: cpu busy ${outcome.res.busyCpuSecs?.toFixed(1) ?? "?"}s · ` +
+                    (outcome.res.throttledSecs ? `throttled ${outcome.res.throttledSecs.toFixed(1)}s · ` : "") +
                     `peak mem ${mb(outcome.res.peakMemBytes)}MB · ` +
                     `net ${mb(outcome.res.rxBytes)}MB in / ${mb(outcome.res.txBytes)}MB out`);
             }
@@ -3115,13 +3166,9 @@ delegateJob) {
             // is per core-second and per GiB-second, and what was held must come
             // from the record, never from what the config says at billing time.
             step.size = size;
-            const lim = sizeLimits(size);
-            const gib = (() => {
-                const m = lim.memory.match(/^(\d+(?:\.\d+)?)\s*(Gi?|Mi?|g|m)?/i);
-                const n = m ? Number(m[1]) : 2;
-                return (m?.[2] ?? "Gi").toLowerCase().startsWith("m") ? n / 1024 : n;
-            })();
-            step.reserved = { cpus: Number(lim.cpus) || 2, memGiB: gib };
+            if (hasOverride(asked.value))
+                step.resources = asked.value;
+            step.reserved = held;
         }
         else {
             // Same withholding as the sandbox path — the in-process step is what

package/dist/src/starter.js

@@ -474,6 +474,7 @@ owner: ana@example.com      # who answers for it; else the workspace's, else the
 model: default              # fast | default | max
 effort: low                 # how hard to think about it
 size: large                 # small | large | heavy — the sandbox it rents
+resources: { memory: 4Gi }  # optional: cpu, memory, disk in numbers, over the size class
 tools: [web, read, ask, peers, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step, \`peers\` lets it message the steps running beside it
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/

package/dist/src/store.d.ts

@@ -1312,6 +1312,21 @@ export interface StepRecord {
         cpus: number;
         memGiB: number;
     } | null;
+    /** The agent's `resources:` as applied (resources.ts), when it set any:
+     *  why `reserved` differs from the class's figures. Absent before 26 Oct
+     *  2026 and on steps of an agent that wrote none. */
+    resources?: {
+        cpu?: number;
+        memory?: string;
+        disk?: string;
+    };
+    /** What the step's sandbox holds while it exists — set once it is past
+     *  the room gate, cleared when the attempt ends. What an account's
+     *  compute in use sums; `reserved` is the bill's record of the same. */
+    holding?: {
+        cpus: number;
+        memGiB: number;
+    } | null;
     /** 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. */
@@ -1336,6 +1351,9 @@ export interface StepRecord {
     actual?: {
         busyCpuSecs: number | null;
         peakMemBytes: number | null;
+        /** Seconds the CPU cap (the class's cores) held the sandbox back, from
+         *  cpu.stat. Absent before 26 Oct 2026. */
+        throttledSecs?: number | null;
         rxBytes: number | null;
         txBytes: number | null;
     } | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/completions.ts

@@ -143,6 +143,7 @@ const FIELDS: Record<string, Completion[]> = {
     { label: "skills", insert: "skills:\n  - ", hint: "allowlist; omit to inherit all" },
     { label: "scripts", insert: "scripts:\n  - name: \n    run: \n    description: " },
     { label: "runtime", insert: "runtime:\n  python: \"3\"\n  packages: []" },
+    { label: "resources", insert: "resources:\n  cpu: 2\n  memory: 4Gi", hint: "cores, memory and disk in numbers, over the size class's" },
     { label: "mcpServers", insert: "mcpServers:\n  " },
     { label: "ask", insert: "ask:\n  timeout: 30m", hint: "tools: [ask] — how long ask_person waits for a person (max 24h)" },
     { label: "permissionMode", insert: "permissionMode: plan", hint: "plan = read-only" },

package/src/frontmatter-fields.ts

@@ -79,6 +79,7 @@ const AGENT: FieldSpec[] = [
   { key: "model", type: "string", help: "fast | default | max, an alias, or a full model id" },
   { key: "effort", type: "string", values: EFFORT_LEVELS, help: "how long it thinks" },
   { key: "size", type: "string", values: ["small", "large", "heavy"], help: "the sandbox it rents; anything else becomes large" },
+  { key: "resources", type: "object", help: "{cpu, memory, disk} in numbers, over the size class's figures key by key — cpu 0.5–8, memory 256Mi–16Gi, disk 1–40Gi" },
   { key: "permissionMode", type: "string", values: ["plan"], help: "plan = read-only; no other mode changes anything here" },
   { key: "tools", type: ["list", "string"], help: "the one grant list" },
   { key: "disallowedTools", type: ["list", "string"], help: "subtract from what it would otherwise have" },
@@ -130,6 +131,7 @@ const AGENTS_MD: FieldSpec[] = [
   { key: "budget", type: ["number", "string"], help: "USD per month, or N/day | N/week | N/month" },
   { key: "priority", type: "string", values: ["high", "normal", "low"], help: "account: where its runs stand in the queue" },
   { key: "concurrency", type: ["number", "string"], help: "account: runs at once" },
+  { key: "compute", type: "object", help: "account: {vcpu, memory} its running steps may hold together — lowers the plan's, never raises it" },
   { key: "alerts", type: "object", validated: true, help: "thresholds that tell notify: — failure_rate (30%), min_runs, credits_day, run_minutes, stale_days, cost_spike, runs_per_hour, new_host" },
   { key: "capture", type: "string", values: ["full", "metadata"], help: "what runs record of each tool call: full (its input and output, secrets masked) or metadata (name, size and time only)" },
   { key: "network_enforce", type: "boolean", help: "true: a site off a step's network: list is refused, not only named in the trace. The account's or the workspace's true is enough" },
@@ -244,7 +246,7 @@ const SAID_WHAT_IT_IS: FieldSpec[] = [
 const JOB_FIELDS: Partial<Record<SchemaKind, Partial<Record<Job, readonly string[]>>>> = {
   agent: {
     governance: ["owner", "budget"],
-    guardrail: ["limits", "network", "hooks", "disallowedTools", "permissionMode", "secrets", "sandbox"],
+    guardrail: ["limits", "network", "hooks", "disallowedTools", "permissionMode", "secrets", "sandbox", "resources"],
   },
   flow: {
     governance: ["owner", "approvers", "approve_within", "budget", "priority"],
@@ -252,7 +254,7 @@ const JOB_FIELDS: Partial<Record<SchemaKind, Partial<Record<Job, readonly string
     observability: ["issues", "sla"],
   },
   "agents-md": {
-    governance: ["owner", "budget", "priority", "concurrency", "deploy_block"],
+    governance: ["owner", "budget", "priority", "concurrency", "compute", "deploy_block"],
     guardrail: ["limits", "network", "network_enforce", "hooks"],
     observability: ["alerts", "telemetry", "notify", "capture"],
     evaluation: ["judge"],

package/src/frontmatter-schema.ts

@@ -8,6 +8,7 @@ import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS
 import { budgetProblem } from "./budget.ts";
 import { cronProblem } from "./cron.ts";
 import { modelSecretCollision } from "./model-credential.ts";
+import { resourcesProblem, computeProblem } from "./resources.ts";
 
 export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
 
@@ -33,11 +34,13 @@ const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => stri
     apis: apisProblem,
     budget: (v) => budgetProblem(v, ["run"]),
     ask: (v) => askProblem(v),
+    resources: resourcesProblem,
     secrets: modelSecretCollision,
   },
   "agents-md": {
     budget: (v) => budgetProblem(v, ["day", "week", "month"]),
     concurrency: (v) => (Number.isInteger(Number(v)) && Number(v) > 0 ? null : `${String(v)} is not a whole number of runs, 1 or more`),
+    compute: computeProblem,
   },
   "flow": {
     schedule: cronProblem,

package/src/resources.ts

@@ -0,0 +1,151 @@
+// An agent's `resources:` — cores, memory and disk in numbers, over its
+// `size:` class's figures one key at a time:
+//
+//   size: large
+//   resources: { cpu: 2, memory: 4Gi, disk: 10Gi }
+//
+// `size:` stays the form most agents write; this is for the one that knows
+// its shape (much memory and one core for a big CSV, much disk for a video).
+// The figures are bounded and stepped the way sandbox platforms sell them,
+// so steps pack onto a node predictably and a price reads plainly. One
+// parser: `foldrun check` reports what it refuses, and the runner applies
+// what it accepts — so the two can never disagree about a value.
+//
+// Pure: no fs, no env. The class's figures come from sizeLimits
+// (run-container.ts), which resolveResources there merges these over.
+
+/** What an agent may ask for, and in what steps. */
+export const RESOURCE_BOUNDS = {
+  cpu: { min: 0.5, max: 8, step: 0.5 },
+  memoryMi: { min: 256, max: 16 * 1024, step: 256 },
+  diskGi: { min: 1, max: 40, step: 1 },
+} as const;
+
+/** The overrides an agent asked for, normalised: cores as a number, memory
+ *  in Mi and disk in Gi as quantities both Kubernetes and Docker accept. */
+export interface ResourceOverride {
+  cpu?: number;
+  memory?: string;
+  disk?: string;
+}
+
+const KEYS = ["cpu", "memory", "disk"] as const;
+
+/** A size in MiB: 512Mi, 4Gi, 1.5Gi (and Docker's 4g, 512m). NaN when it is
+ *  not one. A bare number is refused, because 4 could mean four of anything;
+ *  so are G and M, which are decimal to Kubernetes and binary to Docker —
+ *  an agent's figure means one thing everywhere it is read. */
+export function quantityMi(q: unknown): number {
+  if (typeof q !== "string") return NaN;
+  const m = /^(\d+(?:\.\d+)?)\s*(Mi|Gi|m|g)$/.exec(q.trim());
+  if (!m) return NaN;
+  const n = Number(m[1]);
+  return m[2] === "Gi" || m[2] === "g" ? n * 1024 : n;
+}
+
+/** A class's memory figure in MiB, in any spelling an install may set it:
+ *  bytes, Kubernetes' Ki/Mi/Gi/Ti and K/M/G/T, Docker's k/m/g/t. Wider than
+ *  quantityMi, which reads only what an agent may write. NaN when none. */
+export function anyMemoryMi(q: unknown): number {
+  const m = /^(\d+(?:\.\d+)?)\s*(Ki|Mi|Gi|Ti|K|M|G|T|k|m|g|t|b)?$/.exec(String(q ?? "").trim());
+  if (!m) return NaN;
+  const n = Number(m[1]);
+  const MiB = 2 ** 20;
+  const bin: Record<string, number> = { Ki: 2 ** 10, Mi: MiB, Gi: 2 ** 30, Ti: 2 ** 40, k: 2 ** 10, m: MiB, g: 2 ** 30, t: 2 ** 40, b: 1 };
+  const dec: Record<string, number> = { K: 1e3, M: 1e6, G: 1e9, T: 1e12 };
+  const unit = m[2] ?? "b";
+  return (n * (unit in bin ? bin[unit] : dec[unit])) / MiB;
+}
+
+const shown = (v: unknown) => (typeof v === "string" || typeof v === "number" ? String(v) : Array.isArray(v) ? "a list" : "a map");
+
+/** Read `resources:` — what applies, and why anything else does not. A key
+ *  that fails is dropped (the class's figure holds), never guessed at. */
+export function readResources(raw: unknown): { value: ResourceOverride; problems: string[] } {
+  const value: ResourceOverride = {};
+  const problems: string[] = [];
+  if (raw === undefined || raw === null) return { value, problems };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { value, problems: [`is ${shown(raw)}, not a map — write {cpu: 2, memory: 4Gi, disk: 10Gi}`] };
+  }
+  const r = raw as Record<string, unknown>;
+  for (const k of Object.keys(r)) {
+    if (!(KEYS as readonly string[]).includes(k)) problems.push(`\`${k}\` is not one of cpu, memory, disk — it is ignored`);
+  }
+  const { cpu: C, memoryMi: M, diskGi: D } = RESOURCE_BOUNDS;
+  if (r.cpu !== undefined && r.cpu !== null) {
+    // A number, or a string of one — never a list or a map coerced (`[2]`
+    // is 2 to Number(), and a map's own toString may throw).
+    const numeric = typeof r.cpu === "number" || (typeof r.cpu === "string" && /^\s*\d+(\.\d+)?\s*$/.test(r.cpu));
+    const n = numeric ? Number(r.cpu) : NaN;
+    if (!Number.isFinite(n)) problems.push(`cpu: ${shown(r.cpu)} is not a number of cores — write 2 or 0.5`);
+    else if (n < C.min || n > C.max || Math.round(n / C.step) * C.step !== n) problems.push(`cpu: ${n} is not ${C.min} to ${C.max} cores in halves — the class's cores are used`);
+    else value.cpu = n;
+  }
+  if (r.memory !== undefined && r.memory !== null) {
+    const mi = quantityMi(r.memory);
+    if (!Number.isFinite(mi)) problems.push(`memory: ${shown(r.memory)} is not a size — write 4Gi or 512Mi${/\d\s*[GM]$/.test(String(shown(r.memory))) ? " (Gi and Mi: G and M are read two ways)" : ""}`);
+    else if (mi < M.min || mi > M.max || mi % M.step !== 0) problems.push(`memory: ${shown(r.memory)} is not 256Mi to 16Gi in steps of 256Mi — the class's memory is used`);
+    else value.memory = `${mi}Mi`;
+  }
+  if (r.disk !== undefined && r.disk !== null) {
+    const mi = quantityMi(r.disk);
+    const gi = mi / 1024;
+    if (!Number.isFinite(mi)) problems.push(`disk: ${shown(r.disk)} is not a size — write 10Gi`);
+    else if (!Number.isInteger(gi) || gi < D.min || gi > D.max) problems.push(`disk: ${shown(r.disk)} is not a whole 1Gi to 40Gi — the class's disk is used`);
+    else value.disk = `${gi}Gi`;
+  }
+  return { value, problems };
+}
+
+/** For `foldrun check`: every reason, in one message, or null. */
+export function resourcesProblem(v: unknown): string | null {
+  const { problems } = readResources(v);
+  return problems.length ? problems.join("; ") : null;
+}
+
+/** Whether an override changes anything. */
+export function hasOverride(o: ResourceOverride | null | undefined): o is ResourceOverride {
+  return !!o && (o.cpu !== undefined || o.memory !== undefined || o.disk !== undefined);
+}
+
+/** An account's own `compute:` in AGENTS.md — the most its running steps may
+ *  hold together. It can only lower what the plan or install allows
+ *  (platform limits.ts accountCompute); here it is only read:
+ *
+ *    compute: { vcpu: 4, memory: 8Gi }
+ */
+export interface ComputeAsk {
+  vcpu?: number;
+  memGiB?: number;
+}
+
+export function readCompute(raw: unknown): { value: ComputeAsk; problems: string[] } {
+  const value: ComputeAsk = {};
+  const problems: string[] = [];
+  if (raw === undefined || raw === null) return { value, problems };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { value, problems: [`is ${shown(raw)}, not a map — write {vcpu: 4, memory: 8Gi}`] };
+  }
+  const r = raw as Record<string, unknown>;
+  for (const k of Object.keys(r)) {
+    if (k !== "vcpu" && k !== "memory") problems.push(`\`${k}\` is not vcpu or memory — it is ignored`);
+  }
+  if (r.vcpu !== undefined && r.vcpu !== null) {
+    const numeric = typeof r.vcpu === "number" || (typeof r.vcpu === "string" && /^\s*\d+(\.\d+)?\s*$/.test(r.vcpu));
+    const n = numeric ? Number(r.vcpu) : NaN;
+    if (!Number.isFinite(n) || n < 0.5 || Math.round(n * 2) !== n * 2) problems.push(`vcpu: ${shown(r.vcpu)} is not a number of cores, 0.5 or more in halves`);
+    else value.vcpu = n;
+  }
+  if (r.memory !== undefined && r.memory !== null) {
+    const mi = quantityMi(r.memory);
+    if (!Number.isFinite(mi) || mi < 256) problems.push(`memory: ${shown(r.memory)} is not a size of 256Mi or more — write 8Gi`);
+    else value.memGiB = mi / 1024;
+  }
+  return { value, problems };
+}
+
+export function computeProblem(v: unknown): string | null {
+  const { problems } = readCompute(v);
+  return problems.length ? problems.join("; ") : null;
+}

package/src/run-container.ts

@@ -33,6 +33,7 @@ import type { TokenPrice } from "./catalog.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET, type RuntimeSpec } from "./runtime.ts";
 import { egressCaSh, type NetworkLevel } from "./network.ts";
+import { anyMemoryMi, quantityMi, type ResourceOverride } from "./resources.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
 import type { DelegateSpec, SubagentSpec } from "./subagents.ts";
@@ -181,6 +182,8 @@ export function parseDriverMark(line: string): { name: StartupPhase; at: number
 export interface StepActuals {
   busyCpuSecs: number | null;
   peakMemBytes: number | null;
+  /** Seconds the CPU cap held the sandbox back. Absent before 26 Oct 2026. */
+  throttledSecs?: number | null;
   rxBytes: number | null;
   txBytes: number | null;
 }
@@ -619,6 +622,11 @@ function readActuals() {
   const cpuStat = read("/sys/fs/cgroup/cpu.stat");
   const usage = cpuStat?.match(/^usage_usec (\\d+)/m);
   const cpuacctNs = usage ? NaN : Number(read("/sys/fs/cgroup/cpuacct/cpuacct.usage")?.trim());
+  // Time the CPU cap held the sandbox back: v2's throttled_usec in the same
+  // cpu.stat, v1's throttled_time (nanoseconds) under gVisor. Large against
+  // busy time means the step wanted more cores than its class gives.
+  const throttledUs = cpuStat?.match(/^throttled_usec (\\d+)/m);
+  const throttledNs = throttledUs ? null : read("/sys/fs/cgroup/cpu/cpu.stat")?.match(/^throttled_time (\\d+)/m);
   const peak =
     read("/sys/fs/cgroup/memory.peak") ??
     read("/sys/fs/cgroup/memory/memory.max_usage_in_bytes") ??
@@ -638,6 +646,7 @@ function readActuals() {
         ? cpuacctNs / 1e9
         : null,
     peakMemBytes: peak ? Number(peak.trim()) || null : null,
+    throttledSecs: throttledUs ? Number(throttledUs[1]) / 1e6 : throttledNs ? Number(throttledNs[1]) / 1e9 : null,
     rxBytes: sawNet ? rx : null,
     txBytes: sawNet ? tx : null,
   };
@@ -1262,7 +1271,8 @@ export function buildFailureSummary(log: string, opts: { tail?: number; maxLines
   const key: string[] = [];
   for (const raw of log.split("\n")) {
     const line = raw.replace(/^#\d+ \d+(\.\d+)? /, "").trim();
-    if (!/^runner image:|^ERROR\b|^error:/i.test(line) && !/did not complete successfully/.test(line)) continue;
+    // apt's own errors start "E: "; the legacy builder ends with "returned a non-zero code".
+    if (!/^runner image:|^ERROR\b|^error:|^E: /i.test(line) && !/did not complete successfully|returned a non-zero code|no space left on device/i.test(line)) continue;
     const cut = line.length > 300 ? line.slice(0, 300) + " …" : line;
     if (seen.has(cut)) continue;
     seen.add(cut);
@@ -1270,6 +1280,11 @@ export function buildFailureSummary(log: string, opts: { tail?: number; maxLines
   }
   // The ones that say what is missing first: a reader stops at the top.
   key.sort((a, b) => Number(/MISSING ENGINES/.test(b)) - Number(/MISSING ENGINES/.test(a)));
+  // A full Docker disk is the commonest cause on one machine, and the fix is
+  // not in foldrun: say it first, in plain words.
+  if (/enough free space|no space left on device/i.test(log)) {
+    key.unshift("the Docker disk is full: free space (`docker system df`, then `docker builder prune` / `docker image prune`) and run it again");
+  }
   const head = key.length
     ? key.slice(0, maxLines).map((l) => `  ${l}`).join("\n") + (key.length > maxLines ? `\n  … ${key.length - maxLines} more` : "")
     : "  (no engine or ERROR line in the log)";
@@ -1372,6 +1387,8 @@ export function parseDriverLine(
             ? {
                 busyCpuSecs: typeof parsed.res.busyCpuSecs === "number" ? parsed.res.busyCpuSecs : null,
                 peakMemBytes: typeof parsed.res.peakMemBytes === "number" ? parsed.res.peakMemBytes : null,
+                // A driver from before 26 Oct 2026 sends none: unknown, not zero.
+                throttledSecs: typeof parsed.res.throttledSecs === "number" ? parsed.res.throttledSecs : null,
                 rxBytes: typeof parsed.res.rxBytes === "number" ? parsed.res.rxBytes : null,
                 txBytes: typeof parsed.res.txBytes === "number" ? parsed.res.txBytes : null,
               }
@@ -1408,6 +1425,54 @@ function ensureRunNetwork(): string {
   return RUN_NETWORK;
 }
 
+// The cores the container engine can hand out, asked once. `--cpus` above it
+// is refused outright ("range of CPUs is from 0.01 to N"), so a heavy step
+// on a two-core server would fail before it began. The engine may be a VM
+// (Docker Desktop) with fewer cores than this machine, which is why it is
+// asked rather than read from os; podman answers a different template, and
+// an engine that does not answer falls back to this machine's count.
+let engineCpuCount: number | null = null;
+function engineCpus(): number {
+  if (engineCpuCount !== null) return engineCpuCount;
+  const out = spawnSync(cli(), ["info", "--format", "{{.NCPU}}"], { encoding: "utf8", timeout: 10_000 });
+  const n = Number((out.stdout ?? "").trim());
+  engineCpuCount = Number.isInteger(n) && n > 0 ? n : os.availableParallelism();
+  return engineCpuCount;
+}
+
+/**
+ * A memory figure Docker will accept: the mirror of k8sMemory.
+ *
+ * Docker reads b/k/m/g (binary) and refuses Kubernetes' Mi and Gi outright
+ * ("invalid suffix: 'mi'", Docker 29). The class defaults for small and
+ * heavy are Kubernetes quantities (1Gi, 8Gi), and `resources: memory` is
+ * normalised to Mi, so before 26 Oct 2026 every small and heavy step failed
+ * to start on the docker executor; only large's `2g` worked. Binary suffixes
+ * become whole bytes (1.5Gi has no Docker spelling), Docker's own pass
+ * through, and anything else is handed over for Docker's error to name.
+ */
+export function dockerMemory(value: string): string {
+  const s = String(value).trim();
+  // Lowercase only: case decides, as in k8sMemory — `1G` is Kubernetes'
+  // decimal gigabyte, and Docker would read it as binary.
+  if (/^\d+(\.\d+)?[bkmg]?$/.test(s)) return s;
+  const m = /^(\d+(?:\.\d+)?)(Ki|Mi|Gi|Ti|K|M|G|T)$/.exec(s);
+  if (!m) return s;
+  const pow: Record<string, number> = { Ki: 1, Mi: 2, Gi: 3, Ti: 4 };
+  const dec: Record<string, number> = { K: 1e3, M: 1e6, G: 1e9, T: 1e12 };
+  const bytes = m[2] in pow ? Number(m[1]) * 1024 ** pow[m[2]] : Number(m[1]) * dec[m[2]];
+  return String(Math.round(bytes));
+}
+
+/** The `--cpus` a step's container gets: its class's billed cores, no more
+ *  than the engine has. Null when the figure is not a number, so the flag is
+ *  left off rather than failing the step on an install's typo. */
+export function dockerCpus(cpus: string, available: number = engineCpus()): string | null {
+  const n = Number(cpus);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return String(Math.min(n, available));
+}
+
 export interface RunInContainerArgs {
   workspaceRoot: string;
   libraryRoot: string;
@@ -1435,6 +1500,9 @@ export interface RunInContainerArgs {
   stopRequested?: () => boolean;
   /** The reservation class — which limits this step's sandbox holds. */
   size?: "small" | "large" | "heavy";
+  /** The class's figures with the agent's `resources:` over them
+   *  (resolveResources). Absent: the class's own. */
+  limits?: StepLimits;
   /** 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
@@ -1549,8 +1617,8 @@ export function sizeLimits(size?: "small" | "large" | "heavy"): { cpus: string;
     // For steps that render a browser or hold real data. The memory figure is
     // a hard ceiling (memory is not compressible — over it, the kernel OOM-kills
     // the pod, which on a single-box install can take neighbours with it). The
-    // cpus figure is a billing weight, not a ceiling: on k8s the pod bursts CPU
-    // freely, and this is the rate its seconds are priced at.
+    // cpus figure is both the rate its seconds are priced at and, since
+    // 26 Oct 2026, the cores the sandbox is capped at.
     return {
       cpus: process.env.FOLDRUN_RUNNER_CPUS_HEAVY ?? "4",
       memory: process.env.FOLDRUN_RUNNER_MEMORY_HEAVY ?? "8Gi",
@@ -1562,6 +1630,66 @@ export function sizeLimits(size?: "small" | "large" | "heavy"): { cpus: string;
   };
 }
 
+/** What one step's sandbox holds: cores and memory (each a hard limit and a
+ *  billing figure) and, where the agent set it, disk. */
+export interface StepLimits {
+  cpus: string;
+  memory: string;
+  /** The agent's `resources: disk`, or null for the class's (the k8s tier's
+   *  diskFor; Docker has no per-container disk cap). */
+  disk: string | null;
+}
+
+/**
+ * The class's figures with an agent's `resources:` over them, key by key.
+ *
+ * `atLeastClass` is for a retry that moved the step up a class after the
+ * cluster ended it for want of memory or disk: each override is raised to
+ * the bigger class's figure, so `memory: 3Gi` OOM-killed at large retries at
+ * heavy's 8Gi rather than the same 3Gi that already failed.
+ */
+export function resolveResources(
+  size?: "small" | "large" | "heavy",
+  override?: ResourceOverride | null,
+  opts: { atLeastClass?: boolean } = {},
+): StepLimits {
+  const base = sizeLimits(size);
+  const bigger = (mine: number, theirs: number) => (opts.atLeastClass ? Math.max(mine, theirs) : mine);
+  const baseMi = anyMemoryMi(base.memory);
+  let cpus = base.cpus;
+  if (override?.cpu !== undefined) {
+    const b = Number(base.cpus);
+    cpus = String(Number.isFinite(b) ? bigger(override.cpu, b) : override.cpu);
+  }
+  let memory = base.memory;
+  if (override?.memory !== undefined) {
+    const mi = quantityMi(override.memory);
+    memory = Number.isFinite(baseMi) && opts.atLeastClass && baseMi > mi ? base.memory : override.memory;
+  }
+  // Disk the same way: a step evicted for disk at its own `disk: 2Gi` would
+  // fail again at 2Gi, whatever class the retry moved it to.
+  let disk = override?.disk ?? null;
+  if (disk && opts.atLeastClass) {
+    const classMi = anyMemoryMi(classDisk(size));
+    if (Number.isFinite(classMi) && classMi > quantityMi(disk)) disk = null;
+  }
+  return { cpus, memory, disk };
+}
+
+/** The node disk a class may write (the k8s `ephemeral-storage` limit;
+ *  Docker has no per-container cap). Env-tunable like the cores and memory. */
+export function classDisk(size?: "small" | "large" | "heavy"): string {
+  if (size === "small") return process.env.FOLDRUN_RUNNER_DISK_SMALL ?? "2Gi";
+  if (size === "heavy") return process.env.FOLDRUN_RUNNER_DISK_HEAVY ?? "20Gi";
+  return process.env.FOLDRUN_RUNNER_DISK ?? "8Gi";
+}
+
+/** A memory figure in GiB, for the step's reservation record. */
+export function memoryGiB(memory: string): number {
+  const mi = anyMemoryMi(memory);
+  return Number.isFinite(mi) ? mi / 1024 : 2;
+}
+
 /** The label both executors stamp, so one name means one thing. */
 export const RUN_LABEL = "foldrun-run-id";
 
@@ -1624,6 +1752,8 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       { mode: 0o600 },
     );
 
+    const lim = args.limits ?? resolveResources(args.size);
+    const cpus = dockerCpus(lim.cpus);
     const flags = [
       "--security-opt", "no-new-privileges",
       ...(args.runId ? ["--label", `${RUN_LABEL}=${args.runId}`] : []),
@@ -1633,10 +1763,11 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       "--cap-add", "CHOWN", "--cap-add", "SETUID", "--cap-add", "SETGID",
       "--pids-limit", "512",
       // Memory is a hard ceiling (not compressible — an OOM protects the host).
-      // CPU is deliberately NOT capped, matching the k8s path: a cap only
-      // throttles work the customer pays for, and the tier's cpu figure is a
-      // billing weight, applied in usage.ts, not a docker --cpus limit here.
-      "--memory", sizeLimits(args.size).memory,
+      // CPU is capped at the class's billed cores, matching the k8s path
+      // (since 26 Oct 2026): a step runs on what it pays for and cannot take
+      // the whole machine from the steps beside it.
+      "--memory", dockerMemory(lim.memory),
+      ...(cpus ? ["--cpus", cpus] : []),
       "--env-file", envFile,
     ];
     // gVisor (or kata) where the host has it: one env var, because the flag