@foldrun/core 2.13.1 → 2.14.1

package/dist/src/frontmatter-fields.js

@@ -85,7 +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: "compute", type: "object", help: "{vcpu, memory, disk} the running steps here may hold together — the account's pool, or this workspace's; only narrows the level above" },
     { 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" },
@@ -125,6 +125,7 @@ const FLOW = [
     { key: "pause_when", type: "string", help: "a marker that pauses the flow when a run's result says it" },
     { key: "approvers", type: ["list", "string"], help: "who may approve its gates" },
     { key: "budget", type: ["number", "string"], help: "USD per run" },
+    { key: "compute", type: "object", help: "{vcpu, memory, disk} one run's steps may hold together at once — only narrows the workspace's and account's" },
     { key: "live", type: "boolean", help: "true: steps may act for real in a test run" },
 ];
 const TOOL = [

package/dist/src/frontmatter-schema.js

@@ -53,6 +53,7 @@ const CHECKS = {
         disable_after: (v) => (Number(v) > 0 && Number(v) <= 100 ? null : `${String(v)} is not a count from 1 to 100; it is ignored`),
         pause_when: (v) => (String(v).length <= 60 ? null : "is longer than 60 characters"),
         budget: (v) => budgetProblem(v, ["run"]),
+        compute: computeProblem,
     },
     "tool": {
         transport: (v) => (["http", "script", "mcp"].includes(String(v).toLowerCase()) ? null : `"${String(v)}" is not a transport — http, script or mcp`),

package/dist/src/platform.d.ts

@@ -99,6 +99,25 @@ export interface PlatformHooks {
         kind: string;
         ref: string;
     }): void;
+    /** A restarted driver's sweep of the run's orphans: destroy its
+     *  sandboxes except `keep` (the refs its steps re-attach to). Not a stop —
+     *  the run goes on, and steps of it are about to start. Optional: without
+     *  it the whole run's are killed (killRunSandboxes). */
+    killOrphanSandboxes?(runId: string, keep: readonly string[]): void;
+    /** Is there room for a step waiting in the queue to start now — by the
+     *  same rules as the executor's room gate — and if not, why. Asked before
+     *  such a step is started again, so a run claimed only to find no room
+     *  yet adds nothing to its trail. Optional: without it the step goes to
+     *  its executor, which looks there. */
+    roomCheck?(ask: {
+        tenant: string;
+        workspace: string;
+        runId: string;
+        since: string;
+        cpus: number;
+        memGiB: number;
+        diskGiB: number;
+    }): Promise<string | null>;
     /** Publish storage/public/ as share links after a run. Default: no links. */
     syncPublicShares(tenant: string, workspace: string): Promise<{
         added: string[];

package/dist/src/resources.d.ts

@@ -42,15 +42,19 @@ export declare function readResources(raw: unknown): {
 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:` — the most the steps running inside one scope may hold
+ *  together, in cores, memory and disk (27 Oct 2026: disk, and the scopes
+ *  past the account). Written in the account's AGENTS.md (its pool), a
+ *  workspace's AGENTS.md (that workspace's pool) and a flow (each run's
+ *  pool). Each level only narrows the one above it — the plan or install
+ *  caps the account (platform limits.ts). Here it is only read:
  *
- *    compute: { vcpu: 4, memory: 8Gi }
+ *    compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }
  */
 export interface ComputeAsk {
     vcpu?: number;
     memGiB?: number;
+    diskGiB?: number;
 }
 export declare function readCompute(raw: unknown): {
     value: ComputeAsk;

package/dist/src/resources.js

@@ -112,12 +112,12 @@ export function readCompute(raw) {
     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}`] };
+        return { value, problems: [`is ${shown(raw)}, not a map — write {vcpu: 4, memory: 8Gi, disk: 40Gi}`] };
     }
     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 (k !== "vcpu" && k !== "memory" && k !== "disk")
+            problems.push(`\`${k}\` is not vcpu, memory or disk — 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));
@@ -134,6 +134,13 @@ export function readCompute(raw) {
         else
             value.memGiB = mi / 1024;
     }
+    if (r.disk !== undefined && r.disk !== null) {
+        const mi = quantityMi(r.disk);
+        if (!Number.isFinite(mi) || mi < 1024)
+            problems.push(`disk: ${shown(r.disk)} is not a size of 1Gi or more — write 40Gi`);
+        else
+            value.diskGiB = mi / 1024;
+    }
     return { value, problems };
 }
 export function computeProblem(v) {

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

@@ -1,3 +1,4 @@
+import type { RoomLevel } from "./store.ts";
 import type { PeerInfo } from "./operator.ts";
 import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
@@ -152,6 +153,10 @@ export interface StepActuals {
 }
 export interface ContainerStepOutcome {
     status: "completed" | "failed";
+    /** No room to start, and the step may wait in the queue rather than here
+     *  (`room.mayDefer`): why. Nothing ran and nothing was rented — not a
+     *  failure, not an attempt. `status` is not read when this is set. */
+    deferred?: string;
     result: string | null;
     /** Why the sandbox ended when the step did not: what the cluster said
      *  (OOMKilled, Evicted, the pod gone). Absent when the driver finished
@@ -475,6 +480,18 @@ export interface RunInContainerArgs {
      *  (consumed 0), and before each output line it applies. The runner
      *  records these on the step, so the next driver knows where to attach. */
     checkpoint?: (ref: string, consumed: number) => void;
+    /** The wait for room (27 Oct 2026), for an executor with a room gate.
+     *  `since`: when this step first found none, carried across re-drives —
+     *  its place in line. `waiting` is called when it finds none (and again
+     *  when the reason changes); `mayDefer` says whether, instead of waiting
+     *  on, it may answer `deferred` so its run goes back to the queue. */
+    room?: {
+        since: string | null;
+        /** `${runId}#${step}` — breaks a tie between two equal ages. */
+        key?: string;
+        waiting: (why: string, level?: RoomLevel) => void;
+        mayDefer: () => boolean;
+    };
     /** A test run: where state/ and storage/ changes go instead of the
      *  workspace, and who to tell about each. See test-mode.ts. */
     divert?: WriteDivert;

package/dist/src/runner.js

@@ -16,7 +16,7 @@ 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, resolveResources, memoryGiB, heldCores, killRunSandboxes } from "./run-container.js";
+import { runStepInContainer, resolveResources, memoryGiB, heldCores, killRunSandboxes, classDisk } 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";
@@ -1909,7 +1909,12 @@ peerBus,
 /** Runs one job for a `sandbox: own` sub-agent as a step of its own and
  *  answers with its reply (the drive loop's delegateFor). Absent for a
  *  step that is itself a sub-agent's: depth one. */
-delegateJob) {
+delegateJob, 
+/** Whether this step, finding no room to start, may go back to the queue
+ *  with its run instead of waiting in this driver (the drive loop's
+ *  mayDefer). Absent: it waits here, however long — a rescue, a step
+ *  outside a flow, a foreground run. */
+mayDefer) {
     // Secret values are injected into scripts as environment variables and
     // substituted into API headers, so a model that reads one back — from a
     // script that prints it, an API error that echoes it, or its own `env` —
@@ -2129,7 +2134,7 @@ delegateJob) {
         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: heldCores(limits.cpus, process.env.FOLDRUN_RUN_ISOLATION), memGiB: memoryGiB(limits.memory) };
+        const held = { cpus: heldCores(limits.cpus, process.env.FOLDRUN_RUN_ISOLATION), memGiB: memoryGiB(limits.memory), diskGiB: memoryGiB(limits.disk ?? classDisk(size)) };
         // 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:
@@ -2807,6 +2812,8 @@ delegateJob) {
             };
             const primaryTranslator = proxiedTranslator(translator, MODEL_KEY_NAME);
             const secondTranslator = proxiedTranslator(fallbackTranslator, `${MODEL_KEY_NAME}_FALLBACK`);
+            // Set once the first sandbox call has run (see room.mayDefer below).
+            let executed = false;
             const runIsolated = isolation === "container" ? runStepInContainer : platform.isolation[isolation];
             const isolatedArgs = (modelEnv, keyName = MODEL_KEY_NAME) => ({
                 workspaceRoot,
@@ -2921,7 +2928,23 @@ delegateJob) {
                     if (consumed === 0)
                         step.holding = held;
                     if (consumed === 0)
+                        step.roomWait = null;
+                    if (consumed === 0)
+                        save();
+                },
+                // The wait for room: its age is the step's place in line, so it is
+                // on the record from the first "no" and survives a re-drive.
+                room: {
+                    since: step.roomWait?.since ?? null,
+                    ...(runId && stepIndex !== undefined ? { key: `${runId}#${stepIndex}` } : {}),
+                    waiting: (why, level) => {
+                        step.roomWait = { since: step.roomWait?.since ?? new Date().toISOString(), why, cpus: held.cpus, memGiB: held.memGiB, diskGiB: held.diskGiB, ...(level ? { level } : {}) };
                         save();
+                    },
+                    // Only before anything ran: a later call of this attempt (a
+                    // rotated credential, a busy provider, a re-run on the full
+                    // image) waits for room where it is — its outcome is the step's.
+                    mayDefer: () => !executed && (mayDefer?.() ?? false),
                 },
             });
             // A busy provider gets another moment on the SAME supply before the
@@ -2942,21 +2965,46 @@ delegateJob) {
                 // its first checkpoint, after any wait for room.
                 if (!platform.sandboxResumable(isolation)) {
                     step.holding = held;
+                    // Started: no longer waiting for room (an executor that can
+                    // report its sandbox clears this at its first checkpoint).
+                    step.roomWait = null;
                     save();
                 }
+                let out;
                 try {
-                    return await runIsolated(a);
+                    out = await runIsolated(a);
+                    return out;
                 }
                 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;
+                    // A call that ran, or failed, is past waiting; only a step sent
+                    // back to the queue keeps its place in line.
+                    if (!out?.deferred)
+                        step.roomWait = null;
                     save();
                 }
             };
             let attemptFrom = step.events.length;
             let outcome = await runTracked(firstArgs);
+            if (!outcome.deferred)
+                executed = true;
             step.sandbox = null; // whatever happens next starts its own
+            // No room, and the run may wait for it in the queue: nothing ran and
+            // nothing was rented, so this is neither a failure nor a try. The
+            // step goes back to pending with its place in line (roomWait).
+            if (outcome.deferred) {
+                if (lease) {
+                    await serving?.close();
+                    serving = null;
+                    await lease.release();
+                }
+                step.status = "pending";
+                push("info", `room: none yet — ${outcome.deferred}; the run waits in the queue and starts this step when there is`);
+                save();
+                return { actedThenFailedCheck: false, deferred: true };
+            }
             // A 401 from a token that rotated mid-step is not a broken key: the
             // replacement is already on its way to the mounted file. Wait for it
             // once, then fall into the same retry the busy case uses.
@@ -3168,6 +3216,7 @@ delegateJob) {
             step.size = size;
             if (hasOverride(asked.value))
                 step.resources = asked.value;
+            // Cores, GiB and disk (27 Oct 2026): all three are billed as held.
             step.reserved = held;
         }
         else {
@@ -4255,6 +4304,10 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 if (entry && entry.status === "running")
                     entry.status = "failed";
             }
+            // The sandboxes the steps below re-attach to — the orphan sweep must
+            // leave them standing (27 Oct 2026: it deleted every pod of the run,
+            // and each sibling that was about to re-attach found its pod gone).
+            const reattaching = [];
             for (const step of run.steps) {
                 if (step.status !== "running")
                     continue;
@@ -4263,6 +4316,9 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     orphaned = true;
                     step.sandbox = null;
                 }
+                else {
+                    reattaching.push(step.sandbox.ref);
+                }
                 step.status = "pending";
                 step.events.push({
                     t: new Date().toISOString(),
@@ -4277,10 +4333,14 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // `timeout:` carries no pod deadline at all — so the orphaned step
                 // may still be executing, non-idempotent work included, while the
                 // new attempt starts. Destroy it first; re-driving is only safe
-                // once nothing else is driving.
+                // once nothing else is driving. Not a stop: the run goes on, so the
+                // platform's sweep keeps the re-attaching sandboxes and leaves no
+                // stop word for the steps about to start.
                 try {
                     if (process.env.FOLDRUN_RUN_ISOLATION === "container")
                         killRunSandboxes(run.id);
+                    else if (platform.killOrphanSandboxes)
+                        platform.killOrphanSandboxes(run.id, reattaching);
                     else
                         platform.killRunSandboxes(run.id);
                 }
@@ -4447,6 +4507,12 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 run.budgetUsd = readFlow(tenant, workspace, run.flow)?.budget ?? null;
                 save();
             }
+            // compute: — the flow's run pool, stamped the same way: the cap a run
+            // is held to is on its record (27 Oct 2026).
+            if (run.compute === undefined) {
+                run.compute = readFlow(tenant, workspace, run.flow)?.compute ?? null;
+                save();
+            }
             let gi = 0;
             let context = null;
             let ctxData = undefined;
@@ -4968,8 +5034,43 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // prompt cache it wrote — see warmGate. The claim is the callback's
                 // first statement, before any await; the wait comes before the
                 // pool, so nothing holds a slot while it waits.
-                const gate = warmGate(launching);
-                await Promise.all(launching
+                // Room (27 Oct 2026): a step that finds no room may go back to the
+                // queue with its run — freeing the worker — only when nothing else
+                // of its group is under way (a sibling still running keeps the run
+                // here anyway), and only once the group has waited a while, so a
+                // short wait stays a short wait. Never on a foreground run.
+                const mayDefer = (step) => () => {
+                    if (!opts.parkOnApproval)
+                        return false;
+                    if (launching.some((s) => s !== step && s.status === "running" && !s.roomWait))
+                        return false;
+                    const since = Math.min(...launching.map((s) => (s.roomWait ? Date.parse(s.roomWait.since) : Infinity)));
+                    return Number.isFinite(since) && Date.now() - since >= roomParkAfterMs();
+                };
+                // Steps waiting in the queue for room, the run claimed again: look
+                // first, quietly, before anything (the prompt-cache gate's line
+                // included) writes to their trails. Still none — they stay pending
+                // with their place, the run parks again below, and the trail gains
+                // nothing on each look.
+                const roomStill = new Set();
+                if (platform.roomCheck) {
+                    for (const step of launching) {
+                        if (!step.roomWait || !mayDefer(step)())
+                            continue;
+                        const w = step.roomWait;
+                        const why = await platform.roomCheck({ tenant, workspace, runId: run.id, since: w.since, cpus: w.cpus, memGiB: w.memGiB, diskGiB: w.diskGiB ?? 0 }).catch(() => null);
+                        if (!why)
+                            continue;
+                        roomStill.add(step);
+                        if (why !== w.why) {
+                            step.roomWait = { ...w, why };
+                            save();
+                        }
+                    }
+                }
+                const starting = launching.filter((s) => !roomStill.has(s));
+                const gate = warmGate(starting);
+                await Promise.all(starting
                     .map(async (step) => {
                     const lead = gate.claim(step);
                     if (lead) {
@@ -5015,7 +5116,14 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     // that started it; a step re-run after a backoff picks up the
                     // count it left. Only a step nobody has touched starts at 1.
                     const interruptedInBackoff = !step.sandbox && !!step.attempts && /retrying in \d+s/.test(step.events[step.events.length - 1]?.text ?? "");
-                    const from = step.sandbox ? Math.max(1, step.attempts ?? 1) : interruptedInBackoff ? Math.min(attempts, step.attempts + 1) : 1;
+                    // A step that went back to the queue for room resumes the attempt it was on.
+                    const from = step.sandbox
+                        ? Math.max(1, step.attempts ?? 1)
+                        : step.resumeAttempt
+                            ? Math.min(attempts, step.resumeAttempt)
+                            : interruptedInBackoff
+                                ? Math.min(attempts, step.attempts + 1)
+                                : 1;
                     for (let attempt = from; attempt <= attempts; attempt++) {
                         const ceiling = ceilingFor(step);
                         // Nothing left is a refusal, not "no ceiling": a zero passed
@@ -5042,6 +5150,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         const attemptStartedAt = new Date().toISOString();
                         const eventsBefore = step.events.length;
                         step.attempts = attempt;
+                        step.resumeAttempt = null;
                         step.status = "running";
                         if (ceiling.ceilingUsd !== null)
                             reserved.set(step, ceiling.ceilingUsd);
@@ -5052,7 +5161,14 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         () => {
                             save();
                             return run.stopRequested === true;
-                        }, flowTimezone, run.steps.indexOf(step), siblingsOf(step), peerBus, delegateFor(step)).finally(() => reserved.delete(step));
+                        }, flowTimezone, run.steps.indexOf(step), siblingsOf(step), peerBus, delegateFor(step), mayDefer(step)).finally(() => reserved.delete(step));
+                        // Sent back for room: not a try. The run parks once the
+                        // group is done (below) and this attempt starts again later.
+                        if (verdict?.deferred) {
+                            step.resumeAttempt = attempt;
+                            save();
+                            return;
+                        }
                         // runStep mutates step.status; read it through a widened local
                         // so TS doesn't keep the "running" narrowing from above.
                         const outcome = step.status;
@@ -5149,6 +5265,17 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         }
                     }
                 }
+                // Steps sent back for want of room: the run waits in the queue — its
+                // row keeps its place — and comes back to this group when it is
+                // claimed again. Nothing after the group runs meanwhile.
+                if (opts.parkOnApproval && launching.some((s) => s.status === "pending" && s.roomWait)) {
+                    await harvestQuietly(tenant, workspace, run);
+                    run.status = "queued";
+                    run.parkedAt = new Date().toISOString();
+                    parked = true;
+                    save();
+                    return;
+                }
                 // on-fail: another agent takes the step over. Sequential and rare:
                 // the rescue is a second full attempt at the step's job with the
                 // failure in front of it, and its success is the step's success —
@@ -5585,6 +5712,13 @@ const ABANDONED_AFTER_MS = 2 * 60 * 1000;
 /** The first retry's wait; each one after doubles it, to sixteen times
  *  this (15 s → 4 min by default). An env, so a test can make it small. */
 const retryBaseMs = () => Number(process.env.FOLDRUN_RETRY_BASE_MS) || 15_000;
+/** How long a group waits for room in its driver before its run goes back
+ *  to the queue to wait there: FOLDRUN_ROOM_PARK_AFTER_SEC, default 60 s. */
+const roomParkAfterMs = () => {
+    const v = process.env.FOLDRUN_ROOM_PARK_AFTER_SEC;
+    const n = v ? Number(v) : NaN;
+    return Number.isFinite(n) && n >= 0 ? n * 1000 : 60_000;
+};
 /** The most recent moment a run showed any sign of life. */
 function lastActivity(run) {
     let latest = Date.parse(run.startedAt);

package/dist/src/starter.js

@@ -417,6 +417,7 @@ model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
 priority: normal         # high | normal | low — where its runs stand in the queue
+compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }  # optional: what one run may hold at once
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.

package/dist/src/store.d.ts

@@ -542,6 +542,13 @@ export interface FlowInfo {
     budget: number | null;
     /** What is wrong with the `budget:` line, or null. */
     budgetProblem: string | null;
+    /** `compute:` — what one run's steps may hold together at once (27 Oct
+     *  2026); null is no cap of its own. Copied onto each run as it starts. */
+    compute?: {
+        vcpu?: number;
+        memGiB?: number;
+        diskGiB?: number;
+    } | null;
     /** `trigger: flow` — start when this other flow of the workspace finishes,
      *  with `on:` saying which endings count. The finished run's summary and
      *  result become this run's task. */
@@ -1105,6 +1112,9 @@ export declare function isSplicedRecord(step: {
     subagentOf?: string;
     instruction?: string | null;
 }): boolean;
+/** Which cap holds a step back from starting (27 Oct 2026): its run's,
+ *  its workspace's, its account's, or the node's budget for runs. */
+export type RoomLevel = "run" | "workspace" | "account" | "node";
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1311,6 +1321,7 @@ export interface StepRecord {
     reserved?: {
         cpus: number;
         memGiB: number;
+        diskGiB?: 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
@@ -1326,7 +1337,24 @@ export interface StepRecord {
     holding?: {
         cpus: number;
         memGiB: number;
+        diskGiB?: number;
+    } | null;
+    /** Waiting for room to start (27 Oct 2026): since when — the first time
+     *  the room gate said no, kept across re-drives so its place in line is
+     *  its age — what it asked for, and why there was none. Set while it
+     *  waits in its driver and while its run waits in the queue; cleared the
+     *  moment its sandbox exists. A wait for room never fails the step. */
+    roomWait?: {
+        since: string;
+        why: string;
+        cpus: number;
+        memGiB: number;
+        diskGiB?: number;
+        level?: RoomLevel;
     } | null;
+    /** The attempt a step sent back to the queue for room resumes on — a
+     *  wait is not a try, so it spends none of its `retry:`. */
+    resumeAttempt?: 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. */
@@ -1407,6 +1435,13 @@ export interface RunRecord {
      *  a run was held to is on its record rather than read from a file that
      *  may since have changed. Null: none. */
     budgetUsd?: number | null;
+    /** The flow's `compute:` when this run was first driven — what its steps
+     *  may hold together at once, its own pool (27 Oct 2026). Null: none. */
+    compute?: {
+        vcpu?: number;
+        memGiB?: number;
+        diskGiB?: number;
+    } | null;
     /** Memory files this run created or changed, workspace-relative — what
      *  the agents decided was worth remembering, listed so a person can review
      *  the lesson without diffing the folder. */
@@ -1628,6 +1663,8 @@ export declare function runMeter(run: RunRecord): {
 export declare function runComputeMeter(run: RunRecord): {
     coreSecs: number;
     gibSecs: number;
+    /** GiB of disk allowed × seconds (27 Oct 2026): the third hold. */
+    diskGibSecs: number;
     busyCpuSecs: number;
     flatSecs: number;
 };

package/dist/src/store.js

@@ -19,6 +19,7 @@
 // or an agent, and belongs in git.
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
+import { readCompute } from "./resources.js";
 import { expandPlatformVars } from "./host-env.js";
 import { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 import fs from "node:fs";
@@ -1635,6 +1636,10 @@ export function parseFlow(file, raw) {
         priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
         budget: runBudget(data.budget),
         budgetProblem: budgetProblem(data.budget, ["run"]),
+        compute: (() => {
+            const c = readCompute(data.compute).value;
+            return Object.keys(c).length ? c : null;
+        })(),
         // `after: [[flow:publish]]` — a link or a bare name, read the same way
         // as every other file-naming field (refs.ts).
         after: (refNames(data.after)[0] ?? "").replace(/^flow:/, "").trim() || null,
@@ -3156,7 +3161,7 @@ export function runMeter(run) {
  * flat-rate fallback prices those.
  */
 export function runComputeMeter(run) {
-    let coreSecs = 0, gibSecs = 0, busyCpuSecs = 0, flatSecs = 0;
+    let coreSecs = 0, gibSecs = 0, diskGibSecs = 0, busyCpuSecs = 0, flatSecs = 0;
     for (const s of run.steps) {
         if (s.status !== "completed" && s.status !== "failed")
             continue;
@@ -3168,13 +3173,14 @@ export function runComputeMeter(run) {
         if (s.reserved) {
             coreSecs += secs * s.reserved.cpus;
             gibSecs += secs * s.reserved.memGiB;
+            diskGibSecs += secs * (s.reserved.diskGiB ?? 0);
         }
         else {
             flatSecs += secs;
         }
         busyCpuSecs += s.actual?.busyCpuSecs ?? 0;
     }
-    return { coreSecs, gibSecs, busyCpuSecs, flatSecs };
+    return { coreSecs, gibSecs, diskGibSecs, busyCpuSecs, flatSecs };
 }
 export function runDurationSecs(run) {
     if (!run.finishedAt)

package/package.json

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

package/src/frontmatter-fields.ts

@@ -131,7 +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: "compute", type: "object", help: "{vcpu, memory, disk} the running steps here may hold together — the account's pool, or this workspace's; only narrows the level above" },
   { 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" },
@@ -172,6 +172,7 @@ const FLOW: FieldSpec[] = [
   { key: "pause_when", type: "string", help: "a marker that pauses the flow when a run's result says it" },
   { key: "approvers", type: ["list", "string"], help: "who may approve its gates" },
   { key: "budget", type: ["number", "string"], help: "USD per run" },
+  { key: "compute", type: "object", help: "{vcpu, memory, disk} one run's steps may hold together at once — only narrows the workspace's and account's" },
   { key: "live", type: "boolean", help: "true: steps may act for real in a test run" },
 ];
 

package/src/frontmatter-schema.ts

@@ -55,6 +55,7 @@ const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => stri
     disable_after: (v) => (Number(v) > 0 && Number(v) <= 100 ? null : `${String(v)} is not a count from 1 to 100; it is ignored`),
     pause_when: (v) => (String(v).length <= 60 ? null : "is longer than 60 characters"),
     budget: (v) => budgetProblem(v, ["run"]),
+    compute: computeProblem,
   },
   "tool": {
     transport: (v) => (["http", "script", "mcp"].includes(String(v).toLowerCase()) ? null : `"${String(v)}" is not a transport — http, script or mcp`),

package/src/platform.ts

@@ -116,6 +116,17 @@ export interface PlatformHooks {
    *  the whole run's would take the parent too. Optional: an executor that
    *  cannot re-attach never needs it (the whole run's are killed instead). */
   killSandbox?(sandbox: { kind: string; ref: string }): void;
+  /** A restarted driver's sweep of the run's orphans: destroy its
+   *  sandboxes except `keep` (the refs its steps re-attach to). Not a stop —
+   *  the run goes on, and steps of it are about to start. Optional: without
+   *  it the whole run's are killed (killRunSandboxes). */
+  killOrphanSandboxes?(runId: string, keep: readonly string[]): void;
+  /** Is there room for a step waiting in the queue to start now — by the
+   *  same rules as the executor's room gate — and if not, why. Asked before
+   *  such a step is started again, so a run claimed only to find no room
+   *  yet adds nothing to its trail. Optional: without it the step goes to
+   *  its executor, which looks there. */
+  roomCheck?(ask: { tenant: string; workspace: string; runId: string; since: string; cpus: number; memGiB: number; diskGiB: number }): Promise<string | null>;
   /** Publish storage/public/ as share links after a run. Default: no links. */
   syncPublicShares(tenant: string, workspace: string): Promise<{ added: string[] }>;
   /** This account's own data key, or null to use the install key. */

package/src/resources.ts

@@ -109,15 +109,19 @@ export function hasOverride(o: ResourceOverride | null | undefined): o is Resour
   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:` — the most the steps running inside one scope may hold
+ *  together, in cores, memory and disk (27 Oct 2026: disk, and the scopes
+ *  past the account). Written in the account's AGENTS.md (its pool), a
+ *  workspace's AGENTS.md (that workspace's pool) and a flow (each run's
+ *  pool). Each level only narrows the one above it — the plan or install
+ *  caps the account (platform limits.ts). Here it is only read:
  *
- *    compute: { vcpu: 4, memory: 8Gi }
+ *    compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }
  */
 export interface ComputeAsk {
   vcpu?: number;
   memGiB?: number;
+  diskGiB?: number;
 }
 
 export function readCompute(raw: unknown): { value: ComputeAsk; problems: string[] } {
@@ -125,11 +129,11 @@ export function readCompute(raw: unknown): { value: ComputeAsk; problems: string
   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}`] };
+    return { value, problems: [`is ${shown(raw)}, not a map — write {vcpu: 4, memory: 8Gi, disk: 40Gi}`] };
   }
   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 (k !== "vcpu" && k !== "memory" && k !== "disk") problems.push(`\`${k}\` is not vcpu, memory or disk — 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));
@@ -142,6 +146,11 @@ export function readCompute(raw: unknown): { value: ComputeAsk; problems: string
     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;
   }
+  if (r.disk !== undefined && r.disk !== null) {
+    const mi = quantityMi(r.disk);
+    if (!Number.isFinite(mi) || mi < 1024) problems.push(`disk: ${shown(r.disk)} is not a size of 1Gi or more — write 40Gi`);
+    else value.diskGiB = mi / 1024;
+  }
   return { value, problems };
 }
 

package/src/run-container.ts

@@ -18,6 +18,7 @@
 // The runner image bundles @foldrun/core itself, so the driver runs the same
 // executeStep the server would — one implementation, two homes.
 
+import type { RoomLevel } from "./store.ts";
 import type { PeerInfo } from "./operator.ts";
 import { isHookRecord, type HookRecord } from "./hooks.ts";
 import fs from "node:fs";
@@ -190,6 +191,10 @@ export interface StepActuals {
 
 export interface ContainerStepOutcome {
   status: "completed" | "failed";
+  /** No room to start, and the step may wait in the queue rather than here
+   *  (`room.mayDefer`): why. Nothing ran and nothing was rented — not a
+   *  failure, not an attempt. `status` is not read when this is set. */
+  deferred?: string;
   result: string | null;
   /** Why the sandbox ended when the step did not: what the cluster said
    *  (OOMKilled, Evicted, the pod gone). Absent when the driver finished
@@ -1523,6 +1528,18 @@ export interface RunInContainerArgs {
    *  (consumed 0), and before each output line it applies. The runner
    *  records these on the step, so the next driver knows where to attach. */
   checkpoint?: (ref: string, consumed: number) => void;
+  /** The wait for room (27 Oct 2026), for an executor with a room gate.
+   *  `since`: when this step first found none, carried across re-drives —
+   *  its place in line. `waiting` is called when it finds none (and again
+   *  when the reason changes); `mayDefer` says whether, instead of waiting
+   *  on, it may answer `deferred` so its run goes back to the queue. */
+  room?: {
+    since: string | null;
+    /** `${runId}#${step}` — breaks a tie between two equal ages. */
+    key?: string;
+    waiting: (why: string, level?: RoomLevel) => void;
+    mayDefer: () => boolean;
+  };
   /** A test run: where state/ and storage/ changes go instead of the
    *  workspace, and who to tell about each. See test-mode.ts. */
   divert?: WriteDivert;

package/src/runner.ts

@@ -19,7 +19,7 @@ import { cascadeLimits, toolOwners } from "./limits.ts";
 import { resolveAgentPath } from "./confine.ts";
 import { browserPodLine, podLossDecision, RERAN_ON_FULL } from "./browser-pod.ts";
 import { eventUrl } from "./webhook.ts";
-import { runStepInContainer, resolveResources, memoryGiB, heldCores, killRunSandboxes, type StepTiming } from "./run-container.ts";
+import { runStepInContainer, resolveResources, memoryGiB, heldCores, killRunSandboxes, classDisk, type StepTiming } from "./run-container.ts";
 import { readResources, hasOverride } from "./resources.ts";
 import { hostSafeEnv, platformApiUrl } from "./host-env.ts";
 import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken, isModelEnvName, DECLARED_ENV_PREFIX } from "./model-credential.ts";
@@ -47,6 +47,7 @@ import { sendPlainNotification } from "./notify.ts";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
 import {
+  type RoomLevel,
   accountDir,
   workspaceDir,
   buildMemoryIndex,
@@ -2093,6 +2094,11 @@ async function runStep(
    *  answers with its reply (the drive loop's delegateFor). Absent for a
    *  step that is itself a sub-agent's: depth one. */
   delegateJob?: (agent: string, job: string, cancelled: () => boolean) => Promise<DelegationResult>,
+  /** Whether this step, finding no room to start, may go back to the queue
+   *  with its run instead of waiting in this driver (the drive loop's
+   *  mayDefer). Absent: it waits here, however long — a rescue, a step
+   *  outside a flow, a foreground run. */
+  mayDefer?: () => boolean,
 ) {
   // Secret values are injected into scripts as environment variables and
   // substituted into API headers, so a model that reads one back — from a
@@ -2322,7 +2328,7 @@ async function runStep(
     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: heldCores(limits.cpus, process.env.FOLDRUN_RUN_ISOLATION), memGiB: memoryGiB(limits.memory) };
+    const held = { cpus: heldCores(limits.cpus, process.env.FOLDRUN_RUN_ISOLATION), memGiB: memoryGiB(limits.memory), diskGiB: memoryGiB(limits.disk ?? classDisk(size)) };
 
     // oauth2 secrets become live access tokens here — the one async moment
     // in secret resolution, at the last host-side point before anything is
@@ -3018,6 +3024,8 @@ async function runStep(
       };
       const primaryTranslator = proxiedTranslator(translator, MODEL_KEY_NAME);
       const secondTranslator = proxiedTranslator(fallbackTranslator, `${MODEL_KEY_NAME}_FALLBACK`);
+      // Set once the first sandbox call has run (see room.mayDefer below).
+      let executed = false;
       const runIsolated = isolation === "container" ? runStepInContainer : platform.isolation[isolation!]!;
       const isolatedArgs = (modelEnv: Record<string, string | undefined>, keyName = MODEL_KEY_NAME) => ({
         workspaceRoot,
@@ -3132,8 +3140,23 @@ async function runStep(
           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) step.roomWait = null;
           if (consumed === 0) save();
         },
+        // The wait for room: its age is the step's place in line, so it is
+        // on the record from the first "no" and survives a re-drive.
+        room: {
+          since: step.roomWait?.since ?? null,
+          ...(runId && stepIndex !== undefined ? { key: `${runId}#${stepIndex}` } : {}),
+          waiting: (why: string, level?: RoomLevel) => {
+            step.roomWait = { since: step.roomWait?.since ?? new Date().toISOString(), why, cpus: held.cpus, memGiB: held.memGiB, diskGiB: held.diskGiB, ...(level ? { level } : {}) };
+            save();
+          },
+          // Only before anything ran: a later call of this attempt (a
+          // rotated credential, a busy provider, a re-run on the full
+          // image) waits for room where it is — its outcome is the step's.
+          mayDefer: () => !executed && (mayDefer?.() ?? false),
+        },
       });
 
       // A busy provider gets another moment on the SAME supply before the
@@ -3154,20 +3177,43 @@ async function runStep(
         // its first checkpoint, after any wait for room.
         if (!platform.sandboxResumable(isolation!)) {
           step.holding = held;
+          // Started: no longer waiting for room (an executor that can
+          // report its sandbox clears this at its first checkpoint).
+          step.roomWait = null;
           save();
         }
+        let out: Awaited<ReturnType<typeof runIsolated>> | undefined;
         try {
-          return await runIsolated(a);
+          out = await runIsolated(a);
+          return out;
         } 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;
+          // A call that ran, or failed, is past waiting; only a step sent
+          // back to the queue keeps its place in line.
+          if (!out?.deferred) step.roomWait = null;
           save();
         }
       };
       let attemptFrom = step.events.length;
       let outcome = await runTracked(firstArgs);
+      if (!outcome.deferred) executed = true;
       step.sandbox = null; // whatever happens next starts its own
+      // No room, and the run may wait for it in the queue: nothing ran and
+      // nothing was rented, so this is neither a failure nor a try. The
+      // step goes back to pending with its place in line (roomWait).
+      if (outcome.deferred) {
+        if (lease) {
+          await serving?.close();
+          serving = null;
+          await lease.release();
+        }
+        step.status = "pending";
+        push("info", `room: none yet — ${outcome.deferred}; the run waits in the queue and starts this step when there is`);
+        save();
+        return { actedThenFailedCheck: false, deferred: true };
+      }
       // A 401 from a token that rotated mid-step is not a broken key: the
       // replacement is already on its way to the mounted file. Wait for it
       // once, then fall into the same retry the busy case uses.
@@ -3378,6 +3424,7 @@ async function runStep(
       // from the record, never from what the config says at billing time.
       step.size = size;
       if (hasOverride(asked.value)) step.resources = asked.value;
+      // Cores, GiB and disk (27 Oct 2026): all three are billed as held.
       step.reserved = held;
     } else {
       // Same withholding as the sandbox path — the in-process step is what
@@ -4497,12 +4544,18 @@ function driveRunInner(
         const entry = parent?.delegations?.find((d) => d.id === step.delegation);
         if (entry && entry.status === "running") entry.status = "failed";
       }
+      // The sandboxes the steps below re-attach to — the orphan sweep must
+      // leave them standing (27 Oct 2026: it deleted every pod of the run,
+      // and each sibling that was about to re-attach found its pod gone).
+      const reattaching: string[] = [];
       for (const step of run.steps) {
         if (step.status !== "running") continue;
         const resumable = !!step.sandbox && platform.sandboxResumable(step.sandbox.kind);
         if (!resumable) {
           orphaned = true;
           step.sandbox = null;
+        } else {
+          reattaching.push(step.sandbox!.ref);
         }
         step.status = "pending";
         step.events.push({
@@ -4518,9 +4571,12 @@ function driveRunInner(
         // `timeout:` carries no pod deadline at all — so the orphaned step
         // may still be executing, non-idempotent work included, while the
         // new attempt starts. Destroy it first; re-driving is only safe
-        // once nothing else is driving.
+        // once nothing else is driving. Not a stop: the run goes on, so the
+        // platform's sweep keeps the re-attaching sandboxes and leaves no
+        // stop word for the steps about to start.
         try {
           if (process.env.FOLDRUN_RUN_ISOLATION === "container") killRunSandboxes(run.id);
+          else if (platform.killOrphanSandboxes) platform.killOrphanSandboxes(run.id, reattaching);
           else platform.killRunSandboxes(run.id);
         } catch {
           // a sandbox we cannot reach must not stop the run from resuming
@@ -4683,6 +4739,12 @@ function driveRunInner(
         run.budgetUsd = readFlow(tenant, workspace, run.flow)?.budget ?? null;
         save();
       }
+      // compute: — the flow's run pool, stamped the same way: the cap a run
+      // is held to is on its record (27 Oct 2026).
+      if (run.compute === undefined) {
+        run.compute = readFlow(tenant, workspace, run.flow)?.compute ?? null;
+        save();
+      }
 
       let gi = 0;
       let context: string | null = null;
@@ -5227,9 +5289,40 @@ function driveRunInner(
         // prompt cache it wrote — see warmGate. The claim is the callback's
         // first statement, before any await; the wait comes before the
         // pool, so nothing holds a slot while it waits.
-        const gate = warmGate(launching);
+        // Room (27 Oct 2026): a step that finds no room may go back to the
+        // queue with its run — freeing the worker — only when nothing else
+        // of its group is under way (a sibling still running keeps the run
+        // here anyway), and only once the group has waited a while, so a
+        // short wait stays a short wait. Never on a foreground run.
+        const mayDefer = (step: StepRecord) => () => {
+          if (!opts.parkOnApproval) return false;
+          if (launching.some((s) => s !== step && s.status === "running" && !s.roomWait)) return false;
+          const since = Math.min(...launching.map((s) => (s.roomWait ? Date.parse(s.roomWait.since) : Infinity)));
+          return Number.isFinite(since) && Date.now() - since >= roomParkAfterMs();
+        };
+        // Steps waiting in the queue for room, the run claimed again: look
+        // first, quietly, before anything (the prompt-cache gate's line
+        // included) writes to their trails. Still none — they stay pending
+        // with their place, the run parks again below, and the trail gains
+        // nothing on each look.
+        const roomStill = new Set<StepRecord>();
+        if (platform.roomCheck) {
+          for (const step of launching) {
+            if (!step.roomWait || !mayDefer(step)()) continue;
+            const w = step.roomWait;
+            const why = await platform.roomCheck({ tenant, workspace, runId: run.id, since: w.since, cpus: w.cpus, memGiB: w.memGiB, diskGiB: w.diskGiB ?? 0 }).catch(() => null);
+            if (!why) continue;
+            roomStill.add(step);
+            if (why !== w.why) {
+              step.roomWait = { ...w, why };
+              save();
+            }
+          }
+        }
+        const starting = launching.filter((s) => !roomStill.has(s));
+        const gate = warmGate(starting);
         await Promise.all(
-          launching
+          starting
             .map(async (step) => {
               const lead = gate.claim(step);
               if (lead) {
@@ -5275,7 +5368,14 @@ function driveRunInner(
               // count it left. Only a step nobody has touched starts at 1.
               const interruptedInBackoff =
                 !step.sandbox && !!step.attempts && /retrying in \d+s/.test(step.events[step.events.length - 1]?.text ?? "");
-              const from = step.sandbox ? Math.max(1, step.attempts ?? 1) : interruptedInBackoff ? Math.min(attempts, step.attempts! + 1) : 1;
+              // A step that went back to the queue for room resumes the attempt it was on.
+              const from = step.sandbox
+                ? Math.max(1, step.attempts ?? 1)
+                : step.resumeAttempt
+                  ? Math.min(attempts, step.resumeAttempt)
+                  : interruptedInBackoff
+                    ? Math.min(attempts, step.attempts! + 1)
+                    : 1;
               for (let attempt = from; attempt <= attempts; attempt++) {
                 const ceiling = ceilingFor(step);
                 // Nothing left is a refusal, not "no ceiling": a zero passed
@@ -5303,6 +5403,7 @@ function driveRunInner(
                 const attemptStartedAt = new Date().toISOString();
                 const eventsBefore = step.events.length;
                 step.attempts = attempt;
+                step.resumeAttempt = null;
                 step.status = "running";
                 if (ceiling.ceilingUsd !== null) reserved.set(step, ceiling.ceilingUsd);
                 save();
@@ -5331,7 +5432,15 @@ function driveRunInner(
                   siblingsOf(step),
                   peerBus,
                   delegateFor(step),
+                  mayDefer(step),
                 ).finally(() => reserved.delete(step));
+                // Sent back for room: not a try. The run parks once the
+                // group is done (below) and this attempt starts again later.
+                if (verdict?.deferred) {
+                  step.resumeAttempt = attempt;
+                  save();
+                  return;
+                }
                 // runStep mutates step.status; read it through a widened local
                 // so TS doesn't keep the "running" narrowing from above.
                 const outcome: string = step.status;
@@ -5426,6 +5535,18 @@ function driveRunInner(
               }
         }
 
+        // Steps sent back for want of room: the run waits in the queue — its
+        // row keeps its place — and comes back to this group when it is
+        // claimed again. Nothing after the group runs meanwhile.
+        if (opts.parkOnApproval && launching.some((s) => s.status === "pending" && s.roomWait)) {
+          await harvestQuietly(tenant, workspace, run);
+          run.status = "queued";
+          run.parkedAt = new Date().toISOString();
+          parked = true;
+          save();
+          return;
+        }
+
         // on-fail: another agent takes the step over. Sequential and rare:
         // the rescue is a second full attempt at the step's job with the
         // failure in front of it, and its success is the step's success —
@@ -5868,6 +5989,13 @@ const ABANDONED_AFTER_MS = 2 * 60 * 1000;
 /** The first retry's wait; each one after doubles it, to sixteen times
  *  this (15 s → 4 min by default). An env, so a test can make it small. */
 const retryBaseMs = () => Number(process.env.FOLDRUN_RETRY_BASE_MS) || 15_000;
+/** How long a group waits for room in its driver before its run goes back
+ *  to the queue to wait there: FOLDRUN_ROOM_PARK_AFTER_SEC, default 60 s. */
+const roomParkAfterMs = () => {
+  const v = process.env.FOLDRUN_ROOM_PARK_AFTER_SEC;
+  const n = v ? Number(v) : NaN;
+  return Number.isFinite(n) && n >= 0 ? n * 1000 : 60_000;
+};
 
 /** The most recent moment a run showed any sign of life. */
 function lastActivity(run: RunRecord): number {

package/src/starter.ts

@@ -433,6 +433,7 @@ model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
 priority: normal         # high | normal | low — where its runs stand in the queue
+compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }  # optional: what one run may hold at once
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.

package/src/store.ts

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
+import { readCompute } from "./resources.ts";
 import { expandPlatformVars } from "./host-env.ts";
 import { EFFORT_LEVELS, FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
@@ -1386,6 +1387,9 @@ export interface FlowInfo {
   budget: number | null;
   /** What is wrong with the `budget:` line, or null. */
   budgetProblem: string | null;
+  /** `compute:` — what one run's steps may hold together at once (27 Oct
+   *  2026); null is no cap of its own. Copied onto each run as it starts. */
+  compute?: { vcpu?: number; memGiB?: number; diskGiB?: number } | null;
   /** `trigger: flow` — start when this other flow of the workspace finishes,
    *  with `on:` saying which endings count. The finished run's summary and
    *  result become this run's task. */
@@ -2080,6 +2084,10 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     priority: data.priority === "high" || data.priority === "low" || data.priority === "normal" ? data.priority : null,
     budget: runBudget(data.budget),
     budgetProblem: budgetProblem(data.budget, ["run"]),
+    compute: (() => {
+      const c = readCompute(data.compute).value;
+      return Object.keys(c).length ? c : null;
+    })(),
     // `after: [[flow:publish]]` — a link or a bare name, read the same way
     // as every other file-naming field (refs.ts).
     after: (refNames(data.after)[0] ?? "").replace(/^flow:/, "").trim() || null,
@@ -3335,6 +3343,10 @@ export function isSplicedRecord(step: { rescueOf?: string; subagentOf?: string;
   return !!step.subagentOf || isRescueRecord(step);
 }
 
+/** Which cap holds a step back from starting (27 Oct 2026): its run's,
+ *  its workspace's, its account's, or the node's budget for runs. */
+export type RoomLevel = "run" | "workspace" | "account" | "node";
+
 export interface StepRecord {
   agent: string;
   instruction: string;
@@ -3532,7 +3544,7 @@ export interface StepRecord {
    *  from what the config says when the bill is computed. Absent on steps
    *  from before sizes existed — billing falls back to the flat rate. */
   size?: "small" | "large" | "heavy";
-  reserved?: { cpus: number; memGiB: number } | null;
+  reserved?: { cpus: number; memGiB: number; diskGiB?: 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. */
@@ -3540,7 +3552,16 @@ export interface StepRecord {
   /** 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;
+  holding?: { cpus: number; memGiB: number; diskGiB?: number } | null;
+  /** Waiting for room to start (27 Oct 2026): since when — the first time
+   *  the room gate said no, kept across re-drives so its place in line is
+   *  its age — what it asked for, and why there was none. Set while it
+   *  waits in its driver and while its run waits in the queue; cleared the
+   *  moment its sandbox exists. A wait for room never fails the step. */
+  roomWait?: { since: string; why: string; cpus: number; memGiB: number; diskGiB?: number; level?: RoomLevel } | null;
+  /** The attempt a step sent back to the queue for room resumes on — a
+   *  wait is not a try, so it spends none of its `retry:`. */
+  resumeAttempt?: 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. */
@@ -3622,6 +3643,9 @@ export interface RunRecord {
    *  a run was held to is on its record rather than read from a file that
    *  may since have changed. Null: none. */
   budgetUsd?: number | null;
+  /** The flow's `compute:` when this run was first driven — what its steps
+   *  may hold together at once, its own pool (27 Oct 2026). Null: none. */
+  compute?: { vcpu?: number; memGiB?: number; diskGiB?: number } | null;
   /** Memory files this run created or changed, workspace-relative — what
    *  the agents decided was worth remembering, listed so a person can review
    *  the lesson without diffing the folder. */
@@ -4234,10 +4258,12 @@ export function runMeter(run: RunRecord): {
 export function runComputeMeter(run: RunRecord): {
   coreSecs: number;
   gibSecs: number;
+  /** GiB of disk allowed × seconds (27 Oct 2026): the third hold. */
+  diskGibSecs: number;
   busyCpuSecs: number;
   flatSecs: number;
 } {
-  let coreSecs = 0, gibSecs = 0, busyCpuSecs = 0, flatSecs = 0;
+  let coreSecs = 0, gibSecs = 0, diskGibSecs = 0, busyCpuSecs = 0, flatSecs = 0;
   for (const s of run.steps) {
     if (s.status !== "completed" && s.status !== "failed") continue;
     if (s.carriedFrom) continue;
@@ -4246,12 +4272,13 @@ export function runComputeMeter(run: RunRecord): {
     if (s.reserved) {
       coreSecs += secs * s.reserved.cpus;
       gibSecs += secs * s.reserved.memGiB;
+      diskGibSecs += secs * (s.reserved.diskGiB ?? 0);
     } else {
       flatSecs += secs;
     }
     busyCpuSecs += s.actual?.busyCpuSecs ?? 0;
   }
-  return { coreSecs, gibSecs, busyCpuSecs, flatSecs };
+  return { coreSecs, gibSecs, diskGibSecs, busyCpuSecs, flatSecs };
 }
 
 export function runDurationSecs(run: RunRecord): number | null {