@foldrun/core 2.12.1 → 2.13.0

package/dist/src/completions.js

@@ -94,6 +94,7 @@ const FIELDS = {
         { 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/dist/src/frontmatter-fields.js

@@ -34,6 +34,7 @@ const AGENT = [
     { 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" },
@@ -84,6 +85,7 @@ const AGENTS_MD = [
     { 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" },
@@ -191,7 +193,7 @@ const SAID_WHAT_IT_IS = [
 const JOB_FIELDS = {
     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"],
@@ -199,7 +201,7 @@ const JOB_FIELDS = {
         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/dist/src/frontmatter-schema.js

@@ -7,6 +7,7 @@ import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS
 import { budgetProblem } from "./budget.js";
 import { cronProblem } from "./cron.js";
 import { modelSecretCollision } from "./model-credential.js";
+import { resourcesProblem, computeProblem } from "./resources.js";
 export { FRONTMATTER, schemaKindOf } from "./frontmatter-fields.js";
 /** A value for a message: a scalar as written, anything else by its shape.
  *  Never String() of a map — its `toString` is whatever the YAML says. */
@@ -31,11 +32,13 @@ const CHECKS = {
         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/dist/src/resources.d.ts

@@ -0,0 +1,59 @@
+/** What an agent may ask for, and in what steps. */
+export declare const RESOURCE_BOUNDS: {
+    readonly cpu: {
+        readonly min: 0.5;
+        readonly max: 8;
+        readonly step: 0.5;
+    };
+    readonly memoryMi: {
+        readonly min: 256;
+        readonly max: number;
+        readonly step: 256;
+    };
+    readonly diskGi: {
+        readonly min: 1;
+        readonly max: 40;
+        readonly step: 1;
+    };
+};
+/** 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;
+}
+/** 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 declare function quantityMi(q: unknown): number;
+/** 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 declare function anyMemoryMi(q: unknown): number;
+/** 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 declare function readResources(raw: unknown): {
+    value: ResourceOverride;
+    problems: string[];
+};
+/** For `foldrun check`: every reason, in one message, or null. */
+export declare function resourcesProblem(v: unknown): string | null;
+/** Whether an override changes anything. */
+export declare function hasOverride(o: ResourceOverride | null | undefined): o is ResourceOverride;
+/** 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 declare function readCompute(raw: unknown): {
+    value: ComputeAsk;
+    problems: string[];
+};
+export declare function computeProblem(v: unknown): string | null;

package/dist/src/resources.js

@@ -0,0 +1,142 @@
+// 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 },
+};
+const KEYS = ["cpu", "memory", "disk"];
+/** 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) {
+    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) {
+    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 = { 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 = { 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) => (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) {
+    const value = {};
+    const problems = [];
+    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;
+    for (const k of Object.keys(r)) {
+        if (!KEYS.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) {
+    const { problems } = readResources(v);
+    return problems.length ? problems.join("; ") : null;
+}
+/** Whether an override changes anything. */
+export function hasOverride(o) {
+    return !!o && (o.cpu !== undefined || o.memory !== undefined || o.disk !== undefined);
+}
+export function readCompute(raw) {
+    const value = {};
+    const problems = [];
+    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;
+    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) {
+    const { problems } = readCompute(v);
+    return problems.length ? problems.join("; ") : null;
+}

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

@@ -6,6 +6,7 @@ import type { CallIo, EventExtra, ExecUsage } from "./step-exec.ts";
 import type { TokenPrice } from "./catalog.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import { type NetworkLevel } from "./network.ts";
+import { 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";
@@ -144,6 +145,8 @@ export declare function parseDriverMark(line: string): {
 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;
 }
@@ -296,7 +299,7 @@ export declare function runtimeCacheMount(tenant: string | undefined): {
     target: string;
 } | null;
 /** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
-export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { buildDelegateTools } = await import(\"@foldrun/core/delegate-tools\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n  // sandbox: own sub-agents: a tool each, whose job runs in its own sandbox\n  // on the worker, reached over the same proxy door.\n  const delegate = input.delegates?.length ? buildDelegateTools({ specs: input.delegates, channel, emit, timeoutSec: input.timeoutSec, workspaceRoot: \"/workspace\" }) : { server: null };\n\n  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept\n  // fresh through the proxy's /identity door, which mints only what this\n  // step's lease was granted. Fetched before the step starts, renewed five\n  // minutes before it expires (with jitter); a failure is said and retried.\n  // Plain JS: this text is the driver, not TypeScript.\n  const identityNames = (env.FOLDRUN_IDENTITIES || \"\").split(\",\").filter(Boolean);\n  if (identityNames.length) {\n    // No backslashes: this sits inside a template literal, which eats them.\n    const ep = new RegExp(\"^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$\").exec(env.FOLDRUN_EGRESS || \"\");\n    const dir = env.FOLDRUN_IDENTITY_DIR || \"/tmp/foldrun-identity\";\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    const keepFresh = async (name) => {\n      let wait = 30000;\n      try {\n        if (!ep) throw new Error(\"no egress proxy to ask\");\n        const res = await fetch(ep[1] + \"/identity/\" + ep[2] + \"/\" + name, { signal: AbortSignal.timeout(15000) });\n        const body = await res.json().catch(() => ({}));\n        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || (\"proxy answered \" + res.status));\n        const file = dir + \"/\" + name.toLowerCase() + \".jwt\";\n        fs.writeFileSync(file + \".tmp\", body.token, { mode: 0o600 });\n        fs.renameSync(file + \".tmp\", file);\n        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);\n      } catch (err) {\n        emit(\"error\", \"identity \" + name + \": \" + (err && err.message ? err.message : String(err)) + \" \u2014 trying again in 30s\");\n      }\n      setTimeout(() => { void keepFresh(name); }, wait).unref();\n    };\n    await Promise.all(identityNames.map(keepFresh));\n  }\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(delegate.server ? { foldrun_delegate: delegate.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
+export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  // Time the CPU cap held the sandbox back: v2's throttled_usec in the same\n  // cpu.stat, v1's throttled_time (nanoseconds) under gVisor. Large against\n  // busy time means the step wanted more cores than its class gives.\n  const throttledUs = cpuStat?.match(/^throttled_usec (\\d+)/m);\n  const throttledNs = throttledUs ? null : read(\"/sys/fs/cgroup/cpu/cpu.stat\")?.match(/^throttled_time (\\d+)/m);\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    throttledSecs: throttledUs ? Number(throttledUs[1]) / 1e6 : throttledNs ? Number(throttledNs[1]) / 1e9 : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { buildDelegateTools } = await import(\"@foldrun/core/delegate-tools\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n  // sandbox: own sub-agents: a tool each, whose job runs in its own sandbox\n  // on the worker, reached over the same proxy door.\n  const delegate = input.delegates?.length ? buildDelegateTools({ specs: input.delegates, channel, emit, timeoutSec: input.timeoutSec, workspaceRoot: \"/workspace\" }) : { server: null };\n\n  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept\n  // fresh through the proxy's /identity door, which mints only what this\n  // step's lease was granted. Fetched before the step starts, renewed five\n  // minutes before it expires (with jitter); a failure is said and retried.\n  // Plain JS: this text is the driver, not TypeScript.\n  const identityNames = (env.FOLDRUN_IDENTITIES || \"\").split(\",\").filter(Boolean);\n  if (identityNames.length) {\n    // No backslashes: this sits inside a template literal, which eats them.\n    const ep = new RegExp(\"^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$\").exec(env.FOLDRUN_EGRESS || \"\");\n    const dir = env.FOLDRUN_IDENTITY_DIR || \"/tmp/foldrun-identity\";\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    const keepFresh = async (name) => {\n      let wait = 30000;\n      try {\n        if (!ep) throw new Error(\"no egress proxy to ask\");\n        const res = await fetch(ep[1] + \"/identity/\" + ep[2] + \"/\" + name, { signal: AbortSignal.timeout(15000) });\n        const body = await res.json().catch(() => ({}));\n        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || (\"proxy answered \" + res.status));\n        const file = dir + \"/\" + name.toLowerCase() + \".jwt\";\n        fs.writeFileSync(file + \".tmp\", body.token, { mode: 0o600 });\n        fs.renameSync(file + \".tmp\", file);\n        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);\n      } catch (err) {\n        emit(\"error\", \"identity \" + name + \": \" + (err && err.message ? err.message : String(err)) + \" \u2014 trying again in 30s\");\n      }\n      setTimeout(() => { void keepFresh(name); }, wait).unref();\n    };\n    await Promise.all(identityNames.map(keepFresh));\n  }\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(delegate.server ? { foldrun_delegate: delegate.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
 /** The uv release copied into the image. Pinned: a floating uv is a floating
  *  resolver, and the runtime cache is keyed on the declaration, not on it. */
 export declare const UV_VERSION = "0.11.25";
@@ -406,6 +409,22 @@ export declare function parseDriverLine(line: string): {
 } | ({
     e: "done";
 } & ContainerStepOutcome) | null;
+/**
+ * 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 declare function dockerMemory(value: string): string;
+/** 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 declare function dockerCpus(cpus: string, available?: number): string | null;
 export interface RunInContainerArgs {
     workspaceRoot: string;
     libraryRoot: string;
@@ -436,6 +455,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
@@ -506,6 +528,31 @@ export declare function sizeLimits(size?: "small" | "large" | "heavy"): {
     cpus: string;
     memory: 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 declare function resolveResources(size?: "small" | "large" | "heavy", override?: ResourceOverride | null, opts?: {
+    atLeastClass?: boolean;
+}): StepLimits;
+/** 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 declare function classDisk(size?: "small" | "large" | "heavy"): string;
+/** A memory figure in GiB, for the step's reservation record. */
+export declare function memoryGiB(memory: string): number;
 /** The label both executors stamp, so one name means one thing. */
 export declare const RUN_LABEL = "foldrun-run-id";
 /**

package/dist/src/run-container.js

@@ -28,6 +28,7 @@ import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
 import { egressCaSh } from "./network.js";
+import { anyMemoryMi, quantityMi } from "./resources.js";
 import { isOperatorEvent } from "./operator.js";
 import { parseBrowserPod } from "./browser-pod.js";
 /**
@@ -466,6 +467,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") ??
@@ -485,6 +491,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,
   };
@@ -1098,7 +1105,8 @@ export function buildFailureSummary(log, opts = {}) {
     const key = [];
     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))
+        // 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))
@@ -1108,6 +1116,11 @@ export function buildFailureSummary(log, opts = {}) {
     }
     // 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)";
@@ -1205,6 +1218,8 @@ export function parseDriverLine(line) {
                     ? {
                         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,
                     }
@@ -1236,6 +1251,55 @@ function ensureRunNetwork() {
     }
     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 = null;
+function engineCpus() {
+    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) {
+    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 = { Ki: 1, Mi: 2, Gi: 3, Ti: 4 };
+    const dec = { 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, available = engineCpus()) {
+    const n = Number(cpus);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return String(Math.min(n, available));
+}
 /**
  * What crosses into the container as its environment, and how.
  *
@@ -1318,8 +1382,8 @@ export function sizeLimits(size) {
         // 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",
@@ -1330,6 +1394,52 @@ export function sizeLimits(size) {
         memory: process.env.FOLDRUN_RUNNER_MEMORY ?? "2g",
     };
 }
+/**
+ * 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, override, opts = {}) {
+    const base = sizeLimits(size);
+    const bigger = (mine, theirs) => (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) {
+    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) {
+    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";
 /**
@@ -1387,6 +1497,8 @@ export async function runStepInContainer(args) {
         const containerEnv = stageContainerEnv(args.env, wsIn, args.input.agentRel, args.emit);
         const envFile = path.join(staging, "env");
         fs.writeFileSync(envFile, Object.entries(containerEnv).map(([k, v]) => `${k}=${v}`).join("\n"), { 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}`] : []),
@@ -1396,10 +1508,11 @@ export async function runStepInContainer(args) {
             "--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