@foldrun/core 2.4.0 → 2.6.0

package/src/runner.ts

@@ -3,11 +3,14 @@
 // fail without failing the flow. A direct agent run is a one-step ad-hoc
 // flow, so there is a single execution path.
 
+import { latestRevisionId } from "./history.ts";
+import { recordCallIo, redactionsFor } from "./capture.ts";
+import { AUTH_REFUSAL } from "./issues.ts";
 import { hookNames } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "gray-matter";
+import matter, { parseLenient, configMatter } from "./matter.ts";
 import { spawn } from "node:child_process";
 import {
   knownPrice, executeStep, extractJson, stepCeiling, stepCeilingFor, type EventExtra } from "./step-exec.ts";
@@ -17,7 +20,8 @@ import { browserPodLine, podLossDecision, RERAN_ON_FULL } from "./browser-pod.ts
 import { eventUrl } from "./webhook.ts";
 import { runStepInContainer, sizeLimits, killRunSandboxes, type StepTiming } from "./run-container.ts";
 import { hostSafeEnv, platformApiUrl } from "./host-env.ts";
-import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken } from "./model-credential.ts";
+import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken, isModelEnvName, DECLARED_ENV_PREFIX } from "./model-credential.ts";
+import { parseJudge } from "./judge-verdict.ts";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.ts";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute, type EgressGrant } from "./egress.ts";
 import { explainRefusal, isRefusalStatus, refusalFromLine, supplyNote, type SupplyState } from "./refusal.ts";
@@ -33,7 +37,7 @@ const isolatedRun = () => {
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.ts";
 import { DELEGATE_TOOL, gatherSubagents, subagentPrompt, subagentTools, type SubagentSpec } from "./subagents.ts";
-import { ASK_TOOL, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool } from "./operator.ts";
+import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool, buildPeerTools, inboxReader, localPeerBus, peersPromptLine, type PeerInfo } from "./operator.ts";
 import { sendPlainNotification } from "./notify.ts";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
@@ -67,6 +71,7 @@ import {
   checkFormatVersion,
   readRun,
   writeRun,
+  isRescueRecord,
   runSummary,
   verdictOf,
   type FlowStep,
@@ -83,9 +88,10 @@ import {
   runCost,
 } from "./store.ts";
 import { canReadBack } from "./tool-output.ts";
+import { PromptLayers, promptCacheKey } from "./prompt-layers.ts";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf, type Catalog, type TokenPrice } from "./catalog.ts";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.ts";
-import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
+import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
 import { attachOperations, prefetchOpenApi } from "./openapi.ts";
@@ -210,6 +216,101 @@ export function slotPool(size: number): { acquire: () => Promise<void>; release:
   };
 }
 
+/** Steps whose model has begun its first response — the step's executor
+ *  says so the moment the stream starts (EventExtra.responding). Memory
+ *  only: it is scheduling, not something the run record needs. */
+const respondingSteps = new WeakSet<StepRecord>();
+export function markResponding(step: StepRecord): void {
+  respondingSteps.add(step);
+}
+
+/**
+ * Is this step's prompt in the cache yet? An entry is readable from the
+ * moment the response to the request that wrote it begins streaming
+ * (Anthropic's prompt-caching docs), which is what `responding` marks.
+ * The first text, tool call or recorded model call says the same a little
+ * later, for an executor that cannot see the stream (the stub, an older
+ * driver). Resolves on the first of those, or when the step is over
+ * without one (a refusal before the first turn, a failed start).
+ */
+export function untilFirstReply(step: StepRecord, done: Promise<unknown>, pollMs = 250): Promise<void> {
+  const replied = () =>
+    respondingSteps.has(step) || step.events.some((e) => e.type === "text" || e.type === "tool") || (step.calls?.length ?? 0) > 0;
+  return new Promise<void>((resolve) => {
+    let finished = false;
+    const stop = () => {
+      finished = true;
+      resolve();
+    };
+    done.then(stop, stop);
+    const tick = () => {
+      if (finished) return;
+      if (replied()) return stop();
+      setTimeout(tick, pollMs).unref?.();
+    };
+    tick();
+  });
+}
+
+/**
+ * Steps of one agent launched together share a prompt prefix — tools and
+ * system prompt — and that is what the model's cache keeps. The cache is
+ * written by the first request that carries a prefix and readable only
+ * once that response has begun, so N copies started at once all write it
+ * and none reads: a fan-out of twenty paid twenty cold prefixes. The gate
+ * lets the first instance of each agent go alone and holds its siblings
+ * until its first response has begun (or it ended); then they all start
+ * and read what it wrote — Claude Code holds a workflow's fan-out the same
+ * way. Not a fixed delay: a sandbox takes seconds to start before its
+ * first model call, so a timer from launch would release the siblings
+ * before there was anything to read. Keyed by agent and model, since a
+ * cache is per model.
+ */
+export function warmGate(launching: StepRecord[], pollMs = 250) {
+  const key = (s: StepRecord) => `${s.agent}\u0000${s.model ?? ""}`;
+  const counts = new Map<string, number>();
+  for (const s of launching) counts.set(key(s), (counts.get(key(s)) ?? 0) + 1);
+  const leads = new Map<string, { opened: Promise<void>; open: () => void }>();
+  const isLead = new WeakSet<StepRecord>();
+  return {
+    /** Claim the step's place — synchronously, before anything awaits, or
+     *  the copies that reach their first await together would all find no
+     *  lead and all go (a `parallel:` pool's acquire was exactly that).
+     *  The first of its agent leads and gets null; a later one gets the
+     *  lead's gate to await before it starts; a lone step gets null too. */
+    claim(step: StepRecord): Promise<void> | null {
+      const k = key(step);
+      if ((counts.get(k) ?? 0) < 2) return null;
+      const lead = leads.get(k);
+      if (lead) return lead.opened;
+      let open!: () => void;
+      const opened = new Promise<void>((r) => (open = r));
+      leads.set(k, { opened, open });
+      isLead.add(step);
+      return null;
+    },
+    /** A lead that will not run after all (the run was stopped while it
+     *  waited for a pool slot) still opens its gate — or its siblings,
+     *  which also wake to the stop, would wait on it forever. */
+    release(step: StepRecord): void {
+      if (isLead.has(step)) leads.get(key(step))!.open();
+    },
+    /** Run the step; a lead opens its agent's gate on its first reply (or
+     *  its end), whatever else happens to it. */
+    async run(step: StepRecord, launch: () => Promise<void>): Promise<void> {
+      if (!isLead.has(step)) return launch();
+      const { open } = leads.get(key(step))!;
+      const done = launch();
+      try {
+        await untilFirstReply(step, done, pollMs);
+      } finally {
+        open();
+      }
+      await done;
+    },
+  };
+}
+
 export interface DiscoveredSkill {
   name: string;
   description: string;
@@ -235,32 +336,10 @@ const toTags = (v: unknown): string[] =>
 // 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: {} };
-  }
+  // gray-matter caches a *failed* parse as a hollow success; ./matter.ts
+  // parses every call, so the strict read throws every time and the lenient
+  // one (shared with check, which warns about it) fires every time.
+  return { data: parseLenient(raw).data };
 }
 
 // Both layouts: <root>/<name>/SKILL.md (Agent Skills standard) and the flat
@@ -356,7 +435,7 @@ export function readAgentsMd(dir: string): { data: Record<string, unknown>; body
     const file = path.join(dir, name);
     if (!fs.existsSync(file)) continue;
     try {
-      const parsed = matter(fs.readFileSync(file, "utf8"));
+      const parsed = configMatter(fs.readFileSync(file, "utf8"));
       return { data: parsed.data as Record<string, unknown>, body: withoutAgentRules(parsed.content).trim() };
     } catch {
       return null;
@@ -427,6 +506,10 @@ export function workspaceRuntimePlan(
   return [...byFp.values()];
 }
 
+/** The most tool content one step records (FOL-54 step 4): about 60 calls
+ *  at the per-part cap; past it, metadata only. */
+const STEP_CAPTURE_LIMIT = 4_000_000;
+
 function workspaceFrontmatter(agentDir: string, tenant: string): Record<string, unknown> {
   return {
     ...(readAgentsMd(accountDir(tenant))?.data ?? {}),
@@ -755,10 +838,14 @@ export function agentContext(
   // 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(
+  const { data: front, content: body } = configMatter(
     fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"),
   );
-  const parts = [resolveDocLinks(body.trim(), path.resolve(agentDir, "..", ".."))];
+  // The prompt's sections, by name and by how often they change. Added in
+  // the order they are computed; assembled stable first, so the model's
+  // cache keeps the agent's half across steps and runs (prompt-layers.ts).
+  const parts = new PromptLayers();
+  parts.add("persona", 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
@@ -780,14 +867,14 @@ export function agentContext(
   const languageSet = language.from !== "default" && language.from !== "env";
   const regionSet = region.from !== "none" && region.from !== "env" && region.from !== "language";
   if (languageSet || regionSet) {
-    parts.push(
+    parts.add("locale",
       `# Locale\n\n${localeProse(locale, languageName(language.language), regionName(region.region))} ` +
         `Write in ${languageName(language.language)} unless the step you are given says otherwise; ` +
         `use these currency, units and calendar conventions in anything you produce. ` +
         `Your tools already know: a search asks in it and for this country, the browser reports it, a fetch requests it.`,
     );
   }
-  parts.push(
+  parts.add("where",
     `# 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 — ` +
@@ -832,7 +919,7 @@ export function agentContext(
   // 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);
+  if (sharedContext) parts.add("agents.md", sharedContext);
 
   // Skills follow the open Agent Skills format (agentskills.io): a folder
   // with SKILL.md, optionally bundling its own scripts/ and references/. The
@@ -871,7 +958,7 @@ export function agentContext(
         (bundles.length ? ` (also bundles ${bundles.join(", ")})` : "")
       );
     });
-    parts.push(
+    parts.add("skills",
       `# 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.)` : ""),
@@ -893,11 +980,13 @@ export function agentContext(
       : "";
     const projectMem = workspaceMemoryIndex(tenant, workspace);
     const shared = libraryMemoryIndex(tenant);
-    parts.push(
+    // Dynamic: agents write memory, so the index moves between runs.
+    parts.add("memory",
       `# 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,
+      { dynamic: true },
     );
   }
 
@@ -914,7 +1003,7 @@ export function agentContext(
       projectKnowledge && `Shared across this workspace:\n\n${projectKnowledge}`,
       sharedKnowledge && `Shared across every workspace:\n\n${sharedKnowledge}`,
     ].filter(Boolean);
-    parts.push(
+    parts.add("knowledge",
       `# 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` +
@@ -947,7 +1036,7 @@ export function agentContext(
       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(
+    parts.add("scripts",
       `# 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.`,
@@ -965,7 +1054,8 @@ export function agentContext(
   // file to size it against, not before.
   const state = listDir(path.join(agentDir, "..", "..", "state"), "workspace/state/");
   if (state.length) {
-    parts.push(
+    // Dynamic: runs add and remove state files.
+    parts.add("state",
       `# 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 ` +
@@ -975,6 +1065,7 @@ export function agentContext(
         `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.`,
+      { dynamic: true },
     );
   }
 
@@ -1057,7 +1148,7 @@ export function agentContext(
   const keepIn = { dir: agentDir, readable: () => readsFiles };
   const apiTools = buildApiTools(tenant, apis, workspace, undefined, keepIn);
   if (apiTools.promptLines.length) {
-    parts.push(`# APIs you can call\n\n${apiTools.promptLines.join("\n")}`);
+    parts.add("apis", `# APIs you can call\n\n${apiTools.promptLines.join("\n")}`);
   }
 
   // Secrets an agent declared become env vars for its scripts and bash.
@@ -1214,6 +1305,10 @@ export function agentContext(
         name: spec.name,
         maxTokensParam: preset?.maxTokensParam,
         reasoningEffort: preset?.reasoningEffort,
+        // The agent's prompts share an opening; the key says so to an
+        // endpoint that routes its cache by one. Only where the preset
+        // says the parameter is understood — elsewhere it is a 400.
+        cacheKey: preset?.promptCacheKey ? promptCacheKey(tenant, workspace, path.basename(agentDir)) : undefined,
       });
       // What the run is actually pointed at, in one line: the endpoint, the
       // tiers this gateway renames, and whether the credential landed.
@@ -1404,12 +1499,15 @@ export function agentContext(
     exec,
     keepIn.readable,
   );
-  parts.push(
+  // Dynamic: the date moves daily, and would otherwise invalidate every
+  // layer behind it once a day.
+  parts.add("clock",
     `# 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.`,
+    { dynamic: true },
   );
   if (scriptTools.promptLines.length) {
-    parts.push(
+    parts.add("script-tools",
       `# Tools from scripts\n\nCall these directly — they run workspace scripts for you. Each is called by its full name, ` +
         `\`mcp__foldrun_scripts__<name>\` (\`web\` is \`mcp__foldrun_scripts__web\`); a bare name is refused:\n\n${scriptTools.promptLines.join("\n")}`,
     );
@@ -1420,20 +1518,20 @@ export function agentContext(
   // reddit-desk validator step on 6 Oct 2026. Say it before the first call.
   if (builtins.length) {
     const named = builtins.map((b) => b.split("="));
-    parts.push(
+    parts.add("web",
       `# Web search and fetch on this run\n\n` +
         named.map(([action, tool]) => `- To ${action}, call **${tool}** directly. \`web\` with action=${action} is switched off on this run.`).join("\n") +
         `\n\nThe web tool's other actions work as usual.`,
     );
   }
   if (declared.length) {
-    parts.push(
+    parts.add("secrets",
       `# Secrets\n\nAvailable to your scripts as environment variables: ${declared.join(", ")}. ` +
         `Never print, echo, or write them to a file.`,
     );
   }
 
-  parts.push(
+  parts.add("rules",
     "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 (workspace/storage/ and the older ../../storage/ are the same place). There is no /tmp for you: a " +
@@ -1453,7 +1551,7 @@ export function agentContext(
   // 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(
+  parts.add("rules",
     "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.",
@@ -1500,6 +1598,7 @@ export function agentContext(
   let wantHistory = false;
   let wantDesks = false;
   let wantAsk = false;
+  let wantPeers = false;
 
   for (const ref of toolRefs(front)) {
     const toolName = ref.name;
@@ -1532,12 +1631,13 @@ export function agentContext(
     } else if (TOOL_MAP[toolName]) {
       allowed.push(...TOOL_MAP[toolName]);
       if (available[toolName]) shadowed.push(toolName);
-    } else if (toolName === "search" || toolName === "history" || toolName === "desks" || toolName === "ask") {
+    } else if (toolName === "search" || toolName === "history" || toolName === "desks" || toolName === "ask" || toolName === "peers") {
       // 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 if (toolName === "ask") wantAsk = true;
+      else if (toolName === "peers") wantPeers = true;
       else wantDesks = true;
       if (available[toolName]) shadowed.push(toolName);
     } else if (toolName === "install") {
@@ -1593,10 +1693,16 @@ export function agentContext(
   const ask = wantAsk ? { timeoutSec: askTimeoutSec(front) } : null;
   if (ask) {
     allowed.push(ASK_TOOL);
-    parts.push(`# Asking a person\n\n${askPromptLine(ask.timeoutSec)}`);
+    parts.add("ask", `# Asking a person\n\n${askPromptLine(ask.timeoutSec)}`);
   }
+  // tools: [peers] — peers_list and peers_message, to the other steps of
+  // this step's parallel group. Who they are is known only when the group
+  // launches, so the grant is here and the roster, the server and the
+  // prompt's line are the step's (runStep).
+  const peers = wantPeers;
+  if (peers) allowed.push(...PEER_TOOLS);
   if (searchTools.promptLines.length || historyTools.promptLines.length || deskTools.promptLines.length) {
-    parts.push(`# Finding things\n\n${[...searchTools.promptLines, ...historyTools.promptLines, ...deskTools.promptLines].join("\n")}`);
+    parts.add("finding", `# 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
@@ -1618,6 +1724,7 @@ export function agentContext(
   if (denied.includes("install")) denied.push(INSTALL_TOOL);
   const finalAllowed = allowed.filter((t) => !denied.includes(t));
   readsFiles = canReadBack(finalAllowed);
+  const prompt = parts.assemble();
 
   return {
     front,
@@ -1625,7 +1732,9 @@ export function agentContext(
     /** The zone, where it came from, and anything unreadable on the way —
      *  reported by the step, not here, so it lands in the run's trace. */
     clock,
-    systemPrompt: parts.join("\n\n"),
+    systemPrompt: prompt.text,
+    /** What the record keeps of each layer of that prompt. */
+    promptLayers: prompt.layers,
     allowed: finalAllowed,
     disabled,
     unknownTools,
@@ -1649,6 +1758,7 @@ export function agentContext(
     historyTools,
     deskTools,
     ask,
+    peers,
     // `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
@@ -1906,6 +2016,12 @@ async function runStep(
    *  person's message to this step reaches this step's own inbox and not a
    *  sibling's running in the same group. Undefined outside a flow. */
   stepIndex?: number,
+  /** The other steps launched with this one (its parallel group), for
+   *  tools: [peers]. Empty when it runs alone. */
+  siblings: PeerInfo[] = [],
+  /** The in-process colleagues' bus for this group (localPeerBus), when
+   *  the step runs in this process rather than a pod. */
+  peerBus?: ReturnType<typeof localPeerBus>,
 ) {
   // Secret values are injected into scripts as environment variables and
   // substituted into API headers, so a model that reads one back — from a
@@ -1952,9 +2068,63 @@ async function runStep(
     }
   };
 
+  // What this workspace records of each step (FOL-54 step 4): `capture:` in
+  // AGENTS.md — every model call always; each tool call's input and output
+  // unless it says `metadata`.
+  const capture: "metadata" | "full" = workspaceFrontmatter(agentDir, tenant).capture === "metadata" ? "metadata" : "full";
+  // `judge:` (AGENTS.md): the model and effort every `verify: judge:` here
+  // grades with — field by field, the workspace's else the account's.
+  const { judgeModel, judgeEffort } = (() => {
+    const ws = parseJudge(readAgentsMd(workspaceRootOf(agentDir))?.data?.judge);
+    const account = parseJudge(readAgentsMd(accountDir(tenant))?.data?.judge);
+    const model = ws.model ?? account.model;
+    const effort = resolveEffort(ws.effort ?? account.effort ?? "");
+    return { judgeModel: model ? resolveModel(model) : undefined, judgeEffort: effort ?? undefined };
+  })();
+  // A step that pours out content stops being recorded past this — its
+  // calls keep their names, sizes and times (FOL-54 step 4).
+  let capturedChars = 0;
+  let captureFull = false;
   const push = (type: StepRecord["events"][number]["type"], text: string, extra?: EventExtra) => {
     const t = new Date().toISOString();
-    step.events.push({ t, type, text: redact(text), ...extra });
+    // The model has begun its first response: held only in memory, for
+    // the fan-out gate (warmGate). Not a line in the trace.
+    if (extra?.responding) {
+      markResponding(step);
+      return;
+    }
+    // A model call is a span on the step, not a line in its trace.
+    // Numbered here, across attempts: a retry's calls follow the first
+    // attempt's, and an id-less turn of one attempt never overwrites
+    // another's. No save of its own — a turn's blocks arrive as several
+    // messages, and the next event saves them all.
+    if (extra?.turn) {
+      const calls = (step.calls ??= []);
+      // The loop counts attempts from 1; a call of the first carries none.
+      const attempt = Math.max(1, step.attempts ?? 1);
+      const at = calls.findIndex((c) => c.id === extra.turn!.id && (c.attempt ?? 1) === attempt);
+      const call = { ...extra.turn, n: at >= 0 ? calls[at]!.n : calls.length + 1, ...(attempt > 1 ? { attempt } : {}) };
+      if (at >= 0) calls[at] = call;
+      else calls.push(call);
+      return;
+    }
+    // A tool call's content goes beside the run, masked (capture.ts), and the
+    // event keeps only that it was recorded.
+    let rest: EventExtra | undefined = extra;
+    if (extra?.io) {
+      const { io, ...others } = extra;
+      rest = others;
+      const size = (io.input?.length ?? 0) + (io.output?.length ?? 0);
+      if (runId && extra.call && capture === "full" && capturedChars + size > STEP_CAPTURE_LIMIT && !captureFull) {
+        captureFull = true;
+        step.events.push({ t, type: "info", text: `capture: this step recorded ${Math.round(capturedChars / 1000)}k characters of tool content — the rest of its calls keep only their names, sizes and times` });
+      }
+      if (runId && extra.call && capture === "full" && !captureFull && recordCallIo(path.resolve(agentDir, "..", ".."), runId, extra.call, text, io, redact)) {
+        capturedChars += size;
+        rest = { ...others, captured: true };
+      }
+    }
+    step.events.push({ t, type, text: redact(text), ...rest });
     // A person in the loop: the question, its answer, a message delivered —
     // onto the step, so the run page, the API and history show them.
     if (extra?.operator) {
@@ -1988,7 +2158,26 @@ async function runStep(
     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();
+    let answer = (answers[Math.min(call, answers.length - 1)] ?? "").trim();
+    // `call: <tool> <input> => <output>` lines: a pretend tool call, sent
+    // through the same push a real step's events take — with its model call
+    // and its content — so what the runner records of a step is testable.
+    answer = answer
+      .split("\n")
+      .filter((line) => {
+        const m = /^call: (\S+) (.*?) => (.*)$/.exec(line);
+        if (!m) return true;
+        const id = `toolu_stub${(step.calls?.length ?? 0) + 1}`;
+        // Twice under one id, as the SDK sends a turn's blocks: one row.
+        const turn = { id: `msg_stub${(step.calls?.length ?? 0) + 1}`, n: 0, at: new Date().toISOString(), ms: 5, model: "stub", tokens: { input: 100, output: 10, cacheRead: 80, cacheWrite: 0 }, tools: 0 };
+        push("info", "", { turn });
+        push("info", "", { turn: { ...turn, stop: "tool_use", tools: 1 } });
+        push("tool", m[1]!, { call: id, ...(capture ? { io: { input: m[2]!, inputChars: m[2]!.length } } : {}) });
+        push("tool", m[1]!, { call: id, ms: 3, io: { output: m[3]!, outputChars: m[3]!.length } });
+        return false;
+      })
+      .join("\n")
+      .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
@@ -2027,7 +2216,7 @@ async function runStep(
     // 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, clock, systemPrompt, allowed, disabled, apiTools, scriptTools,
+      front, clockEnv, clock, systemPrompt, promptLayers, allowed, disabled, apiTools, scriptTools,
       secretEnv, secretScopes, missingSecrets, missingTools, runtime,
       unknownTools, shadowed, legacyUse, retiredTools, mcpServers, mcpNames,
       apiSpecs, scriptSpecs, brokenTools, size: agentSize,
@@ -2035,6 +2224,7 @@ async function runStep(
       searchChoice, fetchChoice, actionChoices, web, language, region,
       fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools,
       ask,
+      peers,
       translator, fallbackTranslator,
       outward,
     } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent }, flowTimezone);
@@ -2043,6 +2233,9 @@ async function runStep(
     // Sent again on every turn; with turns and the tools' result sizes, what
     // a token report reads to say where a step's input went.
     step.systemPromptChars = systemPrompt.length;
+    // And each layer's size and hash, so a later reader can say which part
+    // of the prompt changed between this step and the agent's last.
+    step.promptLayers = promptLayers;
     // A retry that moved the step up a class (an evicted or OOM-killed
     // attempt) wins over the agent's own `size:` for the attempts after.
     const size = step.sizeUp ?? agentSize;
@@ -2062,11 +2255,7 @@ async function runStep(
     // 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);
+    redactions = redactionsFor({ ...liveSecrets, ...providerSecrets, ...providerEnv });
 
     // One line for the clock: which zone this step works to, and which level
     // set it. "Why is this dated yesterday" should be answerable from the run.
@@ -2314,7 +2503,14 @@ async function runStep(
       ...mcpNames,
       ...(consults.length ? ["foldrun_agents"] : []),
       ...(ask ? ["foldrun_ask"] : []),
+      ...(peers ? ["foldrun_peers"] : []),
     ];
+    if (peers) {
+      // The colleagues' contract, in the prompt the step reads: who runs
+      // beside it this time (none, when it runs alone), and that a message
+      // is a request, never a hand-over.
+      prompt += `\n\n<colleagues>\n${peersPromptLine(siblings)}\n</colleagues>`;
+    }
 
     // Colleagues this agent may DELEGATE to: each with its own context and
     // its own tools — resolved exactly as its own step's would be, then cut
@@ -2483,7 +2679,24 @@ async function runStep(
         ],
       });
       grant.network = { level: network.level, hosts: network.hosts };
-      const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant, test: testRun, ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}) });
+      // network_enforce: true at the account or the workspace asks the proxy
+      // to refuse; the proxy adds the install's own switch and has the last
+      // word (egress-proxy.ts), so false here never loosens anything.
+      grant.enforce = networkEnforceWanted(
+        readAgentsMd(accountDir(tenant))?.data?.network_enforce,
+        readAgentsMd(workspaceRootOf(agentDir))?.data?.network_enforce,
+      );
+      const lease = await platform.egress.lease({
+        tenant,
+        runId: runId ?? "adhoc",
+        grant,
+        test: testRun,
+        ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}),
+        // tools: [peers] — the roster the proxy serves, and the inboxes a
+        // colleague's message may be addressed to. Only when granted: a
+        // step without the tools has no reason to know its siblings.
+        ...(peers && stepIndex !== undefined && stepIndex >= 0 ? { agent: step.agent, peers: siblings } : {}),
+      });
       // The forward door: every program in the sandbox sends through the
       // proxy, which holds the site list and fills bound secrets. A proxy
       // without the door (an older platform) leaves programs going direct.
@@ -2556,6 +2769,23 @@ async function runStep(
       // carrying TEST_MODE_WITHHELD would only fail where it should have
       // been sunk or refused.
       const apiValues = testRun && lease ? placeholders : sandboxSecrets;
+      // A declared secret named like the step's own model variables
+      // (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, …) was spread over them below
+      // and broke, or redirected, the step's model calls (FOL-19). It crosses
+      // as FOLDRUN_DECLARED_<NAME> instead: the model keeps its settings, and
+      // the driver gives the agent's API and script tools the value under its
+      // own name (run-container.ts) — never the model's key in its place.
+      const modelNamed = Object.keys(sandboxSecrets).filter(isModelEnvName);
+      if (modelNamed.length) {
+        push(
+          "info",
+          `secrets: ${modelNamed.join(", ")} kept away from the model's own settings — ${modelNamed.length === 1 ? "that name is" : "those names are"} what the step's model call uses; ` +
+            "its script and API tools and verify: get the declared value, its own shell the model's. Give the secret another name, or run the model on it with provider:",
+        );
+      }
+      const sandboxEnvSecrets = Object.fromEntries(
+        Object.entries(sandboxSecrets).map(([name, value]) => [isModelEnvName(name) ? `${DECLARED_ENV_PREFIX}${name}` : name, value]),
+      );
       const substitutedApis = apiSpecs.map((api) => ({
         ...api,
         headers: Object.fromEntries(
@@ -2612,15 +2842,19 @@ async function runStep(
           // field. A tool's own `runtime:` is part of what this step needs.
           runtime: runtime.spec,
           consults,
+          ...(peers ? { peers: { self: step.agent, siblings } } : {}),
           ...(subagents.length ? { subagents } : {}),
           timeoutSec: step.timeout,
           budgetUsd: stepBudgetUsd,
           budgetNote: stepBudgetNote,
           price: tokenPrice,
           verify: step.verify,
+          ...(judgeModel ? { judgeModel } : {}),
+          ...(judgeEffort ? { judgeEffort } : {}),
           output: step.output,
           schema: resolvedSchema ?? undefined,
           maxTurns: step.maxTurns,
+          capture,
           ...limitOpts,
           ...hookOpts,
           translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
@@ -2667,12 +2901,15 @@ async function runStep(
             FOLDRUN_AGENT: step.agent,
             FOLDRUN_WORKSPACE: path.basename(workspaceRoot),
             ...(testRun ? testModeEnv() : {}),
-            ...sandboxSecrets,
+            ...sandboxEnvSecrets,
           }).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
         ),
         emit: pushWatching,
         // Stamps the sandbox, so stopping this run can destroy it.
         runId,
+        // A step still waiting for room has no sandbox to destroy; the
+        // executor asks this before it creates one (pod-room.ts).
+        ...(stopRequested ? { stopRequested } : {}),
         size,
         // The pod's network, for the executor's own wall (the k8s tier's
         // network policy): a filtered pod reaches the proxy and DNS only.
@@ -2950,6 +3187,13 @@ async function runStep(
       // On this machine nobody can write in and there is no proxy: the
       // question goes to the terminal when there is one, else unanswered.
       const askTools = ask ? buildAskTool({ channel: null, timeoutSec: ask.timeoutSec, emit: push, local: terminalAsk }) : null;
+      // Colleagues in the same group reach each other over the run's own
+      // bus here — no proxy, so no person can write in, but a sibling can.
+      // Every grouped step gets the inbox (a pod reads the proxy's inbox
+      // whatever its tools); only tools: [peers] gets the tools to send.
+      const peerChannel = peerBus && stepIndex !== undefined && stepIndex >= 0 ? peerBus.channelFor({ agent: step.agent, step: stepIndex }, siblings) : null;
+      const peerTools = peers ? buildPeerTools({ channel: peerChannel, self: step.agent, siblings, emit: push }) : null;
+      const localInbox = peerChannel ? inboxReader(peerChannel, push) : undefined;
       // @file secrets become 0600 paths here (host run), cleaned up in the
       // finally — once, however many attempts follow.
       const mat = materializeFileSecrets(agentDir, stepSecrets);
@@ -2973,6 +3217,9 @@ async function runStep(
         workspaceRoot,
         libraryRoot: libraryDir(tenant),
         ...(subagents.length ? { subagents } : {}),
+        // The colleagues' inbox, read after every tool call — the same hook
+        // a pod uses for a person's messages.
+        ...(localInbox ? { inbox: localInbox } : {}),
         prompt,
         model,
         effort,
@@ -2987,6 +3234,7 @@ async function runStep(
           ...(historyTools.server ? { foldrun_history: historyTools.server } : {}),
           ...(deskTools.server ? { foldrun_desks: deskTools.server } : {}),
           ...(askTools ? { foldrun_ask: askTools.server } : {}),
+          ...(peerTools ? { foldrun_peers: peerTools.server } : {}),
           ...(installTools ? { foldrun_install: installTools.server } : {}),
           ...mcpServers,
         },
@@ -3001,9 +3249,12 @@ async function runStep(
         budgetNote: stepBudgetNote,
         price: tokenPrice,
         verify: step.verify,
+        ...(judgeModel ? { judgeModel } : {}),
+        ...(judgeEffort ? { judgeEffort } : {}),
         output: step.output,
         schema: resolvedSchema ?? undefined,
         maxTurns: step.maxTurns,
+        capture,
         ...limitOpts,
         ...hookOpts,
         stopRequested,
@@ -3203,7 +3454,7 @@ export function copyTreeBytes(from: string, to: string) {
 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 { data } = configMatter(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, "..", ".."));
@@ -3266,7 +3517,7 @@ const CREDENTIAL_POLL_MS = 2_000;
  *  step started one second before the 09:07:52Z refresh) matched none of the
  *  older two, so the step failed instead of waiting for the new token. */
 export function isAuthRefusal(text: string): boolean {
-  return /API Error: 401|access token has (been revoked|expired)|OAuth token (has )?(been )?(revoked|expired)|Failed to authenticate/i.test(text);
+  return AUTH_REFUSAL.test(text);
 }
 
 /**
@@ -3828,10 +4079,30 @@ function driveRunInner(
    *
    * The flag is one-way: nothing here clears it, so the read-modify-write can
    * only ever turn a stop on, never off.
+   *
+   * And once it is on, this copy may not undo what stopRun wrote: the run
+   * stays failed, and steps that had not started stay skipped. Before
+   * 21 Oct 2026 only the flag came across, so the next save put the record
+   * back to `running` with its steps pending; a second stop then answered
+   * "failed" instead of "already failed", and the group kept starting pods
+   * (medium-desk run-mvho48wp-99e1). A step running in THIS process is left
+   * as it is: its sandbox is gone, it ends on its own, and records how.
    */
   const save = () => {
-    if (!run.stopRequested && readRun(tenant, workspace, run.id)?.stopRequested) {
-      run.stopRequested = true;
+    const disk = run.stopRequested ? null : readRun(tenant, workspace, run.id);
+    if (disk?.stopRequested) run.stopRequested = true;
+    if (run.stopRequested) {
+      if (run.status !== "completed" && run.status !== "failed") {
+        run.status = "failed";
+        run.finishedAt ??= disk?.finishedAt ?? new Date().toISOString();
+      }
+      run.parkedAt = null;
+      for (const s of run.steps) {
+        if (s.status === "pending" || s.status === "awaiting-approval") {
+          s.status = "skipped";
+          s.skipReason ??= "run stopped";
+        }
+      }
     }
     writeRun(tenant, workspace, run);
   };
@@ -3890,6 +4161,12 @@ function driveRunInner(
     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.
+      // The first pick-up (FOL-54 step 4): startedAt to this is the time it
+      // queued; and the files it runs are the workspace's latest revision
+      // as it starts — a deploy's revision is its commit, and an edit through
+      // /source makes one too. A re-run comes through here as well.
+      run.drivenAt ??= new Date().toISOString();
+      if (run.revision === undefined) run.revision = latestRevisionId(tenant, workspace);
       if (run.status !== "running") {
         run.status = "running";
         run.parkedAt = null;
@@ -4043,13 +4320,20 @@ function driveRunInner(
         for (let i = gi - 1; i >= 0; i--) if (groupData[i] !== undefined) return groupData[i];
         return undefined;
       };
-      const dataOf = (group: StepRecord[]): unknown => {
+      // A rescue's result already stands on the step it took over, so the
+      // three handoffs below read the flow's steps only: counting the rescue
+      // too handed the next group the same output twice, or a stale one
+      // from an evaluator loop's earlier cycle.
+      const flowStepsOf = (group: StepRecord[]) => group.filter((s) => !isRescueRecord(s));
+      const dataOf = (all: StepRecord[]): unknown => {
+        const group = flowStepsOf(all);
         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 resultsOf = (all: StepRecord[]): string | null => {
+        const group = flowStepsOf(all);
         const results = group
           .filter((s) => s.status === "completed" && s.result)
           .map((s) =>
@@ -4063,8 +4347,8 @@ function driveRunInner(
       };
       // 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
+      const conclusionsOf = (all: StepRecord[]): string | null => {
+        const out = flowStepsOf(all)
           .filter((s) => s.status === "completed" && (s.conclusion || s.result))
           .map((s) => s.conclusion || s.result!);
         return out.length ? out.join("\n") : null;
@@ -4451,7 +4735,7 @@ function driveRunInner(
           save();
           if (freshGroup.every((s) => s.status !== "pending")) {
             // everything in this group was rejected
-            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom)) {
+            if (freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s))) {
               run.status = "failed";
               break;
             }
@@ -4465,7 +4749,18 @@ function driveRunInner(
         // 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");
+        // A rescue record is the on-fail of a step in this group, not a step
+        // of the flow: one left pending by a drive that died is picked up by
+        // rescueStep below, never launched alongside the group (21 Oct 2026:
+        // a resumed run launched 77 leftover fixers at once).
+        const launching = freshGroup.filter((s) => s.status === "pending" && !isRescueRecord(s));
+        // tools: [peers] — what each step of the group is told about the
+        // others, and the bus they share when they run in this process.
+        const peerBus = localPeerBus();
+        const siblingsOf = (step: StepRecord): PeerInfo[] =>
+          launching
+            .filter((s) => s !== step)
+            .map((s) => ({ agent: s.agent, step: run.steps.indexOf(s), instruction: (s.instruction ?? "").split("\n")[0].trim().slice(0, 200) }));
         // An agent's own `budget:` — the most it may spend in one run — is
         // read at launch, so a cap raised mid-run applies to the next step.
         const agentBudgets = new Map(listAgents(tenant, workspace).map((a) => [a.name, a.budget]));
@@ -4502,15 +4797,48 @@ function driveRunInner(
           if (!pool) pools.set(key, (pool = slotPool(step.parallel)));
           return pool;
         };
+        // One instance of each agent goes first so its siblings read the
+        // prompt cache it wrote — see warmGate. The claim is the callback's
+        // first statement, before any await; the wait comes before the
+        // pool, so nothing holds a slot while it waits.
+        const gate = warmGate(launching);
         await Promise.all(
           launching
             .map(async (step) => {
+              const lead = gate.claim(step);
+              if (lead) {
+                step.events.push({ t: new Date().toISOString(), type: "info", text: `prompt cache: waiting for the first ${step.agent} step's reply before starting, so this one reads its prefix` });
+                save();
+                await lead;
+              }
               const pool = poolFor(step);
               if (pool) await pool.acquire();
               try {
-                await launchStep(step);
+                // A stop that arrived while this copy waited — for the
+                // lead's reply or for a slot — must not start it: the
+                // between-groups check runs only once this group is over,
+                // and save() is what carries the flag in from the record.
+                {
+                  save();
+                  if (run.stopRequested) {
+                    step.status = "skipped";
+                    step.skipReason = "run stopped";
+                    step.events.push({ t: new Date().toISOString(), type: "info", text: "run stopped by a person while this step waited to start — skipped" });
+                    save();
+                    gate.release(step);
+                    return;
+                  }
+                }
+                await gate.run(step, () => launchStep(step));
               } finally {
                 pool?.release();
+                // Every attempt is over: off its siblings' rosters, so a
+                // message to it is not reported delivered and never read.
+                // Here, not per attempt — a step between retries is still
+                // one its colleagues can reach.
+                const index = run.steps.indexOf(step);
+                peerBus.leave(index);
+                await platform.egress.stepEnded?.({ tenant, runId: run.id, step: index }).catch(() => undefined);
               }
             }),
         );
@@ -4574,6 +4902,8 @@ function driveRunInner(
                   },
                   flowTimezone,
                   run.steps.indexOf(step),
+                  siblingsOf(step),
+                  peerBus,
                 ).finally(() => reserved.delete(step));
                 // runStep mutates step.status; read it through a widened local
                 // so TS doesn't keep the "running" narrowing from above.
@@ -4668,6 +4998,13 @@ function driveRunInner(
         // runs out of cycles below, which used to fail the run without ever
         // reaching the step's on-fail (medium-desk's claim-trimmer was
         // written for exactly that case and could never run).
+        // A rescue hears a stop the way a group step does: its model loop and
+        // its executor's wait for room both poll this (no sandbox exists yet
+        // for a stop to destroy while it waits).
+        const stopPoll = () => {
+          save();
+          return run.stopRequested === true;
+        };
         const rescueStep = async (step: StepRecord): Promise<void> => {
           if (!step.onFail) return;
           const rescuerDir = path.join(pDir, "agents", step.onFail);
@@ -4679,6 +5016,38 @@ function driveRunInner(
             });
             return;
           }
+          // One rescue per failure, across drives. A worker that died
+          // mid-rescue left an unfinished record behind it; the drive that
+          // resumes picks that one up instead of splicing another — a crash
+          // loop used to add one per restart (blog-desk run-mvh1zra7-ae4k,
+          // ~80). The leftover carries the same instruction, built from the
+          // same failure, and a running one may still hold a sandbox to
+          // re-attach to, so it is THE rescue; any further unfinished copies
+          // are superseded. A FINISHED rescue is history, never reused: it
+          // answered an earlier failure — an evaluator loop's previous cycle
+          // — not this one.
+          const leftovers: StepRecord[] = [];
+          for (let j = run.steps.indexOf(step) + 1; j < run.steps.length && isRescueRecord(run.steps[j]); j++) {
+            const r = run.steps[j];
+            if (r.agent === step.onFail && (r.rescueOf === undefined || r.rescueOf === step.agent) && (r.status === "pending" || r.status === "running")) {
+              leftovers.push(r);
+            }
+          }
+          const resumed = leftovers[0];
+          for (const r of leftovers.slice(1)) {
+            r.status = "skipped";
+            r.skipReason = "superseded on resume — one rescue per failure";
+          }
+          if (resumed) {
+            step.events.push({ t: new Date().toISOString(), type: "info", text: `resuming the rescue by [[${step.onFail}]] that an earlier drive started` });
+            resumed.rescueOf ??= step.agent;
+            resumed.attempts = Math.max(1, resumed.attempts ?? 0);
+            resumed.status = "running";
+            save();
+            await runStep(rescuerDir, tenant, resumed, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, stopPoll, flowTimezone, run.steps.indexOf(resumed));
+            settleRescue(step, resumed);
+            return;
+          }
           step.events.push({
             t: new Date().toISOString(),
             type: "info",
@@ -4695,6 +5064,7 @@ function driveRunInner(
           const owesMarker = step.until ? `\nThe step's loop ended without its marker: your reply must end with a line saying ${step.until}.` : "";
           const rescue: StepRecord = {
             agent: step.onFail,
+            rescueOf: step.agent,
             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}${approved}${owesMarker}\n</rescue>`,
@@ -4725,7 +5095,11 @@ function driveRunInner(
           rescue.attempts = 1;
           rescue.status = "running";
           save();
-          await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, undefined, flowTimezone, run.steps.indexOf(rescue));
+          await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, stopPoll, flowTimezone, run.steps.indexOf(rescue));
+          settleRescue(step, rescue);
+        };
+        // What a rescue's end means for the step it took over.
+        const settleRescue = (step: StepRecord, rescue: StepRecord): void => {
           // runStep mutates rescue.status; widen past TS's "running" narrowing.
           const rescueOutcome: string = rescue.status;
           if (rescueOutcome === "completed") {
@@ -4757,7 +5131,10 @@ function driveRunInner(
         // here: the person chose to start after it. Counting it stopped
         // fix-desk's "re-run from the verifier" (run-muwfi5jn-4217) in under
         // a second, before the one step it was asked to run.
-        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom);
+        // A rescue record's own failure is already on the step it took over
+        // ("also failed"); counted here it would fail a group whose step a
+        // later rescue completed.
+        const requiredFailed = freshGroup.some((s) => s.status === "failed" && !s.optional && !s.carriedFrom && !isRescueRecord(s));
         if (requiredFailed) {
           run.status = "failed";
           break;
@@ -4833,6 +5210,10 @@ function driveRunInner(
             });
             for (const s of [...ordered[gi - 1], ...freshGroup]) {
               if (s.status === "skipped" && s.each) continue; // an expanded template stays expanded
+              // A rescue answered its own failure and stays as it ended: reset
+              // to pending it read as an interrupted rescue, and the next
+              // cycle's failure was handed the old one's instructions.
+              if (isRescueRecord(s)) continue;
               s.status = "pending";
               s.result = null;
             }
@@ -5073,7 +5454,14 @@ export interface Reconciliation {
  * 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(), live?: ReadonlySet<string>): Reconciliation[] {
+/** Told when a run reconcile closed, or resumed and saw to its end — so the
+ *  platform settles, notifies and chains it as it would a run its worker
+ *  drove (a run closed here had spent tokens, and nobody was charged or
+ *  told). Not told when a resumed run parks again: whatever resumes it next
+ *  goes through the worker. */
+export type ReconcileEnd = (tenant: string, workspace: string, runId: string) => void | Promise<void>;
+
+export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[] {
   const closed: Reconciliation[] = [];
 
   for (const workspace of listWorkspaces(tenant)) {
@@ -5108,7 +5496,12 @@ export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlyS
         // 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 });
+        void driveRun(tenant, workspace.name, run, null, run.tags ?? [], { parkOnApproval: true })
+          .then(() => {
+            const after = readRun(tenant, workspace.name, run.id);
+            if (onEnd && after && (after.status === "completed" || after.status === "failed")) return onEnd(tenant, workspace.name, run.id);
+          })
+          .catch((err) => console.error(`[foldrun] reconcile: ${tenant}/${workspace.name}/${run.id} after resume:`, err));
         closed.push({
           runId: run.id,
           tenant,
@@ -5153,6 +5546,11 @@ export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlyS
         // a sandbox we cannot reach must not stop the reconcile
       }
       closed.push({ runId: run.id, tenant, workspace: workspace.name, action: "closed", interrupted });
+      if (onEnd) {
+        void Promise.resolve()
+          .then(() => onEnd(tenant, workspace.name, run.id))
+          .catch((err) => console.error(`[foldrun] reconcile: ${tenant}/${workspace.name}/${run.id} after close:`, err));
+      }
     }
   }
 
@@ -5166,8 +5564,8 @@ export function reconcileRuns(tenant: string, now = Date.now(), live?: ReadonlyS
  * 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(), live?: ReadonlySet<string>): Reconciliation[] {
-  return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live));
+export function reconcileAllRuns(now = Date.now(), live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[] {
+  return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live, onEnd));
 }
 
 /**