@foldrun/core 0.2.0

package/dist/src/runner.js

@@ -0,0 +1,3215 @@
+// Flow orchestration. Steps sharing a group number run in parallel; the next
+// group receives every prior result, labeled per agent. Optional steps ("2?")
+// fail without failing the flow. A direct agent run is a one-step ad-hoc
+// flow, so there is a single execution path.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { executeStep, extractJson, stepCeiling } from "./step-exec.js";
+import { eventUrl } from "./webhook.js";
+import { runStepInContainer, sizeLimits, killRunSandboxes } from "./run-container.js";
+import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute } from "./egress.js";
+import { platform } from "./platform.js";
+/** Does this process run steps in a sandbox — the container core ships, or
+ *  one the platform registered (a pod)? */
+const isolatedRun = () => {
+    const mode = process.env.FOLDRUN_RUN_ISOLATION;
+    return mode === "container" || (!!mode && mode in platform.isolation);
+};
+import { gatherConsults, buildConsultTools } from "./agent-tools.js";
+import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError } from "./tool-names.js";
+import { refNames } from "./refs.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, syncBundleFor, parseToolDef, parseFlow, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, STORAGE_DIR, adoptLegacyVersionKey, runCost, } from "./store.js";
+import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
+import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.js";
+import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
+import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
+import { attachOperations, prefetchOpenApi } from "./openapi.js";
+import { buildSearchTools, buildHistoryTools, buildDeskTools, digestRuns } from "./context-tools.js";
+import { startTranslator, translatorSpecFor } from "./translator.js";
+import { providerPreset } from "./providers.js";
+import { buildScriptTools, parseScripts } from "./script-tools.js";
+import { libraryDir, libraryTools, libraryMemoryIndex } from "./library.js";
+import { mergeRuntimes, parseRuntime, prepareRuntime } from "./runtime.js";
+import { materializeFiles, harvestFiles } from "./storage.js";
+import { chooseExecutor, ensureImage } from "./container.js";
+import { stampBundle } from "./okf.js";
+// An MCP tool definition becomes an SDK server config. ${SECRET} placeholders
+// in env and headers resolve server-side, so a credential reaches the server
+// process without ever entering the model's context.
+function mcpConfig(spec, tenant, workspace) {
+    const fill = (values) => {
+        const out = {};
+        for (const [k, v] of Object.entries(values)) {
+            out[k] = v.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, secretName) => {
+                const hit = getSecret(tenant, secretName, workspace);
+                return hit ? hit.value : whole;
+            });
+        }
+        return out;
+    };
+    // alwaysLoad: the SDK defers MCP tools behind tool search by default, which
+    // hides them from an agent whose toolset we've already narrowed. A server
+    // the author explicitly granted should be present from turn one.
+    return spec.url
+        ? { type: "http", url: spec.url, headers: fill(spec.headers), alwaysLoad: true }
+        : {
+            type: "stdio",
+            command: spec.command,
+            args: spec.args,
+            env: fill(spec.env),
+            alwaysLoad: true,
+        };
+}
+/** How much of the earlier groups' output a step is handed, in characters.
+ *  Newest groups are kept when the total is over it. */
+export const CONTEXT_CHARS = 30_000;
+/** tools: [desks] — how many other-workspace runs cross into a step, in all. */
+export const DESK_RUNS_CAP = 100;
+/**
+ * What a group is handed from the groups before it: all of them, oldest
+ * first, so a group-3 reporter sees what group 1 measured and not only what
+ * group 2 diagnosed. When the total is over the cap, the oldest groups are
+ * dropped whole before anything is cut mid-text — the newest is the one the
+ * step is most likely to be about.
+ */
+export function joinEarlierGroups(groupResults, gi, cap = CONTEXT_CHARS) {
+    const parts = [];
+    for (let i = 0; i < gi; i++)
+        if (groupResults[i])
+            parts.push(groupResults[i]);
+    if (parts.length === 0)
+        return null;
+    while (parts.length > 1 && parts.reduce((n, t) => n + t.length + 2, 0) > cap)
+        parts.shift();
+    return parts.join("\n\n");
+}
+const toTags = (v) => Array.isArray(v) ? v.map(String) : typeof v === "string" && v.trim() ? [v.trim()] : [];
+// gray-matter throws on invalid YAML. Skills authored for another client
+// sometimes ship YAML that that client's parser happened to accept — most
+// often an unquoted value containing a colon (`description: Use when: ...`).
+// The Agent Skills client guide recommends quoting such values and retrying
+// rather than dropping the skill, so a cross-client skill still loads here.
+function safeMatter(raw) {
+    // gray-matter caches by input string AND caches a *failed* parse: the first
+    // call on invalid YAML throws, but every later call on the same bytes returns
+    // a hollow object with the fields silently missing. Clearing the cache makes
+    // the throw deterministic, so the fallback below fires every time rather than
+    // once — otherwise the same skill loads on one run and vanishes on the next.
+    matter.clearCache();
+    try {
+        return matter(raw);
+    }
+    catch {
+        const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (fm) {
+            const fixed = fm[1].replace(/^([A-Za-z0-9_-]+):[ \t]+(?!["'>|])(.*:.*)$/gm, (_m, k, v) => `${k}: ${JSON.stringify(v)}`);
+            try {
+                // A function replacer, not a string: a fixed block containing `$&` or
+                // `$$` (a value with those in it) would otherwise be treated as a
+                // replacement pattern and splice the whole frontmatter into itself.
+                return matter(raw.replace(fm[1], () => fixed));
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        return { data: {} };
+    }
+}
+// Both layouts: <root>/<name>/SKILL.md (Agent Skills standard) and the flat
+// <root>/<name>.md convenience form. `subdir` is the skills root under the
+// scanned directory — "skills" (foldrun-native) or ".agents/skills" (the
+// cross-client convention other skills-compatible tools read and write).
+export function discoverSkills(agentDir, subdir = "skills") {
+    const skillsDir = path.join(agentDir, subdir);
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(skillsDir).sort()) {
+        const full = path.join(skillsDir, entry);
+        const stat = fs.statSync(full);
+        if (stat.isDirectory()) {
+            const skillMd = path.join(full, "SKILL.md");
+            if (!fs.existsSync(skillMd))
+                continue;
+            const { data } = safeMatter(fs.readFileSync(skillMd, "utf8"));
+            const description = typeof data.description === "string" ? data.description.trim() : "";
+            // The spec makes description essential — it is the only thing the model
+            // sees before activating the skill. Without one there is nothing to
+            // disclose, so the skill is skipped rather than offered blind. `check`
+            // reports it; here it is simply not loaded.
+            if (!description)
+                continue;
+            out.push({
+                name: typeof data.name === "string" && data.name ? data.name : entry,
+                description,
+                when: toTags(data.when),
+                path: `${subdir}/${entry}/SKILL.md`,
+                dir: `${subdir}/${entry}`,
+                hasScripts: fs.existsSync(path.join(full, "scripts")),
+                hasReferences: fs.existsSync(path.join(full, "references")),
+                hasAssets: fs.existsSync(path.join(full, "assets")),
+            });
+        }
+        else if (entry.endsWith(".md")) {
+            const { data } = safeMatter(fs.readFileSync(full, "utf8"));
+            const description = typeof data.description === "string" ? data.description.trim() : "";
+            if (!description)
+                continue;
+            out.push({
+                name: typeof data.name === "string" && data.name ? data.name : entry.replace(/\.md$/, ""),
+                description,
+                when: toTags(data.when),
+                path: `${subdir}/${entry}`,
+                dir: null,
+                hasScripts: false,
+                hasReferences: false,
+                hasAssets: false,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * AGENTS.md, at both scopes it can live at.
+ *
+ * `AGENTS.md` is the Linux Foundation name; `project.md` is still read so
+ * nothing written before the rename breaks.
+ *
+ * Returns null rather than throwing on unparseable YAML: a broken shared file
+ * must not take down every agent under it.
+ */
+export function readAgentsMd(dir) {
+    // Convert a pre-rename `mdagent_version:` before parsing. One name in the
+    // code, one on disk — the reader no longer knows two spellings, so a file
+    // written before the rename is migrated here rather than tolerated forever.
+    adoptLegacyVersionKey(dir);
+    for (const name of ["AGENTS.md", "project.md"]) {
+        const file = path.join(dir, name);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            const parsed = matter(fs.readFileSync(file, "utf8"));
+            return { data: parsed.data, body: parsed.content.trim() };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+const workspaceRootOf = (agentDir) => path.join(agentDir, "..", "..");
+/**
+ * Configuration from AGENTS.md, nearest-wins: the workspace's overrides the
+ * account's, key by key.
+ *
+ * Config overrides and prose accumulates — see sharedInstructions. A workspace
+ * naming its own `provider:` means *instead of* the account's; a workspace
+ * writing instructions means *as well as*, because an account rule nobody can
+ * silently drop is the point of having one.
+ */
+function workspaceFrontmatter(agentDir, tenant) {
+    return {
+        ...(readAgentsMd(accountDir(tenant))?.data ?? {}),
+        ...(readAgentsMd(workspaceRootOf(agentDir))?.data ?? {}),
+    };
+}
+/**
+ * The calendar an agent works to. `timezone:` in AGENTS.md, nearest-wins like
+ * every other key there; a flow's cron already means its own timezone, this
+ * makes "today" mean it too. Unset is UTC — what the pods run — which for a
+ * Sydney desk made an article dated today "one day in the future" until 10am.
+ * An unknown name falls back to UTC rather than failing every step.
+ */
+export function resolveTimezone(front) {
+    const tz = typeof front.timezone === "string" ? front.timezone.trim() : "";
+    const chosen = tz || process.env.FOLDRUN_TIMEZONE?.trim() || "UTC";
+    try {
+        new Intl.DateTimeFormat("en-CA", { timeZone: chosen });
+        return chosen;
+    }
+    catch {
+        return "UTC";
+    }
+}
+/** YYYY-MM-DD in a timezone — the date the workspace believes it is. */
+export function localDate(timeZone, now = new Date()) {
+    return new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).format(now);
+}
+/**
+ * The prose from AGENTS.md, outermost first.
+ *
+ * This was written by every scaffold, shown in the dashboard, described in the
+ * template as "context every agent here shares" — and never read. Only the
+ * frontmatter was, so the instructions people actually wrote reached no model.
+ */
+export function sharedInstructions(agentDir, tenant) {
+    const sections = [
+        ["Everyone in this account", readAgentsMd(accountDir(tenant))?.body],
+        ["Everyone in this workspace", readAgentsMd(workspaceRootOf(agentDir))?.body],
+    ].filter(([, body]) => body);
+    if (!sections.length)
+        return null;
+    return (`# Shared context\n\nThis applies to you in addition to your own instructions ` +
+        `above. Where it is more specific than they are, it is not optional.\n\n` +
+        sections.map(([label, body]) => `## ${label}\n\n${body}`).join("\n\n"));
+}
+/**
+ * Which of an agent's in-scope skills load for this run.
+ *
+ * Two independent gates: `skills:` in the agent's frontmatter is an allowlist
+ * (absent means everything in scope), and a skill's own `when:` names the run
+ * tags it is for (absent means every run).
+ *
+ * Note what an empty `tags` means — a skill with `when:` matches nothing, so
+ * an untagged run gets none of them. That is the intent, and it is also why
+ * failing to thread the run's tags this far made every `when:` skill
+ * permanently invisible instead of conditionally loaded.
+ */
+export function applicableSkills(skills, only, tags) {
+    return skills
+        .filter((s) => only.length === 0 || only.includes(s.name))
+        .filter((s) => s.when.length === 0 || s.when.some((t) => tags.includes(t)));
+}
+/**
+ * [[name]] as a reference to a document or file — the Obsidian instinct,
+ * honoured where it is safe. A prompt is text the model acts on, and a
+ * model cannot open "[[sources-of-conveyancers]]"; it can open
+ * `../../knowledge/sources-of-conveyancers.md`. So links resolve to real
+ * agent-relative paths BEFORE the prompt is built, matching by filename or
+ * OKF title, hyphen/underscore/case-blind. Anything unmatched — agent
+ * names, flow links, prose in brackets — passes through untouched: this is
+ * sugar over paths, never a gate in front of them.
+ */
+/**
+ * Whether an evaluator's reply actually carries its `until:` marker.
+ *
+ * Not a substring test. A reviewer that writes "APPROVED once the tribunal
+ * sentence is corrected" contains the word, and a substring match reads that
+ * conditional as a pass — the loop ends, the correction is never made, and the
+ * step after it inherits the problem the loop existed to catch. That happened:
+ * a factual error rode a conditional approval past the gate.
+ *
+ * So the marker has to stand alone on its own line, which is a thing a model
+ * does deliberately and cannot do by accident mid-sentence. Trailing
+ * punctuation is allowed ("APPROVED." is still a decision), and the line may
+ * sit anywhere in the reply, so an approval followed by notes still passes —
+ * the point is that the word is a switch, not a clause.
+ */
+export function saysUntilMarker(result, until) {
+    const marker = until.trim().toLowerCase();
+    if (!marker)
+        return true;
+    return (result ?? "")
+        .split(/\r?\n/)
+        .some((line) => 
+    // Strip markdown emphasis and punctuation from BOTH ends: "**APPROVED.**"
+    // is a decision written by someone using bold, not a sentence.
+    line
+        .trim()
+        .replace(/^[#>\-*_`\s]+/, "")
+        .replace(/[.!:,*_`\s]+$/, "")
+        .toLowerCase() === marker);
+}
+export function resolveDocLinks(text, workspaceRoot) {
+    if (!text.includes("[["))
+        return text;
+    const map = new Map();
+    const norm = (v) => v.toLowerCase().replace(/\.md$/, "").replace(/\/+$/, "").replace(/[^a-z0-9/]+/g, "-");
+    // Folders resolve too: a reference to "the file store" is as real as a
+    // reference to one file in it, and an agent told to read whatever its
+    // instruction names needs to say WHERE without naming a file. Added
+    // first, so a document that happens to share a folder's name still wins.
+    for (const dir of [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"]) {
+        if (fs.existsSync(path.join(workspaceRoot, dir)))
+            map.set(norm(dir), `../../${dir}/`);
+    }
+    for (const kind of ["knowledge", "memory"]) {
+        const dir = path.join(workspaceRoot, kind);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { recursive: true }).map(String)) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const rel = `../../${kind}/${entry.split(path.sep).join("/")}`;
+            map.set(norm(entry), rel);
+            map.set(norm(`${kind}/${entry}`), rel);
+            try {
+                const data = matter(fs.readFileSync(path.join(dir, entry), "utf8")).data;
+                // `title:` is OKF v0.2's word; `name:` is the older spelling still
+                // read, never written. A link should match what the file says it
+                // is, in either era's vocabulary.
+                for (const key of ["title", "name"]) {
+                    const v = data?.[key];
+                    if (typeof v === "string" && v)
+                        map.set(norm(v), rel);
+                }
+            }
+            catch {
+                // unparseable frontmatter still resolves by filename
+            }
+        }
+    }
+    // state/ — the cursors, snapshots and histories a scheduled desk reads from
+    // itself every run. Individual files here were not linkable for a long time
+    // while the folder was, so the one directory a recurring flow reads MOST was
+    // the one that could only be reached by typing `../../state/x.md` by hand.
+    // Indexed by path like storage/ rather than by frontmatter like knowledge/:
+    // these are data files, often .json or .csv, and many carry no frontmatter.
+    const stateDir = path.join(workspaceRoot, "state");
+    if (fs.existsSync(stateDir)) {
+        for (const entry of fs.readdirSync(stateDir, { recursive: true }).map(String)) {
+            try {
+                if (!fs.statSync(path.join(stateDir, entry)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const fwd = entry.split(path.sep).join("/");
+            const rel = `../../state/${fwd}`;
+            map.set(norm(`state/${fwd}`), rel);
+            map.set(norm(fwd), rel);
+        }
+    }
+    try {
+        // The hosted store's index lives at <tenant>/storage/<workspace>/ — beside
+        // the workspaces, not inside one. workspaceRoot is <tenant>/…/<ws>, so
+        // up two and across. Single-workspace installs have no index and fall
+        // through to the plain-directory walk below.
+        const index = JSON.parse(fs.readFileSync(path.join(workspaceRoot, "..", "..", STORAGE_DIR, path.basename(workspaceRoot), "index.json"), "utf8"));
+        for (const f of index.files ?? [])
+            map.set(norm(`${STORAGE_DIR}/${f.path}`), `../../${STORAGE_DIR}/${f.path}`);
+    }
+    catch {
+        // no file store index is normal
+    }
+    // Plain files on disk under storage/ too — local installs write there directly.
+    const filesDir = path.join(workspaceRoot, STORAGE_DIR);
+    if (fs.existsSync(filesDir)) {
+        for (const entry of fs.readdirSync(filesDir, { recursive: true }).map(String)) {
+            try {
+                if (!fs.statSync(path.join(filesDir, entry)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const fwd = entry.split(path.sep).join("/");
+            if (fwd.startsWith(".store/"))
+                continue;
+            map.set(norm(`${STORAGE_DIR}/${fwd}`), `../../${STORAGE_DIR}/${fwd}`);
+            map.set(norm(fwd), `../../${STORAGE_DIR}/${fwd}`);
+        }
+    }
+    return text.replace(/\[\[([^\]\n]+)\]\]/g, (whole, name) => {
+        const hit = map.get(norm(name.trim()));
+        return hit ? `\`${hit}\`` : whole;
+    });
+}
+function agentContext(agentDir, tenant, tags = [], 
+/** Who is running, so scripts can stamp what they write with its provenance. */
+identity = {}) {
+    // agentDir is <data>/<tenant>/projects/<workspace>/agents/<agent>, so the
+    // workspace a secret should resolve against is two levels up.
+    const workspace = path.basename(path.resolve(agentDir, "..", ".."));
+    const { data: front, content: body } = matter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
+    const parts = [resolveDocLinks(body.trim(), path.resolve(agentDir, "..", ".."))];
+    // Where the agent is standing. Every path below this line is relative to the
+    // agent's own directory, and a run showed why that has to be said rather
+    // than implied: told to read `../../knowledge/index.md`, the model asked for
+    // `/knowledge/index.md` twice before working it out. Two denials and a turn,
+    // for want of one sentence.
+    parts.push(`# Where you are\n\n` +
+        `Your working directory is \`agents/${path.basename(agentDir)}/\` inside the ` +
+        `\`${workspace}\` workspace. Every path in this prompt is relative to it — ` +
+        `\`outputs/\` is yours, and \`../../\` is the workspace root, so the workspace's ` +
+        `own knowledge is at \`../../knowledge/\`. Absolute paths are outside the ` +
+        `workspace and will be refused.\n\n` +
+        // A flow's whole point is that a later step works on what an earlier one
+        // produced, and each agent writes to its own outputs/. A run showed what
+        // omitting this costs: the checker looked in its own empty outputs/ and
+        // reported the draft missing — reviewing nothing, and saying so
+        // confidently — while the publisher only found it by guessing at a glob.
+        `Each agent writes to its own \`outputs/\`, so a file an earlier step produced is ` +
+        `at \`../<that-agent>/outputs/\`, not in yours. If a previous step says it wrote ` +
+        `something, look there before concluding it does not exist.\n\n` +
+        // The distinction agents kept getting wrong, said where they can read
+        // it: outputs/ is working text between steps and never leaves the
+        // source tree; storage/ is the store the dashboard's Storage page lists.
+        // A 100-row CSV written to outputs/ is delivered nowhere — a person
+        // looking for it on the Storage page finds it empty and concludes the run
+        // produced nothing.
+        // The path here MUST be the one harvestFiles reads. It said
+        // `../../files/` after the rename, and nothing recovered from that:
+        // materializeFiles always creates `storage/` before the step, so
+        // adoptLegacyFilesDir's "move files/ to storage/" is a no-op by the time
+        // the run ends — a deliverable written where this text pointed was
+        // harvested from nowhere and silently never appeared.
+        `\`../../storage/\` is the workspace file store: anything you leave there is kept ` +
+        `after the run and shown on the Storage page for people to download. Write ` +
+        `deliverables people asked for — CSVs, reports, PDFs, images — to \`../../storage/\`; ` +
+        `use \`outputs/\` for working text the next step reads.`);
+    // Shared context before anything derived — an account or workspace rule is
+    // background the rest of the prompt is read against, not an afterthought.
+    const sharedContext = sharedInstructions(agentDir, tenant);
+    if (sharedContext)
+        parts.push(sharedContext);
+    // Skills follow the open Agent Skills format (agentskills.io): a folder
+    // with SKILL.md, optionally bundling its own scripts/ and references/. The
+    // flat `skills/<name>.md` form is also accepted for small skills.
+    //
+    // Progressive disclosure, as the standard prescribes: only each skill's
+    // name and description go into context up front. The agent reads the full
+    // SKILL.md when a task actually calls for it — so an agent can carry many
+    // skills for a few tokens each.
+    // Own skills, then the workspace's, then the workspace library — nearest
+    // definition of a name wins, so a team default can be overridden locally.
+    const skills = [];
+    const seenSkills = new Set();
+    const addSkills = (dir, prefix, subdir = "skills") => {
+        for (const skill of discoverSkills(dir, subdir)) {
+            if (seenSkills.has(skill.name))
+                continue;
+            seenSkills.add(skill.name);
+            skills.push({ ...skill, path: `${prefix}${skill.path}`, dir: skill.dir ? `${prefix}${skill.dir}` : null });
+        }
+    };
+    const workspaceRoot = path.join(agentDir, "..", "..");
+    addSkills(agentDir, "");
+    addSkills(workspaceRoot, "../../"); // the workspace's skills/
+    // The cross-client convention: skills any skills-compatible tool installs
+    // under .agents/skills/ are visible here too, and vice versa. Scanned after
+    // the native location so a foldrun-native skill wins a name clash, but both
+    // are discovered. project scope only — foldrun workspaces are self-contained.
+    addSkills(workspaceRoot, "../../", ".agents/skills");
+    addSkills(path.join(libraryDir(tenant)), "../../../../library/"); // the account library
+    // A skill with `when:` only loads when the run carries a matching tag —
+    // so an agent with 119 skills costs 119 lines of context only when every
+    // one is genuinely relevant.
+    // `skills:` is Claude Code's field for naming which skills an agent gets.
+    // Absent, an agent inherits every skill in scope — knowledge cascades. Named,
+    // it's an allowlist, which is how you keep a focused agent focused.
+    const only = refNames(front.skills);
+    const applicable = applicableSkills(skills, only, tags);
+    const withheld = skills.length - applicable.length;
+    if (applicable.length) {
+        const lines = applicable.map((s) => {
+            // The rest of the Agent Skills layout, named so the agent knows to look
+            // rather than guessing that a skill folder holds only SKILL.md.
+            const bundles = [
+                s.hasScripts && `scripts in \`${s.dir}/scripts/\``,
+                s.hasReferences && `reference docs in \`${s.dir}/references/\``,
+                s.hasAssets && `assets in \`${s.dir}/assets/\``,
+            ].filter(Boolean);
+            return (`- **${s.name}** — ${s.description || "(no description)"} ` +
+                `Full instructions: \`${s.path}\`` +
+                (bundles.length ? ` (also bundles ${bundles.join(", ")})` : ""));
+        });
+        parts.push(`# Skills\n\nCapabilities available to you. Each line is a summary — when a task matches one, ` +
+            `read its file for the full instructions before proceeding:\n\n${lines.join("\n")}` +
+            (withheld ? `\n\n(${withheld} further skills exist but do not apply to this run.)` : ""));
+    }
+    // Memory: the index is loaded every run, and the agent is told how to add
+    // to it. Writing is only possible if it has the `files` tool.
+    const canWrite = refNames(front.tools).includes("files");
+    const memoryDir = path.join(agentDir, "memory");
+    const memoryIndex = buildMemoryIndex(memoryDir);
+    if (memoryIndex || canWrite) {
+        const howTo = canWrite
+            ? `\n\nTo remember something durable, write one fact per file to memory/<slug>.md with ` +
+                `frontmatter: type (e.g. Fact, Decision, Preference), name and description — these ` +
+                `bundles follow the Open Knowledge Format. The index above maintains itself — you do not ` +
+                `need to edit it. Read a memory file before relying on it, update an existing file ` +
+                `rather than duplicating it, and don't record what this workspace's files already say.`
+            : "";
+        const projectMem = workspaceMemoryIndex(tenant, workspace);
+        const shared = libraryMemoryIndex(tenant);
+        parts.push(`# Memory — what you have learned\n\n${memoryIndex ? `Your own (files under memory/):\n\n${memoryIndex}` : "You have no memories of your own yet."}` +
+            (projectMem ? `\n\nShared across this workspace:\n\n${projectMem}` : "") +
+            (shared ? `\n\nShared across every workspace:\n\n${shared}` : "") +
+            howTo);
+    }
+    // Knowledge — reference material the agent was given. Same three scopes and
+    // the same nearest-wins reading order as memory, but never written back:
+    // an agent that edits the price list it was handed has corrupted its own
+    // source of truth.
+    const ownKnowledge = knowledgeIndex(path.join(agentDir, "knowledge"), "knowledge/");
+    const projectKnowledge = workspaceKnowledgeIndex(tenant, workspace);
+    const sharedKnowledge = knowledgeIndex(libraryDir(tenant, "knowledge"), "../../../../library/knowledge/");
+    if (ownKnowledge || projectKnowledge || sharedKnowledge) {
+        const sections = [
+            ownKnowledge && `Your own (files under knowledge/):\n\n${ownKnowledge}`,
+            projectKnowledge && `Shared across this workspace:\n\n${projectKnowledge}`,
+            sharedKnowledge && `Shared across every workspace:\n\n${sharedKnowledge}`,
+        ].filter(Boolean);
+        parts.push(`# Knowledge — what you were given\n\nReference material. Open a file when a task depends ` +
+            `on it rather than guessing at its contents. This is read-only: it is maintained by ` +
+            `people, not by you — if you learn something new, write it to memory/ instead.\n\n` +
+            sections.join("\n\n"));
+    }
+    // Scripts an agent can run with bash: its own scripts/, plus the
+    // workspace-level shared scripts/ exposed at shared/ in its working dir.
+    const listDir = (dir, prefix) => {
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+            const rel = String(entry);
+            if (fs.statSync(path.join(dir, rel)).isFile())
+                out.push(`- ${prefix}${rel}`);
+        }
+        return out.sort();
+    };
+    const own = listDir(path.join(agentDir, "scripts"), "scripts/");
+    const shared = listDir(path.join(agentDir, "..", "..", "scripts"), "../../scripts/");
+    // The library's path depends on where this run executes: isolated runs see
+    // it at /library, host runs at its real location. Printing the host path
+    // into a container's prompt handed the model files it could never open.
+    const libraryScriptsRoot = isolatedRun() ? "/library/scripts" : libraryDir(tenant, "scripts");
+    const global = listDir(libraryDir(tenant, "scripts"), `${libraryScriptsRoot}/`);
+    if (own.length || shared.length || global.length) {
+        const sections = [
+            own.length ? `Your own scripts:\n${own.join("\n")}` : null,
+            shared.length ? `Shared across this workspace:\n${shared.join("\n")}` : null,
+            global.length ? `From the account library (read-only):\n${global.join("\n")}` : null,
+        ].filter(Boolean);
+        parts.push(`# Scripts\n\nTooling you can run with bash from your working directory:\n\n${sections.join("\n\n")}\n\n` +
+            `Read a script before running it if you are unsure what it does. Credentials your ` +
+            `scripts need are already in the environment as the secrets listed below.`);
+    }
+    // State — data a run carries to the next one. It was a directory in the
+    // workspace list, preserved across deploys, and nothing else: never named to
+    // an agent, never loaded, never written. A promise with no implementation.
+    //
+    // Listed rather than inlined, for the same reason knowledge and memory are:
+    // an agent that needs a cursor opens it, and one that doesn't shouldn't pay
+    // for it. The difference is that state is small enough that inlining would
+    // usually be free — that is a threshold worth adding once there is a real
+    // file to size it against, not before.
+    const state = listDir(path.join(agentDir, "..", "..", "state"), "../../state/");
+    if (state.length) {
+        parts.push(`# State — what you carry between runs\n\n` +
+            `What this workspace keeps across runs: a count, a cursor, where you got to. ` +
+            `Read and write these directly, and update them before you finish so the next ` +
+            `run starts where you left off.\n\n${state.join("\n")}\n\n` +
+            `Keep a file in the format it is already in, and write markdown for anything new. ` +
+            `A count reads as well in a sentence as in JSON, and a person edits these in the ` +
+            `same editor as everything else — data formats are allowed here, not preferred.\n\n` +
+            `This is not memory. A fact you learned goes in memory/, where it is indexed and ` +
+            `its provenance recorded — state is the bookmark, not the lesson.`);
+    }
+    // APIs — the agent's own definitions, plus workspace tools it granted by
+    // name. Library tools are defined once and reused.
+    const apis = parseApis(front.apis);
+    // Scripts declared inline on the agent, plus any script-type tool it
+    // granted — one list grants both kinds.
+    const scriptSpecs = parseScripts(front.scripts);
+    // Workspace tools shadow account tools of the same name (nearest wins).
+    const available = { ...libraryTools(tenant), ...workspaceTools(tenant, workspace) };
+    // Resolved in one place (tool-names.ts) so nothing downstream can disagree
+    // about which names are the author's.
+    const requested = ownToolNames(front);
+    const legacyUse = legacyUseNames(front);
+    const missingTools = [];
+    // MCP servers an agent connects to. `mcpServers:` is Claude Code's spelling
+    // for the inline form; a `type: mcp` tool file is the shared form. Both end
+    // up here, and both reach the model as ordinary MCP tools.
+    const mcpServers = {};
+    const mcpNames = [];
+    // What the granted tools' programs need — merged into this step's runtime
+    // below. The tool is the unit of code, so its dependencies live in tool.md
+    // and travel with it; the agent should not have to repeat them.
+    const toolRuntimes = [];
+    const grantOwnTool = (name) => {
+        const def = available[name];
+        if (!def) {
+            missingTools.push(name);
+            return;
+        }
+        if (def.kind === "http")
+            apis.push(def.spec);
+        else if (def.kind === "script") {
+            scriptSpecs.push(...parseScripts([def.spec]));
+            const rt = parseRuntime(def.spec.runtime);
+            if (rt)
+                toolRuntimes.push(rt);
+        }
+        else {
+            mcpServers[def.name] = mcpConfig(def.spec, tenant, workspace);
+            mcpNames.push(def.name);
+        }
+    };
+    for (const name of requested)
+        grantOwnTool(name);
+    // Inline servers, Claude Code's field name and shape.
+    if (front.mcpServers && typeof front.mcpServers === "object") {
+        for (const [name, raw] of Object.entries(front.mcpServers)) {
+            const def = parseToolDef({ ...raw, type: "mcp" }, name);
+            if (def?.kind === "mcp") {
+                mcpServers[name] = mcpConfig(def.spec, tenant, workspace);
+                mcpNames.push(name);
+            }
+        }
+    }
+    // An `openapi:` document turns one generic HTTP tool into typed ones, one
+    // per operation. Resolved here, host-side, so the operations cross into a
+    // container as values like the rest of the spec.
+    const attached = attachOperations(apis, tenant, path.resolve(agentDir, "..", ".."));
+    const apiWarnings = attached.warnings;
+    apis.splice(0, apis.length, ...attached.specs);
+    const apiTools = buildApiTools(tenant, apis, workspace);
+    if (apiTools.promptLines.length) {
+        parts.push(`# APIs you can call\n\n${apiTools.promptLines.join("\n")}`);
+    }
+    // Secrets an agent declared become env vars for its scripts and bash.
+    //
+    // Plus the credentials its API tools reference. An agent that opted into
+    // `tools: [email]` has said nothing about RESEND_API_KEY and should not have
+    // to: the whole point of a tool definition is that the capability travels
+    // with its credential and the agent never learns the name. The in-process
+    // path always worked this way — buildApiTools resolves what the specs
+    // reference — so without this the isolated path substituted nothing and
+    // sent `Bearer ${RESEND_API_KEY}` literally, which the provider answers
+    // with a 4xx the agent then reports as "the credential is missing".
+    //
+    // Declared-and-absent is still an error; referenced-and-absent is the API
+    // tool's own missingSecrets, reported where the tool is described.
+    const declared = Array.isArray(front.secrets) ? front.secrets.map(String) : [];
+    const referenced = [...new Set(apis.flatMap(secretsUsedByApi))];
+    const { env: secretEnv, from: secretScopes, } = resolveSecrets(tenant, [...new Set([...declared, ...referenced])], workspace);
+    const { missing: missingDeclared } = resolveSecrets(tenant, declared, workspace);
+    // The step's pod size. Three classes, not a dial: a size is a price and a
+    // promise, and three of each is a menu while ten is a support queue. Default
+    // is large — the install's configured limits — so existing agents change
+    // nothing. `size: small` is the opt-in for agents that wait on APIs more
+    // than they work; `size: heavy` for a rendered browser or real data in
+    // memory. Memory is a hard ceiling per class; CPU bursts uncapped and bills
+    // at the class rate, so heavy both may use more and costs more. The actuals
+    // line in any trace is the evidence for right-sizing.
+    const size = front.size === "small" ? "small" : front.size === "heavy" ? "heavy" : "large";
+    // Provider: which endpoint the model calls run against. Anthropic by
+    // default; an Anthropic-compatible gateway (z.ai, LiteLLM, OpenRouter) by
+    // declaring one. The format is portable — this is where the runtime stops
+    // being tied to one vendor's endpoint.
+    //
+    //   provider:
+    //     base_url: https://api.z.ai/api/anthropic
+    //     token: ${ZAI_TOKEN}
+    //
+    // The URL sits in git; the token is a ${SECRET} resolved server-side. An
+    // agent's own block wins over the workspace's, like everything else here.
+    const providerBlock = front.provider ?? workspaceFrontmatter(agentDir, tenant).provider;
+    let providerEnv = {};
+    let providerLabel = null;
+    // Secret values pulled into the provider block, name → value. Kept apart
+    // from providerEnv because a header blob is a poor redaction key: what
+    // must never reach the journal is the credential inside it, not the blob.
+    const providerSecrets = {};
+    const providerWarnings = [];
+    // The declared second supply, resolved the same way. Null when the block
+    // names none; the platform's own fallback still applies to a step that
+    // rides the platform credential.
+    let fallbackEnv = null;
+    // A Chat-Completions endpoint is reached through the runtime's own
+    // translator; these are its instructions, as values, or null when the
+    // block speaks Anthropic. One for the primary, one for the fallback.
+    let translator = null;
+    let fallbackTranslator = null;
+    const spec = parseProvider(providerBlock);
+    if (spec) {
+        providerWarnings.push(...spec.warnings);
+        const substitute = (text) => text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, secretName) => {
+            const hit = getSecret(tenant, secretName, workspace);
+            if (!hit)
+                return whole;
+            providerSecrets[secretName] = hit.value;
+            return hit.value;
+        });
+        const resolved = substitute(spec.token);
+        if (spec.baseUrl) {
+            const headers = Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, substitute(v)]));
+            providerEnv = providerEnvFor({
+                baseUrl: spec.baseUrl,
+                token: resolved,
+                auth: spec.auth,
+                models: spec.models,
+                headers,
+            });
+            const preset = providerPreset(spec.name);
+            translator = translatorSpecFor({
+                format: spec.format,
+                baseUrl: spec.baseUrl,
+                token: resolved,
+                headers,
+                params: spec.params,
+                name: spec.name,
+                maxTokensParam: preset?.maxTokensParam,
+                reasoningEffort: preset?.reasoningEffort,
+            });
+            // What the run is actually pointed at, in one line: the endpoint, the
+            // tiers this gateway renames, and whether the credential landed.
+            const remapped = Object.entries(spec.models).map(([tier, id]) => `${tier}→${id}`);
+            providerLabel = (spec.name ? `${spec.name} ` : "") + spec.baseUrl + (translator ? " via translator" : "");
+            if (remapped.length)
+                providerLabel += ` (${remapped.join(", ")})`;
+            // An unresolved ${SECRET} would silently fall back to Anthropic's
+            // endpoint with the host's key — say so instead.
+            if (spec.token && resolved === spec.token && spec.token.includes("${")) {
+                providerLabel += " — token secret not set";
+            }
+        }
+        if (spec.fallback?.baseUrl) {
+            const fb = spec.fallback;
+            const headers = Object.fromEntries(Object.entries(fb.headers).map(([k, v]) => [k, substitute(v)]));
+            const fbToken = substitute(fb.token);
+            fallbackEnv = providerEnvFor({ baseUrl: fb.baseUrl, token: fbToken, auth: fb.auth, models: fb.models, headers });
+            const fbPreset = providerPreset(fb.name);
+            fallbackTranslator = translatorSpecFor({
+                format: fb.format,
+                baseUrl: fb.baseUrl,
+                token: fbToken,
+                headers,
+                params: fb.params,
+                name: fb.name,
+                maxTokensParam: fbPreset?.maxTokensParam,
+                reasoningEffort: fbPreset?.reasoningEffort,
+            });
+            providerLabel = `${providerLabel ?? "platform"} (fallback: ${fb.name ?? fb.baseUrl})`;
+        }
+    }
+    // Runtime: an agent's own `runtime:` block, else its workspace's. Built once
+    // per declaration and cached, so scripts get their dependencies without
+    // polluting the host.
+    let runtimeSpec = parseRuntime(front.runtime);
+    if (!runtimeSpec) {
+        // AGENTS.md is the Linux Foundation standard name (60k+ repos, same
+        // nearest-wins cascade we already use); project.md stays accepted so
+        // nothing that already exists breaks.
+        runtimeSpec = parseRuntime(workspaceFrontmatter(agentDir, tenant).runtime);
+    }
+    // Plus whatever the tools this agent granted declared for themselves.
+    runtimeSpec = mergeRuntimes(runtimeSpec, ...toolRuntimes);
+    // Execution: a container per run when Docker is available (real isolation),
+    // otherwise the host venv path so local development still works.
+    const executor = chooseExecutor();
+    const runtimeLog = [];
+    let runtimeError = null;
+    let exec = null;
+    let runtime = { interpreters: {}, env: {}, log: [], error: null };
+    if (executor === "docker") {
+        const image = ensureImage(runtimeSpec);
+        runtimeLog.push(...image.log);
+        runtimeError = image.error;
+        if (!image.error) {
+            exec = {
+                executor: "docker",
+                image: image.tag,
+                mounts: {
+                    [path.resolve(agentDir, "..", "..", "scripts")]: "/workspace-scripts",
+                    [libraryDir(tenant, "scripts")]: "/library-scripts",
+                },
+                // Only agents that granted something reaching out — an `apis:` entry
+                // or one of their own tools — get egress.
+                network: parseApis(front.apis).length > 0 || ownToolNames(front).length > 0,
+            };
+        }
+    }
+    else {
+        runtime = prepareRuntime(tenant, runtimeSpec);
+        runtimeLog.push(...runtime.log);
+        runtimeError = runtime.error;
+    }
+    // What day it is, in the workspace's own timezone. Not a secret, so it
+    // travels beside secretEnv rather than inside it — a value in there is
+    // redacted from every log line that quotes it.
+    const timezone = resolveTimezone(workspaceFrontmatter(agentDir, tenant));
+    const clockEnv = {
+        TZ: timezone,
+        FOLDRUN_DATE: localDate(timezone),
+        // Where the account's own search engine answers, when the install runs
+        // one — the `websearch` library tool reads it. Not a secret; rides with
+        // the clock so it reaches scripts, the sandbox and verify alike.
+        ...(process.env.FOLDRUN_SEARCH_URL ? { FOLDRUN_SEARCH_URL: process.env.FOLDRUN_SEARCH_URL } : {}),
+    };
+    // Scripts declared as tools — callable by name, no bash required.
+    const scriptTools = buildScriptTools(agentDir, scriptSpecs, 
+    // A script can say where its work came from. Without this, anything a
+    // tool writes into another system lands anonymous: you can see 100 new
+    // contacts and have no way back to the run that made them. The run id,
+    // the agent, and the date the platform believes it is.
+    {
+        ...runtime.env,
+        ...secretEnv,
+        ...(identity.runId ? { FOLDRUN_RUN_ID: identity.runId } : {}),
+        ...(identity.agent ? { FOLDRUN_AGENT: identity.agent } : {}),
+        // And the workspace: a commit or a record made by a shared library
+        // tool should say which desk made it, and the pod's own paths
+        // (/workspace/agents/<agent>) do not carry the name.
+        FOLDRUN_WORKSPACE: workspace,
+        ...clockEnv,
+    }, libraryDir(tenant, "scripts"), runtime.interpreters, exec);
+    parts.push(`# Clock\n\nToday is ${clockEnv.FOLDRUN_DATE} (${timezone}). Use this date for anything you ` +
+        `write or check — it is the workspace's calendar, not the container's clock.`);
+    if (scriptTools.promptLines.length) {
+        parts.push(`# Tools from scripts\n\nCall these directly — they run workspace scripts for you:\n\n${scriptTools.promptLines.join("\n")}`);
+    }
+    if (declared.length) {
+        parts.push(`# Secrets\n\nAvailable to your scripts as environment variables: ${declared.join(", ")}. ` +
+            `Never print, echo, or write them to a file.`);
+    }
+    parts.push("Write deliverables for people to workspace/storage/ (kept and downloadable); write working text for later steps to outputs/; " +
+        "what the next run needs goes to workspace/state/. Paths are relative to your agent directory, or start with workspace/ " +
+        "for the workspace root (../../storage/ and workspace/storage/ are the same place). There is no /tmp for you: a " +
+        "directory a tool made outside the workspace, such as a checkout, is reached only through that tool.");
+    // The run's one-line summary is the first meaningful line of the last step
+    // that produced a result — read, never declared (runSummary in store.ts).
+    // That convention was load-bearing and unstated: it decides the runs-list
+    // row, the notification subject, and what `recall_runs()` shows a later
+    // run, and an agent that opened with "I'll start by cloning the repo" made
+    // all three useless. Asking here rather than in each agent.md means every
+    // agent obeys it, including the ones written before the summary existed.
+    parts.push("Open your reply with one sentence saying what you concluded or produced — the outcome, " +
+        "not your plan. Everything else follows it. That sentence is what a person sees in the " +
+        "run list and in the notification, without opening the run.");
+    // One list. `tools:` grants anything: a built-in group, an exact SDK tool
+    // name, or a tool defined in this workspace or account.
+    //
+    // The split used to be ours, not the author's: they don't care whether a
+    // capability comes from the SDK or a file, only what the agent may do. Two
+    // lists meant two places to look for the blast radius.
+    const allowed = [];
+    const disabled = [];
+    const unknownTools = [];
+    const shadowed = [];
+    let wantSearch = false;
+    let wantHistory = false;
+    let wantDesks = false;
+    for (const ref of toolRefs(front)) {
+        const toolName = ref.name;
+        if (ref.mode === "ask") {
+            disabled.push(toolName);
+            continue;
+        }
+        // Resolution order: built-in group, exact SDK name, then your own tools.
+        // Built-ins win a bare name, because their names are a small fixed set —
+        // but a tool hidden by one is worth saying out loud rather than silently
+        // ignoring. A `[[link]]` skips the built-ins entirely: the brackets mean
+        // "my file", which is how a tool named `search` is granted at all.
+        if (ref.linked) {
+            // Granted above through ownToolNames, or reported missing there.
+        }
+        else if (TOOL_MAP[toolName]) {
+            allowed.push(...TOOL_MAP[toolName]);
+            if (available[toolName])
+                shadowed.push(toolName);
+        }
+        else if (toolName === "search" || toolName === "history" || toolName === "desks") {
+            // The platform's own groups, served in-process — built below, once
+            // the roots and the records are known.
+            if (toolName === "search")
+                wantSearch = true;
+            else if (toolName === "history")
+                wantHistory = true;
+            else
+                wantDesks = true;
+            if (available[toolName])
+                shadowed.push(toolName);
+        }
+        else if (BUILTIN_TOOLS.has(toolName)) {
+            allowed.push(toolName);
+            if (available[toolName])
+                shadowed.push(toolName);
+        }
+        else if (available[toolName]) {
+            // Already granted above — nothing to do here.
+        }
+        else if (!missingTools.includes(toolName)) {
+            unknownTools.push(toolName);
+        }
+    }
+    allowed.push(...apiTools.toolNames, ...scriptTools.toolNames);
+    // tools: [search] — every place a fact of this agent's could be, in the
+    // same nearest-wins order the prompt lists them. tools: [history] — the
+    // workspace's finished runs, minus the one being driven. Both are values
+    // by the time they leave here, so the container can rebuild the servers.
+    const wsRoot = path.resolve(agentDir, "..", "..");
+    const searchRoots = wantSearch
+        ? [
+            { label: "knowledge/", dir: path.join(agentDir, "knowledge") },
+            { label: "memory/", dir: path.join(agentDir, "memory") },
+            { label: "../../knowledge/", dir: path.join(wsRoot, "knowledge") },
+            { label: "../../memory/", dir: path.join(wsRoot, "memory") },
+            { label: "../../state/", dir: path.join(wsRoot, "state") },
+            { label: `../../${STORAGE_DIR}/`, dir: path.join(wsRoot, STORAGE_DIR) },
+            { label: "outputs/", dir: path.join(agentDir, "outputs") },
+            { label: "[library] knowledge/", dir: libraryDir(tenant, "knowledge") },
+            { label: "[library] memory/", dir: libraryDir(tenant, "memory") },
+        ]
+        : [];
+    const historyDigest = wantHistory ? digestRuns(listRuns(tenant, workspace), 30, identity.runId) : [];
+    // tools: [desks] — the account's OTHER workspaces, ten runs each. A run
+    // pod cannot reach the platform's API and the library is read-only, so
+    // this is the only way one desk sees what another concluded — and it
+    // stays a value the host chose to send, not a door the sandbox opened.
+    const deskDigest = wantDesks
+        ? listWorkspaces(tenant)
+            .filter((w) => w.name !== workspace)
+            .flatMap((w) => digestRuns(listRuns(tenant, w.name), 10).map((d) => ({ ...d, workspace: w.name })))
+            .sort((a, b) => (b.startedAt > a.startedAt ? 1 : -1))
+            .slice(0, DESK_RUNS_CAP)
+        : [];
+    const searchTools = buildSearchTools(searchRoots);
+    const historyTools = wantHistory ? buildHistoryTools(historyDigest) : { server: null, toolNames: [], promptLines: [] };
+    const deskTools = wantDesks ? buildDeskTools(deskDigest) : { server: null, toolNames: [], promptLines: [] };
+    allowed.push(...searchTools.toolNames, ...historyTools.toolNames, ...deskTools.toolNames);
+    if (searchTools.promptLines.length || historyTools.promptLines.length || deskTools.promptLines.length) {
+        parts.push(`# Finding things\n\n${[...searchTools.promptLines, ...historyTools.promptLines, ...deskTools.promptLines].join("\n")}`);
+    }
+    // An MCP server declares its tools when it connects, so they can't be listed
+    // ahead of time. Server-level specs cover them: granting the server grants
+    // what it exposes, which is the unit a person actually reasons about anyway.
+    for (const name of mcpNames)
+        allowed.push(`mcp__${name}`, `mcp__${name}__*`);
+    // Claude Code's spellings, so an agent written for it mostly runs here.
+    // `permissionMode: plan` is its read-only mode; ours is the `read` group.
+    if (front.permissionMode === "plan") {
+        allowed.length = 0;
+        allowed.push(...TOOL_MAP.read, ...apiTools.toolNames, ...scriptTools.toolNames);
+    }
+    const denied = refNames(front.disallowedTools);
+    const finalAllowed = allowed.filter((t) => !denied.includes(t));
+    return {
+        front,
+        clockEnv,
+        systemPrompt: parts.join("\n\n"),
+        allowed: finalAllowed,
+        disabled,
+        unknownTools,
+        shadowed,
+        legacyUse,
+        mcpServers,
+        mcpNames,
+        apiTools,
+        scriptTools,
+        // The merged spec lists — inline plus tools:-granted — for the isolated
+        // path, which serialises specs across the container boundary rather
+        // than using the servers built here.
+        apiSpecs: apis,
+        scriptSpecs,
+        searchRoots,
+        historyDigest,
+        deskDigest,
+        searchTools,
+        historyTools,
+        deskTools,
+        // `spec` is the MERGED declaration — the agent's own block or its
+        // workspace's, plus every granted tool's. The isolated path builds its
+        // runtime from this; passing the agent's frontmatter alone silently drops
+        // what the tools declared, and a tool whose program needs a package it
+        // asked for by name fails inside the container with "cannot find" while
+        // the host path, which uses this same merged spec, works fine.
+        runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec },
+        secretEnv: { ...runtime.env, ...secretEnv },
+        formatWarning: checkFormatVersion(workspaceFrontmatter(agentDir, tenant).foldrun_version).warning,
+        providerEnv,
+        providerLabel,
+        providerSecrets,
+        providerWarnings,
+        fallbackEnv,
+        translator,
+        fallbackTranslator,
+        apiWarnings,
+        secretScopes,
+        missingTools,
+        size,
+        // Definitions that exist but could not be read. Carried alongside the
+        // missing ones so the step can tell "you never made this" apart from
+        // "it's right there with a typo in it".
+        brokenTools: brokenToolReport(tenant, workspace),
+        missingSecrets: [...new Set([...missingDeclared, ...apiTools.missingSecrets])],
+    };
+}
+/**
+ * The SDK prices a step off Anthropic's table; through a gateway to a
+ * routed model that number is fiction. When the catalogue can price the
+ * tokens itself, its number replaces the SDK's, and the trace says so —
+ * a silently different bill is the one kind nobody forgives.
+ */
+/**
+ * Publish whatever this step left in `storage/public/` and record the URLs.
+ *
+ * Runs after every step, on both execution paths, because the file has to be
+ * on the host (copy-back has happened) and the manifest has to be in place
+ * before the next step's sandbox is filled from that same workspace. A step
+ * generates an image; the step after it reads the URL from a plain file.
+ *
+ * Never fails a step: a link is bookkeeping, and a run that did its work must
+ * not be marked failed because a URL could not be minted.
+ */
+function publishPublicDir(tenant, workspace, push) {
+    try {
+        const { added } = platform.syncPublicShares(tenant, workspace);
+        if (added.length)
+            push("info", `shared: ${added.join(", ")}`);
+    }
+    catch (err) {
+        push("error", `shares: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function repriced(catalog, model, usage, sdkCost, push) {
+    const known = usage ? catalogCost(catalog, model, usage) : null;
+    if (known === null)
+        return sdkCost;
+    if (sdkCost !== null && Math.abs(known - sdkCost) > 0.000001) {
+        push("info", `cost repriced from the gateway's catalogue: $${known.toFixed(6)} (sdk said $${sdkCost.toFixed(6)})`);
+    }
+    return known;
+}
+async function runStep(agentDir, tenant, step, context, save, modelOverride, tags = [], effortOverride, runId, 
+/** What the previous group returned as DATA (an `output: json` step's
+ *  value), beside the prose in `context`. Undefined when nothing did. */
+priorData, 
+/** The most this step may spend before it is stopped mid-turn: the run's
+ *  remaining `budget:`, shared across the steps launched with it. Null
+ *  means the flow set no budget. */
+stepBudgetUsd = null) {
+    // 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` —
+    // can put a live credential into its reply. Everything a step says is
+    // written to runs/<id>.json and rendered in the dashboard, which would make
+    // that credential permanent and visible to anyone who can read a run.
+    //
+    // So values are scrubbed on the way into the journal, at the one place every
+    // event passes through. The name survives, because "the token was here" is
+    // the part worth keeping.
+    //
+    // This is the last line of defence, not the only one: the model is never
+    // given the values in the first place, and checkBash already refuses the
+    // obvious `echo $SOMETHING_TOKEN`. It exists because neither of those can
+    // cover a script's own stdout.
+    let redactions = [];
+    let fileDir = null;
+    const redact = (text) => {
+        let out = text;
+        for (const [value, name] of redactions)
+            out = out.split(value).join(`[redacted:${name}]`);
+        return out;
+    };
+    const push = (type, text, extra) => {
+        step.events.push({ t: new Date().toISOString(), type, text: redact(text), ...extra });
+        save();
+    };
+    // The clock on the step itself. `??=` so a retry extends the first
+    // attempt's span rather than starting a new one; finishedAt is stamped on
+    // every exit below and the last attempt's stands.
+    step.startedAt ??= new Date().toISOString();
+    // The test seam: FOLDRUN_STUB_STEP=1 completes the step from a canned
+    // script instead of a model, so the orchestration around steps — loops,
+    // fan-out, gates — is testable at zero cost. An agent's `stub.md` holds
+    // the answers, `\n---\n`-separated, consumed one per call; the last one
+    // repeats. Never set outside a test.
+    if (process.env.FOLDRUN_STUB_STEP === "1") {
+        const stubFile = path.join(agentDir, "stub.md");
+        const answers = fs.existsSync(stubFile)
+            ? fs.readFileSync(stubFile, "utf8").split(/\n---\n/)
+            : [`stub result from ${step.agent}`];
+        const call = step.events.filter((e) => e.text.startsWith("stub call")).length;
+        push("info", `stub call ${call + 1}`);
+        step.status = "completed";
+        // A stub answer may open with `cost: 0.25` — a pretend price, so the
+        // parts of orchestration that watch money (budget:) are testable too.
+        const answer = (answers[Math.min(call, answers.length - 1)] ?? "").trim();
+        const priced = answer.match(/^cost:\s*([\d.]+)\n?/);
+        const body = (priced ? answer.slice(priced[0].length) : answer).trim();
+        // A `===` line inside an answer separates earlier turns from the final
+        // one, so the handoffs that read a conclusion rather than a transcript
+        // are testable: result is everything joined, conclusion the last part.
+        const turns = body.split(/\n===\n/);
+        step.result = turns.join("\n").trim() + (step.item ? ` [item: ${step.item}]` : "");
+        step.conclusion = turns.length > 1 ? turns.at(-1).trim() : null;
+        step.costUsd = priced ? Number(priced[1]) : 0;
+        // The stub honours the output contract too, so fan-out over data and
+        // the failure of a step that returned no JSON are testable at no cost.
+        if (step.output === "json") {
+            const extracted = extractJson(step.result);
+            if (extracted.ok)
+                step.data = extracted.value;
+            else {
+                push("error", `output: json — ${extracted.reason}`);
+                step.status = "failed";
+            }
+        }
+        step.finishedAt = new Date().toISOString();
+        save();
+        return;
+    }
+    try {
+        // An `openapi:` URL is fetched (and cached a day) before the context is
+        // assembled, because assembling it is synchronous and the document has
+        // to be on disk by then. Failures are lines in the trace, not a failed
+        // step: the generic HTTP tool still works without the typed ones.
+        for (const w of await prefetchOpenApi(tenant, openApiSources(agentDir, tenant)))
+            push("error", `openapi: ${w}`);
+        const { front, clockEnv, systemPrompt, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, translator, fallbackTranslator, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent });
+        // 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:
+        // what crosses into containers, headers and env files is the token. A
+        // failed refresh fails the step naming the secret and the provider's
+        // reason, which beats a 401 three layers later.
+        const liveSecrets = await materializeSecrets(secretEnv);
+        // @file values (SSH keys, certs) still carry their content at this point.
+        // The in-process branch materialises them to 0600 paths on this host
+        // below; the container branch passes the content across and the driver
+        // materialises inside, because a host path is meaningless in there.
+        // Populate before the first push: everything after this point may quote a
+        // credential. Short values are skipped — a two-character secret would
+        // redact half the English language, and anything that short is not one.
+        redactions = Object.entries({ ...liveSecrets, ...providerSecrets, ...providerEnv })
+            .filter(([, value]) => typeof value === "string" && value.length >= 8)
+            .map(([name, value]) => [value, name])
+            // Longest first, so a value containing another is replaced whole.
+            .sort((a, b) => b[0].length - a[0].length);
+        if (providerLabel)
+            push("info", `provider: ${providerLabel}`);
+        for (const w of providerWarnings)
+            push("error", w);
+        for (const w of apiWarnings)
+            push("error", `openapi: ${w}`);
+        if (formatWarning)
+            push("error", formatWarning);
+        if (legacyUse.length)
+            push("error", legacyUseError(legacyUse));
+        for (const t of unknownTools) {
+            push("error", `tools: "${t}" is not a tool group (web, fetch, read, files, bash, search, history), an SDK tool name, or a tool in this workspace's library — nothing was granted for it`);
+        }
+        for (const name of mcpNames)
+            push("info", `mcp server connected: ${name}`);
+        for (const name of shadowed) {
+            push("error", `tools: "${name}" is a built-in, so your tool of the same name was not granted — write it as [[${name}]] to mean yours`);
+        }
+        for (const t of disabled)
+            push("info", `tool ${t}: ask-mode is disabled for platform runs`);
+        for (const s of missingSecrets) {
+            push("error", `secret ${s} is not set in this workspace — add it in Settings → Secrets`);
+        }
+        // Say which store each secret came from: a workspace quietly falling back
+        // to an account credential is the kind of thing you want to see, not infer.
+        for (const [name, scope] of Object.entries(secretScopes)) {
+            push("info", `secret ${name} ← ${scope} scope`);
+        }
+        for (const t of missingTools) {
+            // "Not found" is the wrong sentence when the file is right there with a
+            // typo in it, and it sends the author to the wrong place. Say which.
+            const broken = brokenTools.filter((b) => b.startsWith(`${t}:`));
+            push("error", broken.length
+                ? `tool "${t}" exists but could not be read — ${broken[0].slice(t.length + 2)}`
+                : `tool "${t}" is not in the workspace library — add it under Library → Tools`);
+        }
+        for (const line of runtime.log)
+            push("info", line);
+        push("info", `script executor: ${runtime.executor}`);
+        if (runtime.error)
+            push("error", `runtime: ${runtime.error}`);
+        // Nearest wins, for both halves of model selection: the step names one,
+        // else the flow does, else the agent's own frontmatter. Which level won
+        // goes in the trace — "why did this run on haiku" should be answerable
+        // from the run, not by opening three files.
+        const modelSource = step.model ? "step" : modelOverride ? "flow" : "agent";
+        const model = resolveModel(step.model ?? modelOverride ?? front.model);
+        const rawEffort = step.effort ?? effortOverride ?? front.effort;
+        const effortSource = step.effort ? "step" : effortOverride ? "flow" : "agent";
+        let effort = resolveEffort(rawEffort);
+        if (isEffortWord(rawEffort)) {
+            push("error", `effort: "${String(rawEffort).trim()}" is not a level — use ${EFFORT_LEVELS.join(", ")}. ` +
+                `Running at the model's default instead.`);
+        }
+        push("info", `step started (agent: ${step.agent}, model: ${model} — ${modelSource}` +
+            `${effort ? `, effort: ${effort} — ${effortSource}` : ""}` +
+            // Say it every time, so a limit is never a surprise and its absence
+            // is a choice on the record, not an accident.
+            `${step.timeout ? `, timeout: ${step.timeout}s` : ", no timeout"})`);
+        // The run-start gate, when a gateway is in play. "Any model they want"
+        // is only an offer if a wrong pick fails here, in one line naming the
+        // fix — not minutes in, as an agent narrating tool calls into prose
+        // because its model cannot make them. The catalogue only ever fails a
+        // step on knowledge; unknown ids, presets and offline all pass through
+        // to the model call, which stays the authority of last resort.
+        let catalog = null;
+        let tokenPrice = null;
+        // The env this run's model calls actually ride: the workspace's own
+        // provider block when one is declared, otherwise the platform's — the
+        // "models included" path, where the host env points every run at the
+        // platform's gateway and users only ever pick a model. The gate, the
+        // effort fit and the repricing follow the credential, not the file:
+        // keying them off the provider block alone left the platform-provided
+        // path — the main one — without any of them.
+        const rideEnv = Object.keys(providerEnv).length > 0 ? providerEnv : process.env;
+        // Through the translator the endpoint is localhost and the model id is
+        // the provider's own, sent as written; there is no catalogue to ask.
+        if (translator)
+            push("info", `translator: ${translator.label} — Anthropic Messages in, Chat Completions out`);
+        // What actually goes on the wire: a tier the gateway remapped is sent
+        // as the gateway's id, and that id — not our tier word — is what the
+        // catalogue can have an opinion about.
+        const wireModel = { haiku: rideEnv.ANTHROPIC_DEFAULT_HAIKU_MODEL,
+            sonnet: rideEnv.ANTHROPIC_DEFAULT_SONNET_MODEL,
+            opus: rideEnv.ANTHROPIC_DEFAULT_OPUS_MODEL }[model] ?? model;
+        if (rideEnv.ANTHROPIC_BASE_URL && !translator) {
+            catalog = await loadCatalog(rideEnv.ANTHROPIC_BASE_URL);
+            const needsTools = allowed.length > 0 || mcpNames.length > 0;
+            const verdict = checkModel(catalog, wireModel, { tools: needsTools });
+            // Also what a token costs here, so a step can count its own spend
+            // turn by turn against its ceiling instead of learning at the end.
+            const priced = findModel(catalog, wireModel);
+            if (priced && priced.promptPrice != null && priced.completionPrice != null) {
+                tokenPrice = { input: priced.promptPrice, output: priced.completionPrice };
+            }
+            if (!verdict.ok) {
+                push("error", verdict.reason);
+                step.status = "failed";
+                save();
+                return;
+            }
+            // Effort, fitted to what this model actually takes: unchanged when the
+            // level is supported, the nearest supported level when it isn't, gone
+            // when the model doesn't reason — each departure said aloud. This is
+            // what makes `effort:` portable rather than Anthropic-only: the word
+            // in the file stays the intent, the wire carries what the model has.
+            const fitted = clampEffort(catalog, wireModel, effort);
+            if (fitted.note)
+                push("info", fitted.note);
+            effort = fitted.effort;
+        }
+        fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
+        fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
+        // Expose the workspace's shared scripts/ as ./shared so every agent reaches
+        // them by the same path, without each one carrying a copy.
+        // No symlinks into the agent directory — they would recurse into the
+        // workspace's own file listing. Shared paths are resolved by the script
+        // tool layer and described to the agent below.
+        // The confinement boundary: agents in a workspace are one team, but the
+        // workspace is where isolation is enforced.
+        const workspaceRoot = path.resolve(agentDir, "..", "..");
+        let prompt = step.instruction
+            ? resolveDocLinks(step.instruction, workspaceRoot)
+            : "Begin your run now, following your instructions.";
+        if (context)
+            prompt += `\n\n<previous_step_results>\n${context.slice(0, CONTEXT_CHARS)}\n</previous_step_results>`;
+        if (priorData !== undefined) {
+            // The value itself, beside the prose that mentioned it. This is the
+            // lossless half of a handoff: a URL step 1 returned reaches step 3 as
+            // the URL, not as whatever a re-reading of step 1's paragraph yields.
+            const json = JSON.stringify(priorData, null, 2);
+            prompt +=
+                `\n\n<previous_step_data>\n${json.length > 60000 ? `${json.slice(0, 60000)}\n…[truncated]` : json}\n</previous_step_data>`;
+        }
+        if (step.output === "json") {
+            // The contract the runner parses back out — stated in the prompt so
+            // the instruction and the parser agree by construction, like delegate:.
+            prompt +=
+                `\n\n<output>\nThis step returns data. End your reply with exactly one JSON value inside a ` +
+                    "```json fenced block — the value the next step will compute on. Prose before it is " +
+                    `welcome (lead with a one-line headline); nothing may follow the block. If the instruction ` +
+                    `names fields, use exactly those names.\n</output>`;
+        }
+        if (step.waitFor === "event" && step.eventPayload !== undefined) {
+            // Not resolved for links, like the previous step's results: it is
+            // whatever the outside world sent, and must not name a file by
+            // happening to contain brackets.
+            prompt += `\n\n<event>\nThis step waited for an external event. What arrived:\n${step.eventPayload}\n</event>`;
+        }
+        if (step.approvalNote) {
+            // The person at the gate said something while letting the run through.
+            // That is the freshest instruction the step has — later than the flow
+            // file, aimed at this exact run. When the gate asked a question
+            // (ask:), the note IS the answer and is framed as one.
+            //
+            // Both halves go through resolveDocLinks for the same reason the
+            // instruction above does: this is authored text on its way to becoming
+            // a prompt, and the rule is that ALL of it expands. A person answering
+            // "which list?" with [[dead-ends]] was sending the model two literal
+            // brackets — the one reference syntax the workspace teaches, and the
+            // one place it silently did nothing.
+            //
+            // What is NOT resolved, deliberately: the previous step's results
+            // above. That is model output, not something a person wrote, and a
+            // model that happens to emit [[brackets]] must not thereby name a file.
+            const ask = step.ask ? resolveDocLinks(step.ask, workspaceRoot) : "";
+            const note = resolveDocLinks(step.approvalNote, workspaceRoot);
+            prompt += step.ask
+                ? `\n\n<operator_answer>\nThis step asked a human: ${ask}\nTheir answer:\n${note}\n</operator_answer>`
+                : `\n\n<operator_guidance>\nThe human who approved this step added:\n${note}\n</operator_guidance>`;
+        }
+        if (step.delegate?.length) {
+            // The chooser's contract. The allowed set comes from the flow file;
+            // the runner parses exactly this shape back out of the result, so the
+            // instruction and the parser agree by construction.
+            prompt +=
+                `\n\n<delegation>\nAfter your analysis, end your reply with one line per agent you are delegating to, ` +
+                    `chosen ONLY from: ${step.delegate.join(", ")}.\nFormat, one per line (at most 5):\n` +
+                    `agent-name: the instruction for that agent\n` +
+                    `Lines naming any other agent are ignored.\n</delegation>`;
+        }
+        if (step.item) {
+            // A fan-out instance: same instruction as its siblings, one item each.
+            prompt += `\n\n<item>\nOf everything above, this instance of the step handles exactly one item — this one:\n${step.item}\n</item>`;
+        }
+        // Colleagues this agent may consult mid-turn — declared, like every
+        // other capability.
+        const { consults, missing: missingConsults } = gatherConsults(workspaceRoot, front.agents);
+        for (const m of missingConsults) {
+            push("error", `agents: "${m}" is not an agent in this workspace — no consult tool granted`);
+        }
+        const consultNames = consults.length ? [...mcpNames, "foldrun_agents"] : mcpNames;
+        // The last provider refusal this step saw, for the fallback decision —
+        // watched on both paths, because a refusal reads the same from a pod
+        // and from this process.
+        let lastRefusal = "";
+        const pushWatching = (type, text, extra) => {
+            if (type === "error" && isProviderRefusal(text))
+                lastRefusal = text;
+            push(type, text, extra);
+        };
+        // The second supply: the block's own fallback when it declared one (a
+        // BYOK step's provider is the customer's arrangement, and so is its
+        // fallback), else the platform's, and only for a step riding the
+        // platform credential.
+        const secondSupply = fallbackEnv ?? (Object.keys(providerEnv).length === 0 ? platformFallbackEnv() : null);
+        const isolation = process.env.FOLDRUN_RUN_ISOLATION;
+        if (isolatedRun()) {
+            // The isolated path: the whole loop — model, built-in tools, scripts —
+            // runs inside a throwaway container (a docker sibling, or a pod), and
+            // only filtered file changes come back. The vault stays out here:
+            // secrets are substituted into API headers before the specs cross,
+            // and reach scripts as env.
+            push("info", `isolation: ${isolation}`);
+            // The *merged* lists — inline declarations plus everything `tools:`
+            // granted — not a re-parse of the frontmatter. Rebuilding from `front`
+            // here silently dropped every tools:-granted http and script tool on
+            // the isolated path (mcp grants survived only because mcpServers is
+            // passed as the merged object): the agent's prompt promised a tool
+            // the function list didn't have, and the step failed as the model
+            // politely reporting the gap.
+            // The egress lease: the sandbox sends through the worker, which holds
+            // the values and fills each ${NAME} for the host that secret was
+            // granted to. Built from what this step declared — every http tool's
+            // secrets for that tool's host, the model key for the provider's —
+            // before anything is copied in. Null where no proxy is configured
+            // (the CLI, a compose install without FOLDRUN_EGRESS_URL), and then
+            // everything below materialises exactly as it always did.
+            const grant = { secrets: {} };
+            for (const api of apiSpecs) {
+                const host = hostOf(api.base);
+                if (!host)
+                    continue;
+                for (const v of [...Object.values(api.headers), ...Object.values(api.query)]) {
+                    for (const name of placeholderNames(v))
+                        if (name in liveSecrets)
+                            addGrant(grant, name, liveSecrets[name], host);
+                }
+            }
+            const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant });
+            // Which secrets must still be real inside the sandbox: a script tool
+            // reads them from its environment, and unless it says `secrets:
+            // proxied` it needs the value, not the name. bash is a script by
+            // another route. The record says which way it went, and why.
+            const materialisers = [
+                ...scriptSpecs.filter((sc) => sc.secrets !== "proxied").map((sc) => sc.name),
+                ...(allowed.includes("Bash") ? ["bash"] : []),
+            ];
+            const materialise = !lease || materialisers.length > 0;
+            const declared = Object.keys(liveSecrets);
+            if (lease) {
+                push("info", declared.length
+                    ? materialise
+                        ? `secrets: ${declared.join(", ")} materialised in the sandbox for ${materialisers.join(", ")}; api tools and the model key go through the egress proxy`
+                        : `secrets: ${declared.join(", ")} proxied — nothing in the sandbox but the names`
+                    : "secrets: none declared; the model key goes through the egress proxy");
+            }
+            // Sandbox env for the declared secrets: the value, or its own name as
+            // a placeholder that the proxy fills on the way out.
+            const sandboxSecrets = materialise
+                ? liveSecrets
+                : Object.fromEntries(declared.map((name) => [name, `\${${name}}`]));
+            const substitutedApis = apiSpecs.map((api) => ({
+                ...api,
+                headers: Object.fromEntries(Object.entries(api.headers).map(([k, v]) => [
+                    k,
+                    v.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => sandboxSecrets[name] ?? whole),
+                ])),
+            }));
+            // The provider's own key and headers, when the step has a lease: the
+            // key becomes ${FOLDRUN_MODEL_KEY}, the base URL goes via the proxy,
+            // and a translator's upstream request does the same. The fallback
+            // supply gets its own placeholder name — two keys, two names.
+            const proxied = (env, name) => lease ? proxyModelEnv(env, lease.url, grant, providerSecrets, name) : env;
+            const proxiedTranslator = (spec, name) => {
+                if (!spec || !lease)
+                    return spec;
+                const host = hostOf(spec.upstreamBase);
+                if (!host)
+                    return spec;
+                addGrant(grant, name, spec.upstreamKey, host);
+                return {
+                    ...spec,
+                    egress: lease.url,
+                    upstreamKey: `\${${name}}`,
+                    headers: Object.fromEntries(Object.entries(spec.headers ?? {}).map(([k, v]) => [k, unsubstitute(v, providerSecrets, host, grant)])),
+                };
+            };
+            const primaryTranslator = proxiedTranslator(translator, MODEL_KEY_NAME);
+            const secondTranslator = proxiedTranslator(fallbackTranslator, `${MODEL_KEY_NAME}_FALLBACK`);
+            const runIsolated = isolation === "container" ? runStepInContainer : platform.isolation[isolation];
+            const isolatedArgs = (modelEnv, keyName = MODEL_KEY_NAME) => ({
+                workspaceRoot,
+                libraryRoot: libraryDir(tenant),
+                // Keys this step's dependency cache. Per-account by design — see
+                // run-container.ts#runtimeCacheDir for why it is not shared.
+                tenant,
+                input: {
+                    agentRel: path.relative(workspaceRoot, agentDir).replaceAll("\\", "/"),
+                    prompt,
+                    model,
+                    effort,
+                    systemPrompt,
+                    allowed,
+                    mcpNames: consultNames,
+                    mcpServers,
+                    apis: substitutedApis,
+                    scripts: scriptSpecs,
+                    // The merged spec, not `front.runtime` — see the plan's `runtime`
+                    // field. A tool's own `runtime:` is part of what this step needs.
+                    runtime: runtime.spec,
+                    consults,
+                    timeoutSec: step.timeout,
+                    budgetUsd: stepBudgetUsd,
+                    price: tokenPrice,
+                    verify: step.verify,
+                    output: step.output,
+                    translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
+                    // The container sees the workspace at /workspace and the library
+                    // at /library; the roots are named host-side and moved here.
+                    search: searchRoots.map((r) => ({
+                        label: r.label,
+                        dir: r.dir.startsWith(libraryDir(tenant))
+                            ? path.posix.join("/library", path.relative(libraryDir(tenant), r.dir).replaceAll("\\", "/"))
+                            : path.posix.join("/workspace", path.relative(workspaceRoot, r.dir).replaceAll("\\", "/")),
+                    })),
+                    history: historyDigest,
+                    desks: deskDigest,
+                },
+                env: Object.fromEntries(Object.entries({
+                    // The platform's own model credential, when the agent names no
+                    // provider of its own — this is "models included": the host
+                    // process holds one key, and every isolated run borrows it.
+                    // A provider: block still wins, because providerEnv is spread
+                    // after and carries the agent's chosen endpoint + token.
+                    ...proxied(Object.keys(providerEnv).length === 0 ? modelEnv : providerEnv, keyName),
+                    ...(lease ? { [EGRESS_ENV]: lease.url } : {}),
+                    ...clockEnv,
+                    // Who is running: the in-process path stamps scripts with these
+                    // host-side, but a container rebuilds its tools from its own
+                    // environment, so without them here every script and verify in
+                    // the pod ran anonymous — and a verify comparing a marker to
+                    // $FOLDRUN_RUN_ID compared it to nothing.
+                    FOLDRUN_RUN_ID: runId,
+                    FOLDRUN_AGENT: step.agent,
+                    FOLDRUN_WORKSPACE: path.basename(workspaceRoot),
+                    ...sandboxSecrets,
+                }).filter((entry) => typeof entry[1] === "string")),
+                emit: pushWatching,
+                // Stamps the sandbox, so stopping this run can destroy it.
+                runId,
+                size,
+            });
+            // A busy provider gets another moment on the SAME supply before the
+            // fallback is considered: under a fan-out, twenty steps against one
+            // key are told "too many requests" together, and failing them all is
+            // a broken run where a few seconds would have been a slow one. Each
+            // attempt holds its own sandbox, so the meter owes the sum.
+            const firstArgs = isolatedArgs(platformModelEnv());
+            await lease?.commit();
+            let outcome = await runIsolated(firstArgs);
+            for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
+                const wait = backoffMs(n, lastRefusal);
+                push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
+                await sleep(wait);
+                // Judged fresh: the next attempt's own failure decides what happens
+                // next, not the one that sent us here.
+                lastRefusal = "";
+                const previous = outcome.timing;
+                const again = isolatedArgs(platformModelEnv());
+                await lease?.commit();
+                outcome = await runIsolated(again);
+                outcome = withEarlierTiming(outcome, previous);
+            }
+            // The second supply, tried exactly once, and only when the primary
+            // refused over money/auth/limits rather than the work failing. The
+            // retry is a fresh sandbox — the failed one is gone, and driveRun's
+            // whole contract is that re-driving is safe. A declared fallback
+            // replaces the provider block's env wholesale, so the spread order in
+            // isolatedArgs (providerEnv last) has to be overridden here.
+            if (outcome.status === "failed" && lastRefusal && secondSupply) {
+                push("info", `primary model supply refused (${lastRefusal.slice(0, 80)}) — retrying this step on the fallback provider`);
+                const first = outcome.timing;
+                const fallbackName = `${MODEL_KEY_NAME}_FALLBACK`;
+                const retryArgs = isolatedArgs(secondSupply, fallbackName);
+                // The fallback's own translator, or none: a fallback that speaks
+                // Anthropic must not inherit the primary's Chat-Completions door.
+                const fallbackArgs = {
+                    ...retryArgs,
+                    input: { ...retryArgs.input, translator: fallbackEnv && secondSupply === fallbackEnv ? secondTranslator : null },
+                    env: Object.fromEntries(Object.entries({ ...retryArgs.env, ...proxied(secondSupply, fallbackName) })
+                        .filter((entry) => typeof entry[1] === "string")),
+                };
+                await lease?.commit();
+                outcome = await runIsolated(fallbackArgs);
+                // Both attempts held sandboxes; the meter owes the sum. The first
+                // try's pod ran, was billed for by the platform, and must not
+                // vanish from the record because a second try replaced its outcome.
+                outcome = withEarlierTiming(outcome, first);
+            }
+            if (lease) {
+                for (const line of await lease.drainLog())
+                    push("info", line);
+                await lease.release();
+            }
+            publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            step.status = outcome.status;
+            step.result = outcome.result;
+            step.conclusion = outcome.conclusion;
+            if (outcome.data !== undefined)
+                step.data = outcome.data;
+            step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push);
+            step.tokens = outcome.usage
+                ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
+                : null;
+            step.actual = outcome.res ?? null;
+            if (outcome.res?.peakMemBytes || outcome.res?.rxBytes) {
+                const mb = (n) => (n === null ? "?" : (n / 1024 / 1024).toFixed(0));
+                push("info", `resources: cpu busy ${outcome.res.busyCpuSecs?.toFixed(1) ?? "?"}s · ` +
+                    `peak mem ${mb(outcome.res.peakMemBytes)}MB · ` +
+                    `net ${mb(outcome.res.rxBytes)}MB in / ${mb(outcome.res.txBytes)}MB out`);
+            }
+            // The compute meter, recorded on the step rather than derived later:
+            // the sandbox is gone by the time the run settles, and its lifetime
+            // is not recoverable from the run's own timestamps.
+            const secs = (ms) => Math.round(ms) / 1000;
+            step.computeSecs = outcome.timing ? secs(outcome.timing.totalMs) : null;
+            step.startupSecs = outcome.timing ? secs(outcome.timing.sandboxMs) : null;
+            // Which reservation those seconds held — as numbers, because the bill
+            // is per core-second and per GiB-second, and what was held must come
+            // from the record, never from what the config says at billing time.
+            step.size = size;
+            const lim = sizeLimits(size);
+            const gib = (() => {
+                const m = lim.memory.match(/^(\d+(?:\.\d+)?)\s*(Gi?|Mi?|g|m)?/i);
+                const n = m ? Number(m[1]) : 2;
+                return (m?.[2] ?? "Gi").toLowerCase().startsWith("m") ? n / 1024 : n;
+            })();
+            step.reserved = { cpus: Number(lim.cpus) || 2, memGiB: gib };
+        }
+        else {
+            const consultTools = buildConsultTools(consults, { ...process.env, ...liveSecrets, ...providerEnv }, (type, text) => push(type, text));
+            // @file secrets become 0600 paths here (host run), cleaned up in the
+            // finally — once, however many attempts follow.
+            const mat = materializeFileSecrets(agentDir, liveSecrets);
+            fileDir = mat.dir;
+            const attemptInProcess = (modelEnv) => executeStep({
+                agentDir,
+                workspaceRoot,
+                libraryRoot: libraryDir(tenant),
+                prompt,
+                model,
+                effort,
+                systemPrompt,
+                allowed,
+                mcpNames: consultNames,
+                mcpServers: {
+                    ...(apiTools.server ? { foldrun_apis: apiTools.server } : {}),
+                    ...(scriptTools.server ? { foldrun_scripts: scriptTools.server } : {}),
+                    ...(consultTools.server ? { foldrun_agents: consultTools.server } : {}),
+                    ...(searchTools.server ? { foldrun_search: searchTools.server } : {}),
+                    ...(historyTools.server ? { foldrun_history: historyTools.server } : {}),
+                    ...(deskTools.server ? { foldrun_desks: deskTools.server } : {}),
+                    ...mcpServers,
+                },
+                // Declared secrets reach the agent's scripts as env vars; the model
+                // only ever sees the variable names, not the values.
+                env: { ...process.env, ...clockEnv, ...mat.env, ...modelEnv },
+                timeoutSec: step.timeout,
+                budgetUsd: stepBudgetUsd,
+                price: tokenPrice,
+                verify: step.verify,
+                output: step.output,
+                // What the scripts saw, the verify sees: a flow can then check that
+                // the proof a step left names THIS run, not one that came before —
+                // copy-back never propagates a deletion, so a marker from an earlier
+                // run rides into every later sandbox.
+                verifyEnv: {
+                    ...clockEnv,
+                    ...(runId ? { FOLDRUN_RUN_ID: runId } : {}),
+                    FOLDRUN_AGENT: step.agent,
+                    FOLDRUN_WORKSPACE: path.basename(path.resolve(agentDir, "..", "..")),
+                    ...liveSecrets,
+                },
+                emit: pushWatching,
+            });
+            // With a translator the step's endpoint is the translator: started
+            // here, pointed at by the SDK's env, closed when the attempt ends.
+            const attemptThrough = async (modelEnv, spec) => {
+                if (!spec)
+                    return attemptInProcess(modelEnv);
+                const t = await startTranslator(spec);
+                try {
+                    return await attemptInProcess({ ...modelEnv, ...t.env });
+                }
+                finally {
+                    for (const line of t.drainLog())
+                        push("info", line.startsWith("translator") ? line : `translator: ${line}`);
+                    await t.close();
+                }
+            };
+            let outcome = await attemptThrough(providerEnv, translator);
+            // Same rule as the isolated path: a busy provider is waited out on
+            // the supply it refused from, before any fallback is considered.
+            for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
+                const wait = backoffMs(n, lastRefusal);
+                push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
+                await sleep(wait);
+                lastRefusal = "";
+                outcome = await attemptThrough(providerEnv, translator);
+            }
+            // Same rule as the isolated path: one retry, on a refusal, on the
+            // declared or platform second supply.
+            if (outcome.status === "failed" && lastRefusal && secondSupply) {
+                push("info", `primary model supply refused (${lastRefusal.slice(0, 80)}) — retrying this step on the fallback provider`);
+                outcome = await attemptThrough(secondSupply, fallbackEnv && secondSupply === fallbackEnv ? fallbackTranslator : null);
+            }
+            publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            step.status = outcome.status;
+            step.result = outcome.result;
+            step.conclusion = outcome.conclusion;
+            if (outcome.data !== undefined)
+                step.data = outcome.data;
+            // A consult's spend belongs to the step that asked.
+            const consultCost = consultTools.drainCost();
+            const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push);
+            step.costUsd = stepCost === null && consultCost === 0 ? null : (stepCost ?? 0) + consultCost;
+            step.tokens = outcome.usage
+                ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
+                : null;
+            for (const line of apiTools.drainLog())
+                push("info", `api: ${line}`);
+            for (const line of scriptTools.drainLog())
+                push("info", `script: ${line}`);
+        }
+    }
+    catch (err) {
+        step.status = "failed";
+        push("error", err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        try {
+            cleanupFileSecrets(fileDir);
+        }
+        catch {
+            // best-effort — a leftover scratch file is swept with the run's outputs
+        }
+    }
+    step.finishedAt = new Date().toISOString();
+    save();
+}
+// Block until a human approves or rejects the pending steps. Polls the run
+// record — the same file the dashboard writes through the approval API — so
+// no in-memory queue has to survive a restart. For as long as it takes: a
+// person answering on the 25th hour used to find the run had given up on
+// them at the 24th, and no clock of the platform's gets to decide that.
+async function waitForDecision(tenant, workspace, runId, indexes) {
+    for (;;) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const latest = readRun(tenant, workspace, runId);
+        if (!latest)
+            return false;
+        const stillWaiting = indexes.some((i) => latest.steps[i]?.status === "awaiting-approval");
+        if (!stillWaiting)
+            return true;
+    }
+}
+/**
+ * Copy a directory tree by reading and writing the bytes.
+ *
+ * Not fs.cpSync: that copies through the kernel's clone/copy_file_range
+ * path, which on a bind-mounted or network volume — exactly where a hosted
+ * install keeps its data — can report success and leave a zero-length file
+ * behind. Every archived run output was empty, and nothing failed to say
+ * so, which is the worst shape a bug can take. This works on every
+ * filesystem, and normalises the mode while it is here: what an agent
+ * produced belongs to the platform, not to the container umask that
+ * happened to create it.
+ */
+export function copyTreeBytes(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const src = path.join(from, entry.name);
+        const dst = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyTreeBytes(src, dst);
+        else if (entry.isFile())
+            fs.writeFileSync(dst, fs.readFileSync(src), { mode: 0o644 });
+    }
+}
+// Which of the host's own credentials an isolated run may borrow. Only the
+// model credential — a run gets the ability to think on the platform's
+// account, never the platform's other secrets, which is the entire reason
+// the container env is allowlisted instead of inheriting process.env.
+/**
+ * The platform's second model supply, tried when the first refuses over
+ * money or auth. Order is a cost decision: a flat-rate subscription as the
+ * engine, pay-per-token only when it runs dry —
+ *
+ *   FOLDRUN_FALLBACK_BASE_URL     e.g. https://openrouter.ai/api
+ *   FOLDRUN_FALLBACK_TOKEN        bearer for that endpoint
+ *   FOLDRUN_FALLBACK_HAIKU/SONNET/OPUS_MODEL   tier ids in ITS catalogue
+ *
+ * Empty ANTHROPIC_API_KEY on purpose: set, it goes out as x-api-key and a
+ * gateway rejects it; the fallback's whole credential is the bearer.
+ */
+/**
+ * Every `openapi:` URL the agent's API tools name — its own `apis:` and the
+ * http tools it opted into — so they can be fetched before the context is
+ * assembled. File paths need no fetching and are left out.
+ */
+function openApiSources(agentDir, tenant) {
+    const out = new Set();
+    try {
+        const { data } = matter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
+        const front = data;
+        for (const api of parseApis(front.apis))
+            if (api.openapi?.startsWith("https://"))
+                out.add(api.openapi);
+        const workspace = path.basename(path.resolve(agentDir, "..", ".."));
+        const available = { ...libraryTools(tenant), ...workspaceTools(tenant, workspace) };
+        for (const name of ownToolNames(front)) {
+            const def = available[name];
+            if (def?.kind === "http" && def.spec.openapi?.startsWith("https://"))
+                out.add(def.spec.openapi);
+        }
+    }
+    catch {
+        // an unreadable agent.md fails the step properly a moment later
+    }
+    return [...out];
+}
+function platformFallbackEnv() {
+    const base = process.env.FOLDRUN_FALLBACK_BASE_URL;
+    const token = process.env.FOLDRUN_FALLBACK_TOKEN;
+    if (!base || !token)
+        return null;
+    const out = {
+        ANTHROPIC_BASE_URL: base,
+        ANTHROPIC_AUTH_TOKEN: token,
+        ANTHROPIC_API_KEY: "",
+        CLAUDE_CODE_OAUTH_TOKEN: "",
+    };
+    for (const tier of ["HAIKU", "SONNET", "OPUS"]) {
+        const id = process.env[`FOLDRUN_FALLBACK_${tier}_MODEL`];
+        if (id)
+            out[`ANTHROPIC_DEFAULT_${tier}_MODEL`] = id;
+    }
+    return out;
+}
+/** A model-call failure the fallback can answer: the primary refusing over
+ *  credit, quota or auth — never a failure of the work itself, which would
+ *  fail identically anywhere. */
+function isProviderRefusal(text) {
+    // Money and auth words only, plus the API's own status codes. The first
+    // version matched bare "exceed", which is also how the pod backstop
+    // phrases a timeout — and a timed-out step got retried on the paid
+    // fallback it could only time out on again. A refusal the fallback can
+    // answer is about the ACCOUNT; anything about the work or the sandbox is
+    // not, however similar the vocabulary.
+    return /API Error: (401|402|403|429|5\d\d)|credits?\b|quota|billing|insufficient|overloaded/i.test(text);
+}
+/** How many times a busy provider is given another moment, and the longest
+ *  any one wait may be. Three is the industry's habit and the point where
+ *  waiting longer stops being kinder than failing. */
+export const OVERLOAD_RETRIES = 3;
+const MAX_BACKOFF_MS = 30_000;
+/**
+ * A refusal the SAME supply may answer in a moment — the provider is busy,
+ * not the account broken.
+ *
+ * The distinction is the whole point. 429 means "too many requests", and a
+ * provider says it for two unrelated reasons: the endpoint is momentarily
+ * saturated (wait, and it works), or the account is out of credit or over
+ * its quota (wait forever, it never works). Money words decide it: a 429
+ * that mentions credit, quota or billing is the account, and belongs to the
+ * fallback provider, not to a retry that can only fail again.
+ */
+export function isTransientOverload(text) {
+    if (/credits?\b|quota|billing|insufficient|payment|401|402|403/i.test(text))
+        return false;
+    return /\b(429|503|529)\b|overloaded|rate.?limit|too many requests|try again/i.test(text);
+}
+/**
+ * How long to wait before attempt `n` (1-based). A `retry-after` the
+ * provider named wins — it knows when it will be ready. Otherwise
+ * exponential, with jitter: twenty steps of a fan-out that all failed
+ * together must not all come back together, or the second wave is the first
+ * wave again. Capped, because a step waiting half a minute is already the
+ * limit of what a slow run should cost a person watching it.
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Carry an earlier attempt's sandbox time into the outcome that replaced
+ * it. Every attempt rented a pod; the meter owes all of them, and a record
+ * that shows only the last one under-bills the platform and lies to the
+ * customer about how long their step actually took.
+ */
+function withEarlierTiming(outcome, earlier) {
+    if (!earlier)
+        return outcome;
+    if (!outcome.timing)
+        return { ...outcome, timing: earlier };
+    return { ...outcome, timing: { ...outcome.timing, totalMs: outcome.timing.totalMs + earlier.totalMs } };
+}
+export function backoffMs(attempt, text = "", random = Math.random) {
+    // retry-after, retry_after, "retryAfter": — every spelling a provider or
+    // its SDK has used for the same header.
+    const named = text.match(/retry[-_\s]?after["':\s]+(\d+)/i);
+    if (named)
+        return Math.min(Math.max(Number(named[1]), 1) * 1000, MAX_BACKOFF_MS);
+    const base = Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
+    return Math.round(base * (0.5 + random() * 0.5));
+}
+function platformModelEnv() {
+    const { ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, CLAUDE_CODE_OAUTH_TOKEN, 
+    // What the tiers mean when the platform's own provider is not Anthropic.
+    // These belong to the credential: a base URL pointing at OpenRouter with
+    // Anthropic's model ids still attached is not a working provider, it is
+    // a 404 per step. Forwarded for the same reason the base URL is — an
+    // agent that names no provider gets the platform's, whole.
+    ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, } = process.env;
+    return {
+        ANTHROPIC_API_KEY,
+        ANTHROPIC_AUTH_TOKEN,
+        ANTHROPIC_BASE_URL,
+        CLAUDE_CODE_OAUTH_TOKEN,
+        ANTHROPIC_DEFAULT_HAIKU_MODEL,
+        ANTHROPIC_DEFAULT_SONNET_MODEL,
+        ANTHROPIC_DEFAULT_OPUS_MODEL,
+    };
+}
+/**
+ * Write a fresh run record and reset outputs — everything starting a run
+ * means *except* driving it. Split out so the queue can create a `queued`
+ * record for a worker to pick up, while `startFlowRun` keeps its promise of
+ * a run that is already going when it returns.
+ */
+/**
+ * `each: rows of <path>` — one item per CSV data row, each carrying the
+ * header so an instance reads as a one-row CSV. The path resolves the way
+ * the agent's own instructions do (relative to its folder) and is confined
+ * to the workspace: fan-out must not become a way to read past it.
+ */
+/**
+ * `each: items` — one instance per element of the previous group's data.
+ * An array is the items; an object with one array-valued field is that
+ * field (the common `{ "leads": [...] }` shape); anything else is nothing,
+ * said out loud. Each item crosses as JSON text, because `item` is what the
+ * instance's prompt quotes and what its result is labelled with.
+ */
+function jsonItems(data, step, take) {
+    let list = Array.isArray(data) ? data : null;
+    if (!list && data && typeof data === "object") {
+        const arrays = Object.entries(data).filter(([, v]) => Array.isArray(v));
+        if (arrays.length === 1)
+            list = arrays[0][1];
+        else if (arrays.length > 1) {
+            step.skipReason = `each: items — the previous data has ${arrays.length} array fields; return the list itself`;
+            return [];
+        }
+    }
+    if (!list) {
+        step.skipReason =
+            data === undefined
+                ? "each: items needs an `output: json` step before it that returned an array"
+                : "each: items — the previous data is not an array";
+        return [];
+    }
+    return list.slice(0, take).map((v) => (typeof v === "string" ? v : JSON.stringify(v)));
+}
+function csvItems(workspaceDir, step, take) {
+    const raw = step.eachPath ?? "";
+    if (!raw) {
+        step.skipReason = "each: rows needs a path — `each: rows of ../../storage/x.csv`";
+        return [];
+    }
+    const resolved = path.resolve(workspaceDir, "agents", step.agent, raw);
+    if (!resolved.startsWith(path.resolve(workspaceDir) + path.sep)) {
+        step.skipReason = `each: rows — ${raw} is outside this workspace`;
+        return [];
+    }
+    let text;
+    try {
+        text = fs.readFileSync(resolved, "utf8");
+    }
+    catch {
+        step.skipReason = `each: rows — ${raw} does not exist (yet?)`;
+        return [];
+    }
+    // Minimal CSV: quoted fields with embedded commas/newlines survive.
+    const rows = [];
+    let field = "", row = "", quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quoted) {
+            if (c === '"' && text[i + 1] === '"') {
+                field += '""';
+                i++;
+            }
+            else if (c === '"') {
+                field += c;
+                quoted = false;
+            }
+            else
+                field += c;
+        }
+        else if (c === '"') {
+            field += c;
+            quoted = true;
+        }
+        else if (c === "\n") {
+            rows.push(row + field);
+            row = "";
+            field = "";
+        }
+        else if (c !== "\r")
+            field += c;
+    }
+    if (row + field)
+        rows.push(row + field);
+    const [header, ...data] = rows.filter((r) => r.trim() !== "");
+    if (!header || data.length === 0) {
+        step.skipReason = `each: rows — ${raw} has no data rows`;
+        return [];
+    }
+    return data.slice(0, take).map((r) => `${header}\n${r}`);
+}
+export function createFlowRun(tenant, workspace, steps, flowName, status, tags = []) {
+    const run = {
+        id: `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+        flow: flowName,
+        tags,
+        status,
+        startedAt: new Date().toISOString(),
+        finishedAt: null,
+        steps: steps.map((s) => ({
+            agent: s.agent,
+            instruction: s.instruction,
+            group: s.group ?? 1,
+            optional: s.optional ?? false,
+            model: s.model,
+            effort: s.effort,
+            approve: s.approve,
+            when: s.when,
+            case: s.case,
+            else: s.else,
+            retry: s.retry,
+            timeout: s.timeout,
+            verify: s.verify,
+            loop: s.loop,
+            until: s.until,
+            loopRemaining: s.loop,
+            each: s.each,
+            eachPath: s.eachPath,
+            max: s.max,
+            onFail: s.onFail,
+            waitSecs: s.waitSecs,
+            waitFor: s.waitFor,
+            ask: s.ask,
+            preview: s.preview,
+            delegate: s.delegate,
+            output: s.output,
+            attempts: 0,
+            status: "pending",
+            events: [],
+            result: null,
+            costUsd: null,
+        })),
+    };
+    writeRun(tenant, workspace, run);
+    // Start every run from an empty outputs/ for each agent it will touch.
+    //
+    // Without this, `verify: test -s outputs/report.md` passes on run 2 because
+    // run 1 left the file behind — the one check that exists to catch a model
+    // claiming work it didn't do can be satisfied by a stale artifact. The
+    // previous contents aren't lost: they were archived when that run finished.
+    //
+    // This is the one thing resuming must not do: a resumed run's earlier steps
+    // already wrote there, and clearing it would delete the work being resumed.
+    const runRoot = workspaceDir(tenant, workspace);
+    for (const agent of new Set(run.steps.map((s) => s.agent))) {
+        const outputs = path.join(runRoot, "agents", agent, "outputs");
+        fs.rmSync(outputs, { recursive: true, force: true });
+        fs.mkdirSync(outputs, { recursive: true });
+    }
+    return run;
+}
+export function startFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = [], effortOverride) {
+    const run = createFlowRun(tenant, workspace, steps, flowName, "running", tags);
+    void driveRun(tenant, workspace, run, modelOverride, tags, { effortOverride });
+    return run;
+}
+/**
+ * Drive a run to completion: groups in order, approval gates, retries.
+ *
+ * Separate from starting one so a run can be picked up again. The loop reads
+ * every decision off the run record — `pending` steps are the work left, and
+ * a completed group's results are already on it — so re-entering it on a
+ * partly-finished record continues rather than restarts.
+ *
+ * `parkOnApproval` — a queue worker's slot is too expensive to spend polling
+ * a file for a person who may answer tomorrow. With it set, an approval gate
+ * saves the run as parked and returns; the approval API re-enqueues it and a
+ * worker re-enters this loop, which continues where the record says it
+ * stopped. Without it (the CLI, whose process belongs to the person waiting)
+ * the gate blocks in place exactly as before.
+ */
+/**
+ * Turn a gate's `preview:` patterns into the files under storage/ that
+ * exist right now, relative to storage/. `*` matches within a segment,
+ * `**` across segments; a pattern with no wildcard is kept only if the file
+ * is there. Sorted, deduplicated, capped — a preview is a handful of files,
+ * not a directory dump.
+ */
+export function resolvePreview(storageDir, patterns, cap = 12) {
+    const out = new Set();
+    for (const pattern of patterns) {
+        if (!/[*?]/.test(pattern)) {
+            if (fs.existsSync(path.join(storageDir, pattern)))
+                out.add(pattern);
+            continue;
+        }
+        const re = new RegExp("^" + pattern
+            .split("**").map((part) => part.split("*").map((x) => x.replace(/[.+^${}()|[\]\\?]/g, "\\$&")).join("[^/]*"))
+            .join(".*") + "$");
+        const walk = (dir, rel) => {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                if (e.name.startsWith("."))
+                    continue;
+                const r = rel ? `${rel}/${e.name}` : e.name;
+                if (e.isDirectory())
+                    walk(path.join(dir, e.name), r);
+                else if (re.test(r))
+                    out.add(r);
+            }
+        };
+        walk(storageDir, "");
+    }
+    return [...out].sort().slice(0, cap);
+}
+/** Store what a run has left in storage/ so far. Never fails the run: a
+ *  store that is down costs the gate its thumbnail, not the run its step. */
+/**
+ * Copy onto the in-memory run any gate decision that reached the record on
+ * disk while this driver was busy — status, stamps, note, the event line —
+ * so the driver's next save keeps it. Returns whether anything landed. Only
+ * steps this copy still shows as asking are touched: everything else on the
+ * record is this driver's own, and newer in memory than on disk.
+ */
+export function adoptDecisions(run, disk) {
+    if (!disk)
+        return false;
+    let any = false;
+    run.steps.forEach((s, i) => {
+        const d = disk.steps[i];
+        if (!d || s.status !== "awaiting-approval" || d.status === "awaiting-approval")
+            return;
+        s.status = d.status;
+        s.events = d.events;
+        if (d.approvedAt)
+            s.approvedAt = d.approvedAt;
+        if (d.approvalNote)
+            s.approvalNote = d.approvalNote;
+        any = true;
+    });
+    return any;
+}
+async function harvestQuietly(tenant, workspace, run) {
+    try {
+        await harvestFiles(tenant, workspace, `run:${run.id}`);
+    }
+    catch {
+        // bookkeeping only
+    }
+}
+/**
+ * The runs this process is driving right now. The one fact reconcile needs:
+ * a run in here is alive however quiet its step is, and a `running` run not
+ * in here has no driver — this is the only process that drives.
+ */
+export const drivingRuns = new Set();
+export function driveRun(tenant, workspace, run, modelOverride, tags = [], opts = {}) {
+    drivingRuns.add(run.id);
+    return driveRunInner(tenant, workspace, run, modelOverride, tags, opts).finally(() => {
+        drivingRuns.delete(run.id);
+    });
+}
+function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
+    const effortOverride = opts.effortOverride ?? null;
+    const pDir = workspaceDir(tenant, workspace);
+    const runRoot = pDir;
+    /**
+     * Persist the run — carrying forward a stop that arrived while we were busy.
+     *
+     * A stop is written to the record by another process (stopRun), and this
+     * loop holds the run in memory for as long as a group takes. Without the
+     * merge below, the next save silently overwrote `stopRequested`, and the
+     * between-groups check then read back the value it had just erased. A run
+     * stopped mid-group carried on to the end of the flow as if nothing had
+     * happened — observed on 2026-09-03, when a run stopped at 04:52 published
+     * to five live Google Business Profiles at 06:05.
+     *
+     * The flag is one-way: nothing here clears it, so the read-modify-write can
+     * only ever turn a stop on, never off.
+     */
+    const save = () => {
+        if (!run.stopRequested && readRun(tenant, workspace, run.id)?.stopRequested) {
+            run.stopRequested = true;
+        }
+        writeRun(tenant, workspace, run);
+    };
+    // Provenance: a memory an agent wrote gets stamped with who wrote it, per
+    // OKF v0.2. Without this a fact the model invented and a fact a person
+    // verified are indistinguishable on disk — and the reader has no way to
+    // know which one they're trusting.
+    const stampMemories = () => {
+        const agents = new Set(run.steps.map((s) => s.agent));
+        // Every memory bundle a run can write to, not just the agent's own. The
+        // workspace bundle is writable from any step — confine only denies
+        // knowledge/ — so a fact left there was going unstamped and untyped, and
+        // the bundle stopped conforming until someone ran `foldrun check`.
+        // The account library is not here: it is read-only from a run.
+        const dirs = [
+            // Attributable only when one agent could have written it.
+            { dir: path.join(runRoot, "memory"), agent: agents.size === 1 ? [...agents][0] : null },
+            ...[...agents].map((agent) => ({
+                dir: path.join(runRoot, "agents", agent, "memory"),
+                agent,
+            })),
+        ];
+        const written = [];
+        for (const { dir, agent } of dirs) {
+            // Each stamped file is a Creation in the bundle's log — that is what the
+            // log is for, and an agent's writes are exactly the changes a reader
+            // most wants dated. syncBundleFor logs the file it is given, so passing
+            // index.md logged nothing about the concept that actually appeared.
+            for (const rel of stampBundle(dir, agent)) {
+                syncBundleFor(path.join(dir, rel), "Creation");
+                written.push(path.relative(runRoot, path.join(dir, rel)).replaceAll("\\", "/"));
+            }
+        }
+        // On the record, so the run page can say "this run learned two things"
+        // and a reviewer can open exactly those files.
+        if (written.length)
+            run.memoryWrites = [...(run.memoryWrites ?? []), ...written];
+    };
+    // Archive what a run produced, so history survives the next run's reset.
+    const archive = () => {
+        for (const agent of new Set(run.steps.map((s) => s.agent))) {
+            const from = path.join(runRoot, "agents", agent, "outputs");
+            if (!fs.existsSync(from) || fs.readdirSync(from).length === 0)
+                continue;
+            copyTreeBytes(from, path.join(runRoot, "runs", run.id, "outputs", agent));
+        }
+    };
+    // A parked run is paused, not finished — the completion bookkeeping in
+    // `finally` (finishedAt, archive, memory stamps) must not touch it.
+    let parked = false;
+    return (async () => {
+        try {
+            // Entering the loop is what makes a run live, whatever state it was
+            // saved in: `queued` from the queue, `awaiting-approval` from a park.
+            if (run.status !== "running") {
+                run.status = "running";
+                run.parkedAt = null;
+                save();
+            }
+            // A step still marked `running` here is an orphan: exactly one driver
+            // holds a run's job, so whatever process set that status is gone —
+            // killed mid-step by a deploy or a crash. Left alone it is worse than
+            // failed: the group loop only runs `pending` steps, so the driver
+            // would step over the unfinished work, run everything after it, and
+            // mark the run completed — a run that reports success on work that
+            // never happened, which reconcile can then never see. Reset it to
+            // pending and it simply runs again; driveRun's whole contract is that
+            // re-driving a partly-finished record is safe.
+            let orphaned = false;
+            for (const step of run.steps) {
+                if (step.status !== "running")
+                    continue;
+                orphaned = true;
+                step.status = "pending";
+                step.events.push({
+                    t: new Date().toISOString(),
+                    type: "info",
+                    text: "interrupted mid-step (platform restart) — running again from the start of the step",
+                });
+            }
+            if (orphaned) {
+                // The sandbox outlives the process that created it — a step with no
+                // `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.
+                try {
+                    if (process.env.FOLDRUN_RUN_ISOLATION === "container")
+                        killRunSandboxes(run.id);
+                    else
+                        platform.killRunSandboxes(run.id);
+                }
+                catch {
+                    // a sandbox we cannot reach must not stop the run from resuming
+                }
+            }
+            save();
+            // Put the workspace's files on disk before the first step, so they are
+            // simply *there* when the step's container copy is taken. This is the
+            // whole of the agent-facing file API: a directory. Nothing here hands
+            // the model a bucket, a URL or a credential, and a run pod that has
+            // never heard of S3 reads a 200MB PDF the same way it reads AGENTS.md.
+            //
+            // Runs on resume too — a parked run's container is long gone, and the
+            // one it comes back in needs the same files the first one had.
+            try {
+                const brought = await materializeFiles(tenant, workspace);
+                if (brought.length) {
+                    run.steps[0]?.events.push({
+                        t: new Date().toISOString(),
+                        type: "info",
+                        text: `files: ${brought.length} brought into the workspace`,
+                    });
+                }
+            }
+            catch (err) {
+                // A file store that is down must not take the run with it: most flows
+                // never touch storage/, and the ones that do will fail their own verify.
+                run.steps[0]?.events.push({
+                    t: new Date().toISOString(),
+                    type: "error",
+                    text: `files: could not be brought in — ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            // Group steps by their group number, ascending. Rebuilt on demand
+            // because two patterns mutate the step list mid-run: fan-out expands a
+            // step into instances, and an evaluator loop winds groups back.
+            const orderedGroups = () => {
+                const groups = new Map();
+                for (const s of run.steps) {
+                    const list = groups.get(s.group) ?? [];
+                    list.push(s);
+                    groups.set(s.group, list);
+                }
+                return [...groups.entries()].sort(([a], [b]) => a - b).map(([, g]) => g);
+            };
+            let ordered = orderedGroups();
+            // What each finished group produced, by position — so a loop that
+            // winds back can hand the re-run the same upstream context the first
+            // pass saw, instead of its own stale output.
+            const groupResults = [];
+            const groupConclusions = [];
+            // Every earlier group, oldest first, so a group-3 reporter sees what
+            // group 1 measured and not only what group 2 diagnosed. This used to
+            // hand back the nearest earlier group alone, and a reporter two groups
+            // after the measurement went looking on disk for a feed that was
+            // already in the run. The cap (CONTEXT_CHARS, applied where the prompt
+            // is assembled) keeps the newest: when the total is over it, the
+            // oldest groups are dropped whole before anything is cut mid-text.
+            const contextBefore = (gi) => joinEarlierGroups(groupResults, gi);
+            // The data half of the same handoff: what the nearest earlier group
+            // returned through `output: json`. Rebuilt from the record rather than
+            // kept only in memory, so a resumed run hands step 3 the value step 1
+            // returned before the park.
+            const groupData = [];
+            const dataBefore = (gi) => {
+                for (let i = gi - 1; i >= 0; i--)
+                    if (groupData[i] !== undefined)
+                        return groupData[i];
+                return undefined;
+            };
+            const dataOf = (group) => {
+                const carrying = group.filter((s) => s.status === "completed" && s.data !== undefined);
+                if (carrying.length === 0)
+                    return undefined;
+                if (carrying.length === 1 && !carrying[0].item)
+                    return carrying[0].data;
+                return carrying.map((s) => ({ agent: s.agent, ...(s.item ? { item: s.item } : {}), data: s.data }));
+            };
+            const resultsOf = (group) => {
+                const results = group
+                    .filter((s) => s.status === "completed" && s.result)
+                    .map((s) => s.item
+                    ? `## Result for item: ${s.item.slice(0, 80)} (${s.agent})\n\n${s.result}`
+                    : group.length > 1
+                        ? `## Result from ${s.agent}\n\n${s.result}`
+                        : s.result);
+                return results.length ? results.join("\n\n") : null;
+            };
+            // What each step concluded — its final turn — for the handoffs that
+            // should read a conclusion rather than a transcript (`each: lines`).
+            const conclusionsOf = (group) => {
+                const out = group
+                    .filter((s) => s.status === "completed" && (s.conclusion || s.result))
+                    .map((s) => s.conclusion || s.result);
+                return out.length ? out.join("\n") : null;
+            };
+            // Groups already finished before this drive (a resume, or a run picked
+            // up after a gate) still carry their results and data on the record.
+            // Rebuilding all three here is what lets the step after an approval
+            // read what came before it, not only the gate's question.
+            for (const [i, g] of ordered.entries()) {
+                if (g.every((s) => s.status !== "pending" && s.status !== "running" && s.status !== "awaiting-approval")) {
+                    groupResults[i] = resultsOf(g);
+                    groupConclusions[i] = conclusionsOf(g);
+                    groupData[i] = dataOf(g);
+                }
+            }
+            // budget: — the flow's own per-run cap, stamped on the record the first
+            // time it is driven. Between groups, not mid-step: a step in flight is
+            // money already committed, and stopping it half-way keeps the cost
+            // and loses the work.
+            if (run.budgetUsd === undefined) {
+                run.budgetUsd = readFlow(tenant, workspace, run.flow)?.budget ?? null;
+                save();
+            }
+            let gi = 0;
+            let context = null;
+            let ctxData = undefined;
+            while (gi < ordered.length) {
+                const group = ordered[gi];
+                context = contextBefore(gi);
+                ctxData = dataBefore(gi);
+                if (run.budgetUsd && runCost(run) >= run.budgetUsd && group.some((s) => s.status === "pending")) {
+                    const spent = runCost(run);
+                    const last = run.steps.findLast((s) => s.status === "completed" || s.status === "failed") ?? run.steps[0];
+                    last?.events.push({
+                        t: new Date().toISOString(),
+                        type: "error",
+                        text: `over budget — $${spent.toFixed(4)} spent of the flow's $${run.budgetUsd.toFixed(2)} (budget: in the flow file); the remaining steps were not run`,
+                    });
+                    for (const s of run.steps) {
+                        if (s.status === "pending") {
+                            s.status = "skipped";
+                            s.skipReason = "over budget";
+                        }
+                    }
+                    run.status = "failed";
+                    save();
+                    break;
+                }
+                // wait: — the clock starts when the run REACHES the step, so
+                // "wait: 3d" means three days after the previous group finished,
+                // surviving restarts because the deadline is stamped on the record.
+                for (const s of group) {
+                    if (s.status === "pending" && s.waitSecs && !s.waitUntil) {
+                        s.waitUntil = new Date(Date.now() + s.waitSecs * 1000).toISOString();
+                        s.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `waiting until ${s.waitUntil} (wait: ${s.waitSecs}s)`,
+                        });
+                    }
+                }
+                const stillWaiting = group
+                    .filter((s) => s.status === "pending" && s.waitUntil)
+                    .map((s) => new Date(s.waitUntil).getTime())
+                    .filter((t) => t > Date.now());
+                if (stillWaiting.length) {
+                    save();
+                    if (opts.parkOnApproval) {
+                        // Back to the queue with a not-before — a three-day wait must
+                        // not hold a worker slot, a process, or survive on either. The
+                        // files so far are stored first, as at an approval park.
+                        await harvestQuietly(tenant, workspace, run);
+                        run.status = "queued";
+                        run.parkedAt = new Date().toISOString();
+                        parked = true;
+                        save();
+                        return;
+                    }
+                    // Foreground (CLI) runs sleep in slices so Ctrl-C stays prompt.
+                    await new Promise((r) => setTimeout(r, Math.min(Math.min(...stillWaiting) - Date.now(), 30_000)));
+                    continue;
+                }
+                // Fan-out: a step with `each:` becomes one instance per item of the
+                // previous group's result, capped, all in this same group — the
+                // declared shape stays readable in the file, the width comes from
+                // the data. The template survives as a skipped step for the trace.
+                // `each: lines` splits what the previous group CONCLUDED — each step's
+                // final turn — not every turn joined. A translator that narrated one
+                // line per file write put the same sentence in front of eight
+                // validators; its final turn was the list. Falls back to the joined
+                // result for records made before `conclusion` existed.
+                const eachSource = gi > 0 ? (groupConclusions[gi - 1] ?? groupResults[gi - 1]) : null;
+                for (const step of [...group]) {
+                    if (!step.each || step.status !== "pending" || step.item)
+                        continue;
+                    const cap = Math.min(step.max ?? 10, 20);
+                    const items = step.each === "rows"
+                        ? csvItems(pDir, step, cap + 1)
+                        : step.each === "items"
+                            ? jsonItems(ctxData, step, cap + 1)
+                            : (eachSource ?? "")
+                                .split("\n")
+                                .map((l) => l.replace(/^[-*\d.)\s]+/, "").trim())
+                                .filter(Boolean)
+                                .slice(0, cap + 1);
+                    const dropped = items.length > cap ? "at least one" : "";
+                    const used = items.slice(0, cap);
+                    step.status = "skipped";
+                    if (used.length === 0) {
+                        step.skipReason ||= "each: the previous group produced no items";
+                        continue;
+                    }
+                    step.skipReason = `expanded into ${used.length} item${used.length === 1 ? "" : "s"}`;
+                    step.events.push({
+                        t: new Date().toISOString(),
+                        type: "info",
+                        text: `fan-out: ${used.length} instance${used.length === 1 ? "" : "s"}` +
+                            (dropped ? ` (more items existed — capped at ${cap})` : ""),
+                    });
+                    const at = run.steps.indexOf(step);
+                    const instances = used.map((item) => ({
+                        ...step,
+                        each: undefined,
+                        max: undefined,
+                        skipReason: undefined,
+                        item,
+                        status: "pending",
+                        events: [],
+                        result: null,
+                        costUsd: null,
+                        attempts: 0,
+                    }));
+                    run.steps.splice(at + 1, 0, ...instances);
+                    ordered = orderedGroups();
+                }
+                save();
+                // A person asked for this to stop. Checked between groups, off the
+                // record rather than in memory, because the request arrives in
+                // another process — the same way an approval decision does. The
+                // sandbox for any in-flight step was already destroyed by stopRun;
+                // this is what keeps the *next* group from starting.
+                const stopCheck = readRun(tenant, workspace, run.id);
+                if (stopCheck?.stopRequested) {
+                    for (const s of run.steps) {
+                        if (s.status === "pending" || s.status === "running") {
+                            s.status = "skipped";
+                            s.skipReason = "run stopped";
+                        }
+                    }
+                    run.status = "failed";
+                    run.stopRequested = true;
+                    save();
+                    break;
+                }
+                const freshGroup = ordered[gi];
+                // Validate agents exist before launching the group.
+                let missing = false;
+                for (const step of freshGroup) {
+                    // Only what still has work to do. This walked every step in the
+                    // group regardless of status, which never showed on a fresh run
+                    // because they all start pending — but on a resumed one it rewrote
+                    // finished steps to `failed`, destroying the history it was
+                    // resuming around.
+                    if (step.status !== "pending")
+                        continue;
+                    const aDir = path.join(pDir, "agents", step.agent);
+                    if (!fs.existsSync(path.join(aDir, "agent.md"))) {
+                        step.status = "failed";
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "error",
+                            text: `agent "${step.agent}" not found in workspace`,
+                        });
+                        if (!step.optional)
+                            missing = true;
+                    }
+                }
+                save();
+                if (missing) {
+                    run.status = "failed";
+                    break;
+                }
+                const ctx = context;
+                // `when:` — skip a step whose condition isn't met by prior results.
+                for (const step of freshGroup) {
+                    if (step.status !== "pending" || !step.when)
+                        continue;
+                    const met = (ctx ?? "").toLowerCase().includes(step.when.toLowerCase());
+                    if (!met) {
+                        step.status = "skipped";
+                        step.skipReason = `condition not met: when "${step.when}"`;
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `skipped — previous results do not mention "${step.when}"`,
+                        });
+                    }
+                }
+                save();
+                // `case:`/`else:` — exclusive routing. Of this group's case steps,
+                // the FIRST whose text appears in the previous results runs; the
+                // rest are routed past. `else:` runs only when no case matched.
+                // (`when:` above stays independent — every matching when runs —
+                // which is why routing is its own vocabulary instead of a mode.)
+                const caseSteps = freshGroup.filter((s) => s.status === "pending" && s.case);
+                if (caseSteps.length || freshGroup.some((s) => s.status === "pending" && s.else)) {
+                    let matchedCase = null;
+                    for (const step of caseSteps) {
+                        if (!matchedCase && (ctx ?? "").toLowerCase().includes(step.case.toLowerCase())) {
+                            matchedCase = step;
+                            continue;
+                        }
+                        step.status = "skipped";
+                        step.skipReason = matchedCase
+                            ? `routed past — "${matchedCase.case}" matched first`
+                            : `case not matched: "${step.case}"`;
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: step.skipReason,
+                        });
+                    }
+                    for (const step of freshGroup) {
+                        if (step.status !== "pending" || !step.else)
+                            continue;
+                        if (matchedCase) {
+                            step.status = "skipped";
+                            step.skipReason = `routed past — "${matchedCase.case}" matched`;
+                            step.events.push({ t: new Date().toISOString(), type: "info", text: step.skipReason });
+                        }
+                    }
+                    save();
+                }
+                // Approval gate — pause the whole run until a human decides. The run
+                // record is the queue: it sits in awaiting-approval until the API
+                // flips the step back to pending.
+                // `!s.approvedAt` — a step approved before the process went away is
+                // already answered. Filtering on status alone asked again.
+                // `wait: event` parks in the same place: the gate is the same, the
+                // key is held by a machine. A person can still release it by hand.
+                const needsApproval = freshGroup.filter((s) => s.status === "pending" && (s.approve || s.ask || s.waitFor === "event") && !s.approvedAt);
+                if (needsApproval.length) {
+                    for (const step of needsApproval) {
+                        step.status = "awaiting-approval";
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            // ask: is the same gate carrying a question — the answer
+                            // arrives as the approval note and rides into the prompt.
+                            text: step.ask
+                                ? `waiting for an answer: ${step.ask}`
+                                : step.waitFor === "event"
+                                    ? `waiting for an external event — release it with POST ${eventUrl(tenant, workspace, run.id)}`
+                                    : "waiting for approval before running",
+                        });
+                    }
+                    run.status = "awaiting-approval";
+                    save();
+                    // The gate's declared preview, resolved now against what the run
+                    // has actually produced — a glob at park time, a list of files on
+                    // the record for as long as the run waits.
+                    for (const s of needsApproval) {
+                        if (s.preview?.length)
+                            s.previewFiles = resolvePreview(path.join(workspaceDir(tenant, workspace), "storage"), s.preview);
+                    }
+                    save();
+                    if (opts.parkOnApproval) {
+                        // What the run has produced so far becomes stored files NOW, not
+                        // at the end: the gate shows the thumbnail a step is about to
+                        // publish, and the Storage page answers "what did it make" while
+                        // the person decides. Unchanged files are skipped by hash, and
+                        // the local copies stay for the resumed step to read.
+                        await harvestQuietly(tenant, workspace, run);
+                        // The gate has been on the record — and in an inbox — since the
+                        // save above, so a decision can land while the harvest runs.
+                        // The API wrote it to disk; it did not enqueue a resume, because
+                        // parkedAt was not set yet; and the save below, from memory,
+                        // would erase it. That was a lost approval and a run that waited
+                        // forever (2026-09-06, approved two seconds after it parked).
+                        // Take what landed, then do the enqueue the API would have done.
+                        const decided = adoptDecisions(run, readRun(tenant, workspace, run.id));
+                        // Hand the slot back. The approval API sees parkedAt and
+                        // re-enqueues; re-entering this loop skips finished groups and
+                        // lands back here with the decision already on the record.
+                        run.parkedAt = new Date().toISOString();
+                        parked = true;
+                        save();
+                        if (decided && run.steps.every((s) => s.status !== "awaiting-approval")) {
+                            await platform.enqueueResume(tenant, workspace, run.id);
+                        }
+                        return;
+                    }
+                    const decided = await waitForDecision(tenant, workspace, run.id, needsApproval.map((s) => run.steps.indexOf(s)));
+                    if (!decided) {
+                        run.status = "failed";
+                        break;
+                    }
+                    // Re-read: the API rewrote the file, so refresh statuses in place.
+                    const latest = readRun(tenant, workspace, run.id);
+                    if (latest) {
+                        latest.steps.forEach((s, i) => {
+                            run.steps[i].status = s.status;
+                            run.steps[i].events = s.events;
+                            // What the decision carried, not just that it happened: the
+                            // note and the event payload are what the step's prompt reads,
+                            // and copying status alone dropped them on the in-process path.
+                            run.steps[i].approvedAt = s.approvedAt;
+                            run.steps[i].approvalNote = s.approvalNote;
+                            run.steps[i].eventPayload = s.eventPayload;
+                        });
+                    }
+                    run.status = "running";
+                    save();
+                    if (freshGroup.every((s) => s.status !== "pending")) {
+                        // everything in this group was rejected
+                        if (freshGroup.some((s) => s.status === "failed" && !s.optional)) {
+                            run.status = "failed";
+                            break;
+                        }
+                        gi += 1;
+                        continue;
+                    }
+                }
+                // The hard cap: what is left of the flow's budget, shared evenly
+                // across the steps this group launches together. Each step stops
+                // itself mid-turn at its share, so a fan-out of twenty cannot end
+                // twenty steps over — the shares sum to what was left. Between
+                // groups the check above still refuses to start the next one.
+                const launching = freshGroup.filter((s) => s.status === "pending");
+                const ceilingUsd = stepCeiling(run.budgetUsd, runCost(run), launching.length);
+                await Promise.all(launching
+                    .map(async (step) => {
+                    const attempts = (step.retry ?? 0) + 1;
+                    for (let attempt = 1; attempt <= attempts; attempt++) {
+                        step.attempts = attempt;
+                        step.status = "running";
+                        save();
+                        await runStep(path.join(pDir, "agents", step.agent), tenant, step, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, ceilingUsd);
+                        // runStep mutates step.status; read it through a widened local
+                        // so TS doesn't keep the "running" narrowing from above.
+                        const outcome = step.status;
+                        if (outcome !== "failed" || attempt === attempts)
+                            break;
+                        // A stop destroys the step's sandbox, which reads here as a
+                        // failed attempt — and a failed attempt used to be retried in
+                        // a fresh sandbox, so a stopped `retry: 2` step ran twice
+                        // more. save() merges the flag from the record.
+                        save();
+                        if (run.stopRequested)
+                            break;
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `attempt ${attempt} failed — retrying (${attempts - attempt} left)`,
+                        });
+                        save();
+                    }
+                }));
+                // 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 —
+                // the trace keeps both records, so "who actually did this" stays
+                // answerable.
+                // Not after a stop: the failure a stop leaves behind is not one a
+                // rescuer should take over. The merge in save() surfaces the flag.
+                save();
+                for (const step of freshGroup) {
+                    if (run.stopRequested)
+                        break;
+                    if (step.status !== "failed" || !step.onFail)
+                        continue;
+                    const rescuerDir = path.join(pDir, "agents", step.onFail);
+                    if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "error",
+                            text: `on-fail: "${step.onFail}" is not an agent in this workspace — no rescue`,
+                        });
+                        continue;
+                    }
+                    step.events.push({
+                        t: new Date().toISOString(),
+                        type: "info",
+                        text: `failed — handing to [[${step.onFail}]] (on-fail)`,
+                    });
+                    const failure = (step.result ?? step.events.filter((e) => e.type === "error").map((e) => e.text).join("\n")).slice(0, 4000);
+                    const rescue = {
+                        agent: step.onFail,
+                        instruction: `${step.instruction}\n\n<rescue>\nYou are taking this step over: [[${step.agent}]] attempted it and failed. ` +
+                            `Its failure, for whatever it is worth:\n${failure}\n</rescue>`,
+                        group: step.group,
+                        optional: false,
+                        model: step.model,
+                        effort: step.effort,
+                        timeout: step.timeout,
+                        // The rescuer inherits the contract, not just the job: a step
+                        // that promised data still owes data when someone else does it.
+                        output: step.output,
+                        attempts: 0,
+                        status: "pending",
+                        events: [],
+                        result: null,
+                        costUsd: null,
+                    };
+                    run.steps.splice(run.steps.indexOf(step) + 1, 0, rescue);
+                    save();
+                    rescue.attempts = 1;
+                    rescue.status = "running";
+                    save();
+                    await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData);
+                    // runStep mutates rescue.status; widen past TS's "running" narrowing.
+                    const rescueOutcome = rescue.status;
+                    if (rescueOutcome === "completed") {
+                        step.status = "completed";
+                        step.result = rescue.result;
+                        step.conclusion = rescue.conclusion;
+                        if (rescue.data !== undefined)
+                            step.data = rescue.data;
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `rescued by [[${step.onFail}]] — its result stands as this step's`,
+                        });
+                    }
+                    else {
+                        step.events.push({
+                            t: new Date().toISOString(),
+                            type: "error",
+                            text: `on-fail: [[${step.onFail}]] also failed`,
+                        });
+                    }
+                    save();
+                }
+                const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional);
+                if (requiredFailed) {
+                    run.status = "failed";
+                    break;
+                }
+                groupResults[gi] = resultsOf(freshGroup);
+                groupConclusions[gi] = conclusionsOf(freshGroup);
+                groupData[gi] = dataOf(freshGroup);
+                // delegate: — the completed chooser's picks become a fresh group
+                // right after this one. The choice SET is the file's; only the
+                // picks and their instructions are the model's, and both are on
+                // the record. Once per chooser, loop rewinds included.
+                for (const chooser of freshGroup) {
+                    if (!chooser.delegate?.length || chooser.status !== "completed" || chooser.delegated)
+                        continue;
+                    chooser.delegated = true;
+                    const allowed = new Set(chooser.delegate);
+                    const picks = [];
+                    const seenAgents = new Set();
+                    for (const line of (chooser.result ?? "").split("\n")) {
+                        const m = line.match(/^\s*(?:[-*\d.)\s]*)\[?\[?([a-z0-9-]+)\]?\]?\s*:\s*(.+)$/);
+                        if (!m || !allowed.has(m[1]) || seenAgents.has(m[1]))
+                            continue;
+                        if (!fs.existsSync(path.join(pDir, "agents", m[1], "agent.md")))
+                            continue;
+                        seenAgents.add(m[1]);
+                        picks.push({
+                            agent: m[1],
+                            instruction: m[2].trim(),
+                            group: chooser.group,
+                            optional: false,
+                            attempts: 0,
+                            status: "pending",
+                            events: [],
+                            result: null,
+                            costUsd: null,
+                        });
+                        if (picks.length >= 5)
+                            break;
+                    }
+                    // Delegating to nobody is a legitimate answer, not a fault: a
+                    // `delegate:` set is who the step MAY call on, and most runs of a
+                    // healthy flow need none of them. Logging that as an error put a
+                    // red line on a step that did exactly the right thing, which is
+                    // how a person learns to stop reading red lines.
+                    chooser.events.push({
+                        t: new Date().toISOString(),
+                        type: "info",
+                        text: picks.length
+                            ? `delegated to ${picks.map((p) => `[[${p.agent}]]`).join(", ")}`
+                            : `delegate: chose nobody (could have called on ${chooser.delegate.join(", ")})`,
+                    });
+                    if (picks.length) {
+                        run.steps.splice(run.steps.indexOf(chooser) + 1, 0, ...picks);
+                        ordered.splice(gi + 1, 0, picks);
+                    }
+                    save();
+                }
+                // Evaluator loop: a completed step with `loop:` whose result lacks
+                // its `until:` marker sends this group and the one before it around
+                // again — at most `loop:` times, so the worst case is still readable
+                // off the flow file. Approval marks survive the rewind: a person
+                // answered, and the question has not changed.
+                const looper = freshGroup.find((s) => s.loop && s.until && s.status === "completed");
+                if (looper?.until &&
+                    !saysUntilMarker(looper.result ?? null, looper.until)) {
+                    if ((looper.loopRemaining ?? 0) > 0 && gi > 0) {
+                        looper.loopRemaining = (looper.loopRemaining ?? 0) - 1;
+                        looper.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `loop: result does not say "${looper.until}" on a line of its own — winding back one group (${looper.loopRemaining} cycle${looper.loopRemaining === 1 ? "" : "s"} left)`,
+                        });
+                        for (const s of [...ordered[gi - 1], ...freshGroup]) {
+                            if (s.status === "skipped" && s.each)
+                                continue; // an expanded template stays expanded
+                            s.status = "pending";
+                            s.result = null;
+                        }
+                        groupResults[gi] = null;
+                        groupResults[gi - 1] = null;
+                        groupConclusions[gi] = null;
+                        groupConclusions[gi - 1] = null;
+                        save();
+                        gi -= 1;
+                        continue;
+                    }
+                    looper.status = "failed";
+                    looper.events.push({
+                        t: new Date().toISOString(),
+                        type: "error",
+                        text: `loop exhausted: after ${looper.loop} cycle${looper.loop === 1 ? "" : "s"} the result still does not say "${looper.until}"`,
+                    });
+                    save();
+                    if (!looper.optional) {
+                        run.status = "failed";
+                        break;
+                    }
+                }
+                gi += 1;
+            }
+            if (run.status === "running")
+                run.status = "completed";
+            for (const s of run.steps)
+                if (s.status === "pending")
+                    s.status = "skipped";
+        }
+        catch (err) {
+            run.status = "failed";
+            run.steps.forEach((s) => {
+                if (s.status === "running") {
+                    s.status = "failed";
+                    s.events.push({
+                        t: new Date().toISOString(),
+                        type: "error",
+                        text: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            });
+        }
+        finally {
+            if (!parked) {
+                run.finishedAt = new Date().toISOString();
+                // What this run concluded, in one line, captured before the record is
+                // saved for the last time. Read from the reply that already says it
+                // rather than asked for separately: the folder gains nothing to
+                // learn, and the runs list and the notification stop having to say
+                // only "completed".
+                run.summary = runSummary(run);
+                // Archive before the next run resets outputs/ — a failed run's
+                // artifacts are usually the most interesting ones, so this runs on
+                // failure too.
+                try {
+                    stampMemories();
+                    archive();
+                }
+                catch {
+                    // never let bookkeeping fail a run that already finished
+                }
+                // Whatever the run left in storage/ becomes a stored file, stamped with
+                // the run and the agent that wrote it — which is what lets the
+                // dashboard answer "where did this PDF come from?" without a join
+                // table. On failure too: a failed run's half-written artifact is
+                // usually the one worth looking at.
+                try {
+                    const { saved, errors } = await harvestFiles(tenant, workspace, `run:${run.id}`);
+                    const last = run.steps.findLast((s) => s.status !== "pending") ?? run.steps[0];
+                    if (saved.length) {
+                        last?.events.push({
+                            t: new Date().toISOString(),
+                            type: "info",
+                            text: `files: saved ${saved.join(", ")}`,
+                        });
+                    }
+                    for (const e of errors) {
+                        last?.events.push({ t: new Date().toISOString(), type: "error", text: `files: ${e}` });
+                    }
+                }
+                catch {
+                    // same rule as archive(): bookkeeping never fails a finished run
+                }
+                save();
+            }
+        }
+    })();
+}
+function readFlow(tenant, workspace, flowName) {
+    const dir = path.join(workspaceDir(tenant, workspace), "flows");
+    if (!fs.existsSync(dir))
+        return null;
+    for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+        const flow = parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8"));
+        if (flow.name === flowName)
+            return flow;
+    }
+    return null;
+}
+// Splice `[[flow:other]]` steps into the parent's step list, renumbering
+// groups so the nested flow's own parallelism survives. Depth-limited, and
+// a cycle raises rather than expanding forever.
+function expandSubflows(tenant, workspace, steps, seen = [], depth = 0) {
+    if (depth > 3)
+        throw new Error("flow nesting too deep (max 3)");
+    const out = [];
+    let group = 0;
+    for (const [i, step] of steps.entries()) {
+        const startsNewGroup = i === 0 || step.group !== steps[i - 1].group;
+        if (startsNewGroup)
+            group += 1;
+        if (!step.subflow) {
+            out.push({ ...step, group });
+            continue;
+        }
+        if (seen.includes(step.subflow)) {
+            throw new Error(`flow cycle: ${[...seen, step.subflow].join(" → ")}`);
+        }
+        const nested = readFlow(tenant, workspace, step.subflow);
+        if (!nested)
+            throw new Error(`flow "${step.subflow}" not found`);
+        const nestedSteps = expandSubflows(tenant, workspace, nested.steps, [...seen, step.subflow], depth + 1);
+        // Nested groups continue from here; the parent's next group follows them.
+        const base = group - 1;
+        let maxGroup = group;
+        for (const ns of nestedSteps) {
+            const g = base + ns.group;
+            maxGroup = Math.max(maxGroup, g);
+            out.push({
+                ...ns,
+                group: g,
+                optional: ns.optional || step.optional,
+                instruction: ns.instruction || step.instruction,
+            });
+        }
+        group = maxGroup;
+    }
+    return out;
+}
+export function loadFlow(tenant, workspace, flowName) {
+    const flow = readFlow(tenant, workspace, flowName);
+    if (!flow)
+        return null;
+    if (!flow.steps.some((s) => s.subflow))
+        return flow;
+    return { ...flow, steps: expandSubflows(tenant, workspace, flow.steps, [flowName]) };
+}
+// ---------------------------------------------------------------- recovery
+/**
+ * How long a run may sit in `running` with nobody touching it before it is
+ * considered abandoned.
+ *
+ * Long enough that a slow model call is never mistaken for a dead process —
+ * a single step can legitimately take minutes — and short enough that a
+ * restarted server does not leave yesterday's run looking live.
+ */
+// A run this process is driving is never abandoned, however long its step
+// is quiet — a 40-minute script is work, not a fault, and the platform sets
+// no clock on work. A `running` run nobody here is driving has lost its
+// driver (a restart; this is the only process that drives) and is closed
+// once it has been quiet for two minutes — the margin is for a record
+// written a beat before its driver registered, not a judgement about pace.
+const ABANDONED_AFTER_MS = 2 * 60 * 1000;
+/** The most recent moment a run showed any sign of life. */
+function lastActivity(run) {
+    let latest = Date.parse(run.startedAt);
+    for (const step of run.steps) {
+        for (const event of step.events) {
+            const t = Date.parse(event.t);
+            if (t > latest)
+                latest = t;
+        }
+    }
+    return latest;
+}
+/**
+ * Close out runs abandoned by a process that is no longer here.
+ *
+ * Runs execute in the server process, and nothing writes a terminal status
+ * when that process goes away — so a deploy, a crash or a Ctrl-C during a run
+ * leaves `status: "running"` on disk forever. The run history then contains
+ * entries that are not merely stale but false: they claim to be in progress,
+ * the dashboard renders them as live, and no one can tell them apart from a
+ * step that is genuinely still thinking.
+ *
+ * Called at startup, before anything reads run history. A run still being
+ * worked on by a live process is protected by the idle window, not by a lock —
+ * so this is safe to call while runs are in flight, and deliberately
+ * conservative about what it declares dead.
+ *
+ * A run genuinely waiting for a person is left alone: that state legitimately
+ * outlives any process. A run whose person already answered is not waiting,
+ * and is picked back up — see below.
+ */
+export function reconcileRuns(tenant, now = Date.now()) {
+    const closed = [];
+    for (const workspace of listWorkspaces(tenant)) {
+        for (const summary of listRuns(tenant, workspace.name)) {
+            if (drivingRuns.has(summary.id))
+                continue;
+            if (now - lastActivity(summary) < ABANDONED_AFTER_MS)
+                continue;
+            // Approved, then abandoned. Approval only writes to the run record; the
+            // loop that acts on it polls in memory, inside the process that started
+            // the run. If that process goes away between the click and the next
+            // poll, the decision is on disk with nobody left to read it — and the
+            // run sits in `awaiting-approval` with no step awaiting approval, so
+            // the dashboard cannot even offer the button again. Nothing else here
+            // rescues it: this status is exempt from being closed, by design.
+            if (summary.status === "awaiting-approval") {
+                const stillAsking = summary.steps.some((s) => s.status === "awaiting-approval");
+                const answered = summary.steps.some((s) => s.approvedAt && s.status === "pending");
+                if (stillAsking || !answered)
+                    continue;
+                const run = readRun(tenant, workspace.name, summary.id);
+                if (!run || run.status !== "awaiting-approval")
+                    continue;
+                run.status = "running";
+                writeRun(tenant, workspace.name, run);
+                // Park at any *later* gate rather than poll: reconcile runs inside
+                // long-lived server processes, where a 24h file-poll is exactly the
+                // slot-burning the queue exists to avoid.
+                void driveRun(tenant, workspace.name, run, null, run.tags ?? [], { parkOnApproval: true });
+                closed.push({
+                    runId: run.id,
+                    tenant,
+                    workspace: workspace.name,
+                    action: "resumed",
+                    interrupted: [],
+                });
+                continue;
+            }
+            if (summary.status !== "running")
+                continue;
+            const run = readRun(tenant, workspace.name, summary.id);
+            if (!run || run.status !== "running")
+                continue;
+            const interrupted = [];
+            for (const step of run.steps) {
+                if (step.status === "running") {
+                    interrupted.push(step.agent);
+                    step.status = "failed";
+                    step.events.push({
+                        t: new Date(now).toISOString(),
+                        type: "error",
+                        text: "interrupted — the process running this step went away before it finished",
+                    });
+                }
+                else if (step.status === "pending") {
+                    step.status = "skipped";
+                    step.skipReason = "the run was interrupted before this step started";
+                }
+            }
+            run.status = "failed";
+            run.finishedAt = new Date(now).toISOString();
+            writeRun(tenant, workspace.name, run);
+            // The record is closed; make the sandbox match. A step with no
+            // `timeout:` has no pod deadline, so an orphan from a mid-step restart
+            // is reaped here, by the run that owned it, not by a clock.
+            try {
+                if (process.env.FOLDRUN_RUN_ISOLATION === "container")
+                    killRunSandboxes(run.id);
+                else
+                    platform.killRunSandboxes(run.id);
+            }
+            catch {
+                // a sandbox we cannot reach must not stop the reconcile
+            }
+            closed.push({ runId: run.id, tenant, workspace: workspace.name, action: "closed", interrupted });
+        }
+    }
+    return closed;
+}
+/**
+ * The same, for every account this installation holds.
+ *
+ * A server reconciles on boot, and it boots for everyone — reconciling only
+ * one hard-coded account left every other account's interrupted runs marked
+ * `running` forever, with no process left to finish them.
+ */
+export function reconcileAllRuns(now = Date.now()) {
+    return listTenants().flatMap((tenant) => reconcileRuns(tenant, now));
+}
+/**
+ * Wait for a run to stop being in progress.
+ *
+ * Runs start and return immediately, which is right for a schedule and wrong
+ * for a caller putting an agent behind their own request: they want the
+ * answer, not a receipt. Polls the run record rather than holding a callback,
+ * so it works from a different process than the one doing the work.
+ *
+ * `awaiting-approval` counts as stopping. It is not finished, but it is not
+ * going to progress without a person, and a caller blocked on it would hang
+ * for as long as the approval window allows.
+ */
+export async function waitForRun(tenant, workspace, runId, timeoutMs = 5 * 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const run = readRun(tenant, workspace, runId);
+        if (!run)
+            return { run: null, timedOut: false };
+        // Queued counts as in flight — a caller asking to wait wants the result,
+        // not a report that the worker hadn't picked the job up yet.
+        if (run.status !== "running" && run.status !== "queued")
+            return { run, timedOut: false };
+        if (Date.now() >= deadline)
+            return { run, timedOut: true };
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+/**
+ * What a run produced, for a caller that wanted an answer.
+ *
+ * The last step that actually returned something: a flow's final step is the
+ * conclusion, and skipping back past steps that were skipped or produced
+ * nothing is what makes `?wait=true` useful rather than merely blocking.
+ */
+export function runResult(run) {
+    for (let i = run.steps.length - 1; i >= 0; i--) {
+        const r = run.steps[i].result;
+        if (r && r.trim())
+            return r;
+    }
+    return null;
+}