@foldrun/core 2.3.0 → 2.5.0

package/dist/src/runner.js

@@ -2,11 +2,14 @@
 // group receives every prior result, labeled per agent. Optional steps ("2?")
 // fail without failing the flow. A direct agent run is a one-step ad-hoc
 // flow, so there is a single execution path.
+import { latestRevisionId } from "./history.js";
+import { recordCallIo, redactionsFor } from "./capture.js";
+import { AUTH_REFUSAL } from "./issues.js";
 import { hookNames } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { knownPrice, executeStep, extractJson, stepCeiling, stepCeilingFor } from "./step-exec.js";
 import { cascadeLimits, toolOwners } from "./limits.js";
 import { resolveAgentPath } from "./confine.js";
@@ -14,7 +17,7 @@ import { browserPodLine, podLossDecision, RERAN_ON_FULL } from "./browser-pod.js
 import { eventUrl } from "./webhook.js";
 import { runStepInContainer, sizeLimits, killRunSandboxes } from "./run-container.js";
 import { hostSafeEnv, platformApiUrl } from "./host-env.js";
-import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken } from "./model-credential.js";
+import { resolveModelCredential, credentialLine, accountModelBlock, isClaudeLoginToken, isModelEnvName, DECLARED_ENV_PREFIX } from "./model-credential.js";
 import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.js";
 import { EGRESS_ENV, MODEL_KEY_NAME, addGrant, hostOf, placeholderNames, proxyModelEnv, unsubstitute } from "./egress.js";
 import { explainRefusal, isRefusalStatus, refusalFromLine, supplyNote } from "./refusal.js";
@@ -29,15 +32,16 @@ const isolatedRun = () => {
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.js";
 import { DELEGATE_TOOL, gatherSubagents, subagentPrompt, subagentTools } from "./subagents.js";
-import { ASK_TOOL, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool } from "./operator.js";
+import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool, buildPeerTools, inboxReader, localPeerBus, peersPromptLine } from "./operator.js";
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
 import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { canReadBack } from "./tool-output.js";
+import { PromptLayers, promptCacheKey } from "./prompt-layers.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
-import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.js";
+import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
 import { attachOperations, prefetchOpenApi } from "./openapi.js";
@@ -155,6 +159,105 @@ export function slotPool(size) {
         },
     };
 }
+/** 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();
+export function markResponding(step) {
+    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, done, pollMs = 250) {
+    const replied = () => respondingSteps.has(step) || step.events.some((e) => e.type === "text" || e.type === "tool") || (step.calls?.length ?? 0) > 0;
+    return new Promise((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, pollMs = 250) {
+    const key = (s) => `${s.agent}\u0000${s.model ?? ""}`;
+    const counts = new Map();
+    for (const s of launching)
+        counts.set(key(s), (counts.get(key(s)) ?? 0) + 1);
+    const leads = new Map();
+    const isLead = new WeakSet();
+    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) {
+            const k = key(step);
+            if ((counts.get(k) ?? 0) < 2)
+                return null;
+            const lead = leads.get(k);
+            if (lead)
+                return lead.opened;
+            let open;
+            const opened = new Promise((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) {
+            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, launch) {
+            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;
+        },
+    };
+}
 const toTags = (v) => Array.isArray(v) ? v.map(String) : typeof v === "string" && v.trim() ? [v.trim()] : [];
 // gray-matter throws on invalid YAML. Skills authored for another client
 // sometimes ship YAML that that client's parser happened to accept — most
@@ -162,12 +265,9 @@ const toTags = (v) => Array.isArray(v) ? v.map(String) : typeof v === "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) {
-    // gray-matter caches by input string AND caches a *failed* parse: the first
-    // call on invalid YAML throws, but every later call on the same bytes returns
-    // a hollow object with the fields silently missing. Clearing the cache makes
-    // the throw deterministic, so the fallback below fires every time rather than
-    // once — otherwise the same skill loads on one run and vanishes on the next.
-    matter.clearCache();
+    // 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);
     }
@@ -351,6 +451,9 @@ export function workspaceRuntimePlan(tenant, workspace) {
     }
     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, tenant) {
     return {
         ...(readAgentsMd(accountDir(tenant))?.data ?? {}),
@@ -651,7 +754,11 @@ grantsOnly = false) {
     // workspace a secret should resolve against is two levels up.
     const workspace = path.basename(path.resolve(agentDir, "..", ".."));
     const { data: front, content: body } = matter(fs.readFileSync(path.join(agentDir, "agent.md"), "utf8"));
-    const parts = [resolveDocLinks(body.trim(), path.resolve(agentDir, "..", ".."))];
+    // 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
     // than implied: told to read `../../knowledge/index.md`, the model asked for
@@ -672,12 +779,12 @@ grantsOnly = false) {
     const languageSet = language.from !== "default" && language.from !== "env";
     const regionSet = region.from !== "none" && region.from !== "env" && region.from !== "language";
     if (languageSet || regionSet) {
-        parts.push(`# Locale\n\n${localeProse(locale, languageName(language.language), regionName(region.region))} ` +
+        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(`# Where you are\n\n` +
+    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 — ` +
         `\`outputs/\` is yours, and \`workspace/\` is the workspace root, in every tool ` +
@@ -720,7 +827,7 @@ grantsOnly = false) {
     // background the rest of the prompt is read against, not an afterthought.
     const sharedContext = sharedInstructions(agentDir, tenant);
     if (sharedContext)
-        parts.push(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
     // flat `skills/<name>.md` form is also accepted for small skills.
@@ -754,7 +861,7 @@ grantsOnly = false) {
                 `Full instructions: \`${s.path}\`` +
                 (bundles.length ? ` (also bundles ${bundles.join(", ")})` : ""));
         });
-        parts.push(`# Skills\n\nCapabilities available to you. Each line is a summary — when a task matches one, ` +
+        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.)` : ""));
     }
@@ -773,10 +880,11 @@ grantsOnly = false) {
             : "";
         const projectMem = workspaceMemoryIndex(tenant, workspace);
         const shared = libraryMemoryIndex(tenant);
-        parts.push(`# Memory — what you have learned\n\n${memoryIndex ? `Your own (files under memory/):\n\n${memoryIndex}` : "You have no memories of your own yet."}` +
+        // 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);
+            howTo, { dynamic: true });
     }
     // Knowledge — reference material the agent was given. Same three scopes and
     // the same nearest-wins reading order as memory, but never written back:
@@ -791,7 +899,7 @@ grantsOnly = false) {
             projectKnowledge && `Shared across this workspace:\n\n${projectKnowledge}`,
             sharedKnowledge && `Shared across every workspace:\n\n${sharedKnowledge}`,
         ].filter(Boolean);
-        parts.push(`# Knowledge — what you were given\n\nReference material. Open a file when a task depends ` +
+        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` +
             sections.join("\n\n"));
@@ -822,7 +930,7 @@ grantsOnly = false) {
             shared.length ? `Shared across this workspace:\n${shared.join("\n")}` : null,
             global.length ? `From the account library (read-only):\n${global.join("\n")}` : null,
         ].filter(Boolean);
-        parts.push(`# Scripts\n\nTooling you can run with bash from your working directory:\n\n${sections.join("\n\n")}\n\n` +
+        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.`);
     }
@@ -837,7 +945,8 @@ grantsOnly = false) {
     // file to size it against, not before.
     const state = listDir(path.join(agentDir, "..", "..", "state"), "workspace/state/");
     if (state.length) {
-        parts.push(`# State — what you carry between runs\n\n` +
+        // 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 ` +
             `run starts where you left off.\n\n${state.join("\n")}\n\n` +
@@ -845,7 +954,7 @@ grantsOnly = false) {
             `A count reads as well in a sentence as in JSON, and a person edits these in the ` +
             `same editor as everything else — data formats are allowed here, not preferred.\n\n` +
             `This is not memory. A fact you learned goes in memory/, where it is indexed and ` +
-            `its provenance recorded — state is the bookmark, not the lesson.`);
+            `its provenance recorded — state is the bookmark, not the lesson.`, { dynamic: true });
     }
     // APIs — the agent's own definitions, plus workspace tools it granted by
     // name. Library tools are defined once and reused.
@@ -928,7 +1037,7 @@ grantsOnly = false) {
     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.
     //
@@ -1079,6 +1188,10 @@ grantsOnly = false) {
                 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.
@@ -1261,10 +1374,12 @@ grantsOnly = false) {
         FOLDRUN_WORKSPACE: workspace,
         ...clockEnv,
     }, libraryDir(tenant, "scripts"), runtime.interpreters, exec, keepIn.readable);
-    parts.push(`# Clock\n\nToday is ${clockEnv.FOLDRUN_DATE} (${timezone}). Use this date for anything you ` +
-        `write or check — it is the workspace's calendar, not the container's clock.`);
+    // 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(`# Tools from scripts\n\nCall these directly — they run workspace scripts for you. Each is called by its full name, ` +
+        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")}`);
     }
     // The web tool's own description lists every action, so an agent whose
@@ -1273,15 +1388,15 @@ grantsOnly = false) {
     // 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(`# Web search and fetch on this run\n\n` +
+        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(`# Secrets\n\nAvailable to your scripts as environment variables: ${declared.join(", ")}. ` +
+        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("Write deliverables for people to workspace/storage/ (kept and downloadable); write working text for later steps to outputs/; " +
+    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 " +
         "directory a tool made outside the workspace, such as a checkout, is reached only through that tool. " +
@@ -1298,7 +1413,7 @@ grantsOnly = false) {
     // run, and an agent that opened with "I'll start by cloning the repo" made
     // all three useless. Asking here rather than in each agent.md means every
     // agent obeys it, including the ones written before the summary existed.
-    parts.push("Open your reply with one sentence saying what you concluded or produced — the outcome, " +
+    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.");
     // One list. `tools:` grants anything: a built-in group, an exact SDK tool
@@ -1340,6 +1455,7 @@ grantsOnly = false) {
     let wantHistory = false;
     let wantDesks = false;
     let wantAsk = false;
+    let wantPeers = false;
     for (const ref of toolRefs(front)) {
         const toolName = ref.name;
         if (ref.mode === "ask") {
@@ -1374,7 +1490,7 @@ grantsOnly = false) {
             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")
@@ -1383,6 +1499,8 @@ grantsOnly = false) {
                 wantHistory = true;
             else if (toolName === "ask")
                 wantAsk = true;
+            else if (toolName === "peers")
+                wantPeers = true;
             else
                 wantDesks = true;
             if (available[toolName])
@@ -1444,10 +1562,17 @@ grantsOnly = false) {
     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
@@ -1469,13 +1594,16 @@ grantsOnly = false) {
         denied.push(INSTALL_TOOL);
     const finalAllowed = allowed.filter((t) => !denied.includes(t));
     readsFiles = canReadBack(finalAllowed);
+    const prompt = parts.assemble();
     return {
         front,
         clockEnv,
         /** 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,
@@ -1499,6 +1627,7 @@ grantsOnly = false) {
         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
@@ -1730,7 +1859,13 @@ flowTimezone,
 /** The step's index in run.steps, carried on its egress lease so a
  *  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) {
+stepIndex, 
+/** The other steps launched with this one (its parallel group), for
+ *  tools: [peers]. Empty when it runs alone. */
+siblings = [], 
+/** The in-process colleagues' bus for this group (localPeerBus), when
+ *  the step runs in this process rather than a pod. */
+peerBus) {
     // Secret values are injected into scripts as environment variables and
     // substituted into API headers, so a model that reads one back — from a
     // script that prints it, an API error that echoes it, or its own `env` —
@@ -1776,9 +1911,56 @@ stepIndex) {
             return value;
         }
     };
+    // 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 = 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, text, extra) => {
         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 = 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) {
@@ -1810,7 +1992,27 @@ stepIndex) {
         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
@@ -1849,12 +2051,15 @@ stepIndex) {
         // 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, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, retiredTools, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size: agentSize, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, searchChoice, fetchChoice, actionChoices, web, language, region, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, ask, translator, fallbackTranslator, outward, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent }, flowTimezone);
+        const { 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, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, 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);
         disposeRuntime = runtime.dispose;
         canActOutward = outward;
         // 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;
@@ -1872,11 +2077,7 @@ stepIndex) {
         // Populate before the first push: everything after this point may quote a
         // credential. Short values are skipped — a two-character secret would
         // redact half the English language, and anything that short is not one.
-        redactions = Object.entries({ ...liveSecrets, ...providerSecrets, ...providerEnv })
-            .filter(([, value]) => typeof value === "string" && value.length >= 8)
-            .map(([name, value]) => [value, name])
-            // Longest first, so a value containing another is replaced whole.
-            .sort((a, b) => b[0].length - a[0].length);
+        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.
         push("info", `clock: ${clock.timezone} (${clock.source}) — today is ${clockEnv.FOLDRUN_DATE}`);
@@ -2115,7 +2316,14 @@ stepIndex) {
             ...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
         // to what THIS step holds (subagents.ts). Built host-side, like consults.
@@ -2286,7 +2494,21 @@ stepIndex) {
                 ],
             });
             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.
@@ -2357,6 +2579,18 @@ stepIndex) {
             // 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(Object.entries(api.headers).map(([k, v]) => [
@@ -2410,6 +2644,7 @@ stepIndex) {
                     // 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,
@@ -2419,6 +2654,7 @@ stepIndex) {
                     output: step.output,
                     schema: resolvedSchema ?? undefined,
                     maxTurns: step.maxTurns,
+                    capture,
                     ...limitOpts,
                     ...hookOpts,
                     translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
@@ -2464,7 +2700,7 @@ stepIndex) {
                     FOLDRUN_AGENT: step.agent,
                     FOLDRUN_WORKSPACE: path.basename(workspaceRoot),
                     ...(testRun ? testModeEnv() : {}),
-                    ...sandboxSecrets,
+                    ...sandboxEnvSecrets,
                 }).filter((entry) => typeof entry[1] === "string")),
                 emit: pushWatching,
                 // Stamps the sandbox, so stopping this run can destroy it.
@@ -2742,6 +2978,13 @@ stepIndex) {
             // 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);
@@ -2765,6 +3008,9 @@ stepIndex) {
                 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,
@@ -2779,6 +3025,7 @@ stepIndex) {
                     ...(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,
                 },
@@ -2796,6 +3043,7 @@ stepIndex) {
                 output: step.output,
                 schema: resolvedSchema ?? undefined,
                 maxTurns: step.maxTurns,
+                capture,
                 ...limitOpts,
                 ...hookOpts,
                 stopRequested,
@@ -3065,7 +3313,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) {
-    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);
 }
 /**
  * Wait, briefly, for the mounted credential to become one we have not
@@ -3649,6 +3897,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
         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;
@@ -4218,6 +4473,12 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // 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) => 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]));
@@ -4249,16 +4510,49 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         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);
                     }
                 }));
                 async function launchStep(step) {
@@ -4304,7 +4598,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         () => {
                             save();
                             return run.stopRequested === true;
-                        }, flowTimezone, run.steps.indexOf(step)).finally(() => reserved.delete(step));
+                        }, 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.
                         const outcome = step.status;
@@ -4767,26 +5061,7 @@ function lastActivity(run) {
     }
     return latest;
 }
-/**
- * Close out runs abandoned by a process that is no longer here.
- *
- * Runs execute in the server process, and nothing writes a terminal status
- * when that process goes away — so a deploy, a crash or a Ctrl-C during a run
- * leaves `status: "running"` on disk forever. The run history then contains
- * entries that are not merely stale but false: they claim to be in progress,
- * the dashboard renders them as live, and no one can tell them apart from a
- * step that is genuinely still thinking.
- *
- * Called at startup, before anything reads run history. A run still being
- * worked on by a live process is protected by the idle window, not by a lock —
- * so this is safe to call while runs are in flight, and deliberately
- * conservative about what it declares dead.
- *
- * A run genuinely waiting for a person is left alone: that state legitimately
- * outlives any process. A run whose person already answered is not waiting,
- * and is picked back up — see below.
- */
-export function reconcileRuns(tenant, now = Date.now(), live) {
+export function reconcileRuns(tenant, now = Date.now(), live, onEnd) {
     const closed = [];
     for (const workspace of listWorkspaces(tenant)) {
         // Live runs only, read whole — every other status is passed over below,
@@ -4823,7 +5098,13 @@ export function reconcileRuns(tenant, now = Date.now(), live) {
                 // 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,
@@ -4870,6 +5151,11 @@ export function reconcileRuns(tenant, now = Date.now(), live) {
                 // 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));
+            }
         }
     }
     return closed;
@@ -4881,8 +5167,8 @@ export function reconcileRuns(tenant, now = Date.now(), live) {
  * 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) {
-    return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live));
+export function reconcileAllRuns(now = Date.now(), live, onEnd) {
+    return listTenants().flatMap((tenant) => reconcileRuns(tenant, now, live, onEnd));
 }
 /**
  * Wait for a run to stop being in progress.