@foldrun/core 2.3.0 → 2.5.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 from "./matter.ts";
 import { spawn } from "node:child_process";
 import {
   knownPrice, executeStep, extractJson, stepCeiling, stepCeilingFor, type EventExtra } from "./step-exec.ts";
@@ -17,7 +20,7 @@ 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 { 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 +36,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";
@@ -83,9 +86,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 +214,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,12 +334,9 @@ 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();
+  // gray-matter caches a *failed* parse as a hollow success; ./matter.ts
+  // parses every call, so the throw below is deterministic and the fallback
+  // fires every time (it used to clear gray-matter's cache here for that).
   try {
     return matter(raw) as { data: Record<string, unknown> };
   } catch {
@@ -427,6 +523,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 ?? {}),
@@ -758,7 +858,11 @@ export function agentContext(
   const { data: front, content: body } = matter(
     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 +884,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 +936,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 +975,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 +997,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 +1020,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 +1053,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 +1071,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 +1082,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 +1165,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 +1322,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 +1516,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 +1535,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 +1568,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 +1615,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 +1648,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 +1710,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 +1741,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 +1749,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 +1775,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 +2033,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 +2085,54 @@ 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";
+  // 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 +2166,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 +2224,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 +2232,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 +2241,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 +2263,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 +2511,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 +2687,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 +2777,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,6 +2850,7 @@ 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,
@@ -2621,6 +2860,7 @@ async function runStep(
           output: step.output,
           schema: resolvedSchema ?? undefined,
           maxTurns: step.maxTurns,
+          capture,
           ...limitOpts,
           ...hookOpts,
           translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
@@ -2667,7 +2907,7 @@ 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,
@@ -2950,6 +3190,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 +3220,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 +3237,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,
         },
@@ -3004,6 +3255,7 @@ async function runStep(
         output: step.output,
         schema: resolvedSchema ?? undefined,
         maxTurns: step.maxTurns,
+        capture,
         ...limitOpts,
         ...hookOpts,
         stopRequested,
@@ -3266,7 +3518,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);
 }
 
 /**
@@ -3890,6 +4142,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;
@@ -4466,6 +4724,13 @@ function driveRunInner(
         // 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");
+        // 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 +4767,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.
+                if (lead || pool) {
+                  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 +4872,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.
@@ -5073,7 +5373,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 +5415,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 +5465,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 +5483,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));
 }
 
 /**