@foldrun/core 0.2.0

package/src/runner.ts

@@ -0,0 +1,3446 @@
+// 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 { spawn } from "node:child_process";
+import { executeStep, extractJson, stepCeiling, type EventExtra } from "./step-exec.ts";
+import { eventUrl } from "./webhook.ts";
+import { runStepInContainer, sizeLimits, killRunSandboxes, type StepTiming } from "./run-container.ts";
+import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute, type EgressGrant } from "./egress.ts";
+import { platform } from "./platform.ts";
+
+/** 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.ts";
+import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError } from "./tool-names.ts";
+import { refNames } from "./refs.ts";
+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,
+  type FlowStep,
+  type McpSpec,
+  type RunRecord,
+  type StepRecord,
+  STORAGE_DIR,
+  adoptLegacyVersionKey,
+  runCost,
+} from "./store.ts";
+import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, type Catalog } from "./catalog.ts";
+import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.ts";
+import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
+import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
+import { attachOperations, prefetchOpenApi } from "./openapi.ts";
+import { buildSearchTools, buildHistoryTools, buildDeskTools, digestRuns, type SearchRoot, type RunDigest } from "./context-tools.ts";
+import { startTranslator, translatorSpecFor, type TranslatorSpec } from "./translator.ts";
+import { providerPreset } from "./providers.ts";
+import { buildScriptTools, parseScripts, type ExecutionContext } from "./script-tools.ts";
+import { libraryDir, libraryTools, libraryMemoryIndex } from "./library.ts";
+import { mergeRuntimes, parseRuntime, prepareRuntime, type RuntimeSpec } from "./runtime.ts";
+import { materializeFiles, harvestFiles } from "./storage.ts";
+import { chooseExecutor, ensureImage } from "./container.ts";
+import { stampBundle } from "./okf.ts";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+
+// 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: McpSpec, tenant: string, workspace: string): McpServerConfig {
+  const fill = (values: Record<string, string>) => {
+    const out: Record<string, string> = {};
+    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: (string | null)[], gi: number, cap = CONTEXT_CHARS): string | null {
+  const parts: string[] = [];
+  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");
+}
+
+export interface DiscoveredSkill {
+  name: string;
+  description: string;
+  /** Tags that must be present on the run for this skill to load. A skill
+   *  with none always loads. Mirrors "apply when this check failed". */
+  when: string[];
+  /** Path to SKILL.md (or the flat .md), relative to the agent directory. */
+  path: string;
+  /** Skill folder relative to the agent directory, or null for flat skills. */
+  dir: string | null;
+  hasScripts: boolean;
+  /** The rest of the Agent Skills layout: references/ and assets/. */
+  hasReferences: boolean;
+  hasAssets: boolean;
+}
+
+const toTags = (v: unknown): string[] =>
+  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: string): { data: Record<string, unknown> } {
+  // 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 as unknown as { clearCache: () => void }).clearCache();
+  try {
+    return matter(raw) as { data: Record<string, unknown> };
+  } 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: string, v: string) => `${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)) as { data: Record<string, unknown> };
+      } 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: string, subdir = "skills"): DiscoveredSkill[] {
+  const skillsDir = path.join(agentDir, subdir);
+  if (!fs.existsSync(skillsDir)) return [];
+  const out: DiscoveredSkill[] = [];
+
+  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: string): { data: Record<string, unknown>; body: string } | null {
+  // 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 as Record<string, unknown>, body: parsed.content.trim() };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+const workspaceRootOf = (agentDir: string) => 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: string, tenant: string): Record<string, unknown> {
+  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: Record<string, unknown>): string {
+  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: string, now = new Date()): string {
+  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: string, tenant: string): string | null {
+  const sections = [
+    ["Everyone in this account", readAgentsMd(accountDir(tenant))?.body],
+    ["Everyone in this workspace", readAgentsMd(workspaceRootOf(agentDir))?.body],
+  ].filter(([, body]) => body) as [string, string][];
+  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<T extends { name: string; when: string[] }>(
+  skills: T[],
+  only: string[],
+  tags: string[],
+): T[] {
+  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: string | null, until: string): boolean {
+  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: string, workspaceRoot: string): string {
+  if (!text.includes("[[")) return text;
+  const map = new Map<string, string>();
+  const norm = (v: string) =>
+    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"] as const) {
+    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 as Record<string, unknown>;
+        // `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"] as const) {
+          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",
+      ),
+    ) as { files?: { path: string }[] };
+    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: string) => {
+    const hit = map.get(norm(name.trim()));
+    return hit ? `\`${hit}\`` : whole;
+  });
+}
+
+function agentContext(
+  agentDir: string,
+  tenant: string,
+  tags: string[] = [],
+  /** Who is running, so scripts can stamp what they write with its provenance. */
+  identity: { runId?: string; agent?: string } = {},
+) {
+  // 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: DiscoveredSkill[] = [];
+  const seenSkills = new Set<string>();
+  const addSkills = (dir: string, prefix: string, 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: string[] = 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: string, prefix: string) => {
+    if (!fs.existsSync(dir)) return [];
+    const out: string[] = [];
+    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: string[] = [];
+  // 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: Record<string, McpServerConfig> = {};
+  const mcpNames: string[] = [];
+
+  // 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: RuntimeSpec[] = [];
+  const grantOwnTool = (name: string) => {
+    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 as { runtime?: unknown }).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 as Record<string, unknown>)) {
+      const def = parseToolDef({ ...(raw as object), 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: string[] = 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: "small" | "large" | "heavy" =
+    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 as Record<string, unknown> | undefined) ?? workspaceFrontmatter(agentDir, tenant).provider;
+  let providerEnv: Record<string, string> = {};
+  let providerLabel: string | null = 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: Record<string, string> = {};
+  const providerWarnings: string[] = [];
+  // 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: Record<string, string> | null = 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: TranslatorSpec | null = null;
+  let fallbackTranslator: TranslatorSpec | null = null;
+  const spec = parseProvider(providerBlock);
+  if (spec) {
+    providerWarnings.push(...spec.warnings);
+    const substitute = (text: string) =>
+      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: string[] = [];
+  let runtimeError: string | null = null;
+  let exec: ExecutionContext | null = null;
+  let runtime = { interpreters: {} as Record<string, string>, env: {} as Record<string, string>, log: [] as string[], error: null as string | 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: string[] = [];
+  const disabled: string[] = [];
+  const unknownTools: string[] = [];
+  const shadowed: string[] = [];
+  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: SearchRoot[] = 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: RunDigest[] = 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: RunDigest[] = 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: string[] = 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: string,
+  workspace: string,
+  push: (type: "info" | "error", text: string) => void,
+) {
+  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: Catalog | null,
+  model: string,
+  usage: { inputTokens: number; outputTokens: number } | null,
+  sdkCost: number | null,
+  push: (type: "info" | "error", text: string) => void,
+): number | null {
+  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: string,
+  tenant: string,
+  step: StepRecord,
+  context: string | null,
+  save: () => void,
+  modelOverride?: string | null,
+  tags: string[] = [],
+  effortOverride?: string | null,
+  runId?: string,
+  /** What the previous group returned as DATA (an `output: json` step's
+   *  value), beside the prose in `context`. Undefined when nothing did. */
+  priorData?: unknown,
+  /** 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: number | null = 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: [string, string][] = [];
+  let fileDir: string | null = null;
+  const redact = (text: string) => {
+    let out = text;
+    for (const [value, name] of redactions) out = out.split(value).join(`[redacted:${name}]`);
+    return out;
+  };
+
+  const push = (type: StepRecord["events"][number]["type"], text: string, extra?: EventExtra) => {
+    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] as [string, string])
+      // 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: Catalog | null = null;
+    let tokenPrice: { input: number; output: number } | null = 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: Record<string, string | undefined> =
+      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: typeof push = (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: EgressGrant = { 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: Record<string, string> = 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 = <T extends Record<string, string | undefined>>(env: T, name: string): T =>
+        lease ? (proxyModelEnv(env, lease.url, grant, providerSecrets, name) as T) : env;
+      const proxiedTranslator = (spec: TranslatorSpec | null, name: string): TranslatorSpec | null => {
+        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: Record<string, string | undefined>, 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): entry is [string, string] => 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): entry is [string, string] => 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: number | null) => (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: number) => 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: Record<string, string | undefined>) => 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: Record<string, string | undefined>, spec: TranslatorSpec | null) => {
+        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: string,
+  workspace: string,
+  runId: string,
+  indexes: number[],
+): Promise<boolean> {
+  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: string, to: string) {
+  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: string, tenant: string): string[] {
+  const out = new Set<string>();
+  try {
+    const { data } = matter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
+    const front = data as { apis?: unknown; tools?: unknown };
+    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(): Record<string, string> | null {
+  const base = process.env.FOLDRUN_FALLBACK_BASE_URL;
+  const token = process.env.FOLDRUN_FALLBACK_TOKEN;
+  if (!base || !token) return null;
+  const out: Record<string, string> = {
+    ANTHROPIC_BASE_URL: base,
+    ANTHROPIC_AUTH_TOKEN: token,
+    ANTHROPIC_API_KEY: "",
+    CLAUDE_CODE_OAUTH_TOKEN: "",
+  };
+  for (const tier of ["HAIKU", "SONNET", "OPUS"] as const) {
+    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: string): boolean {
+  // 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: string): boolean {
+  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: number) => new Promise<void>((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<T extends { timing?: StepTiming | null }>(outcome: T, earlier: StepTiming | null | undefined): T {
+  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: number, text = "", random: () => number = Math.random): number {
+  // 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(): Record<string, string | undefined> {
+  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: unknown, step: StepRecord, take: number): string[] {
+  let list: unknown[] | null = Array.isArray(data) ? data : null;
+  if (!list && data && typeof data === "object") {
+    const arrays = Object.entries(data as Record<string, unknown>).filter(([, v]) => Array.isArray(v));
+    if (arrays.length === 1) list = arrays[0][1] as unknown[];
+    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: string, step: StepRecord, take: number): string[] {
+  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: string;
+  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: string[] = [];
+  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: string,
+  workspace: string,
+  steps: FlowStep[],
+  flowName: string,
+  status: "queued" | "running",
+  tags: string[] = [],
+): RunRecord {
+  const run: RunRecord = {
+    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: string,
+  workspace: string,
+  steps: FlowStep[],
+  flowName: string,
+  modelOverride?: string | null,
+  tags: string[] = [],
+  effortOverride?: string | null,
+): RunRecord {
+  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: string, patterns: string[], cap = 12): string[] {
+  const out = new Set<string>();
+  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: string, rel: string) => {
+      let entries: fs.Dirent[];
+      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: RunRecord, disk: RunRecord | null): boolean {
+  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: string, workspace: string, run: RunRecord): Promise<void> {
+  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<string>();
+
+export function driveRun(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  modelOverride?: string | null,
+  tags: string[] = [],
+  opts: { parkOnApproval?: boolean; effortOverride?: string | null } = {},
+): Promise<void> {
+  drivingRuns.add(run.id);
+  return driveRunInner(tenant, workspace, run, modelOverride, tags, opts).finally(() => {
+    drivingRuns.delete(run.id);
+  });
+}
+
+function driveRunInner(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  modelOverride: string | null | undefined,
+  tags: string[],
+  opts: { parkOnApproval?: boolean; effortOverride?: string | null },
+): Promise<void> {
+  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: { dir: string; agent: string | null }[] = [
+      // 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: string[] = [];
+    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<number, StepRecord[]>();
+        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: (string | null)[] = [];
+      const groupConclusions: (string | null)[] = [];
+      // 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: number) => 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: unknown[] = [];
+      const dataBefore = (gi: number): unknown => {
+        for (let i = gi - 1; i >= 0; i--) if (groupData[i] !== undefined) return groupData[i];
+        return undefined;
+      };
+      const dataOf = (group: StepRecord[]): unknown => {
+        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: StepRecord[]): string | null => {
+        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: StepRecord[]): string | null => {
+        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: string | null = null;
+      let ctxData: unknown = 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: StepRecord[] = 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: StepRecord | null = 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: string = 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: StepRecord = {
+            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: string = 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: StepRecord[] = [];
+          const seenAgents = new Set<string>();
+          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: string, workspace: string, flowName: string) {
+  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: string,
+  workspace: string,
+  steps: FlowStep[],
+  seen: string[] = [],
+  depth = 0,
+): FlowStep[] {
+  if (depth > 3) throw new Error("flow nesting too deep (max 3)");
+  const out: FlowStep[] = [];
+  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: string, workspace: string, flowName: string) {
+  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: RunRecord): number {
+  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;
+}
+
+export interface Reconciliation {
+  runId: string;
+  tenant: string;
+  workspace: string;
+  /** What was done about it: closed as dead, or picked back up. */
+  action: "closed" | "resumed";
+  /** Steps that were mid-flight when the process went away. */
+  interrupted: string[];
+}
+
+/**
+ * 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: string, now = Date.now()): Reconciliation[] {
+  const closed: Reconciliation[] = [];
+
+  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: string[] = [];
+      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()): Reconciliation[] {
+  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: string,
+  workspace: string,
+  runId: string,
+  timeoutMs = 5 * 60_000,
+): Promise<{ run: RunRecord | null; timedOut: boolean }> {
+  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: RunRecord): string | null {
+  for (let i = run.steps.length - 1; i >= 0; i--) {
+    const r = run.steps[i].result;
+    if (r && r.trim()) return r;
+  }
+  return null;
+}