@foldrun/core 0.3.0 → 0.5.0

package/dist/src/runner.js

@@ -5,11 +5,19 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { knownPrice, executeStep, extractJson, stepCeiling } from "./step-exec.js";
+import { knownPrice, executeStep, extractJson, stepCeiling, stepCeilingFor } from "./step-exec.js";
+import { cascadeLimits, toolOwners } from "./limits.js";
+import { resolveAgentPath } from "./confine.js";
+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 } from "./host-env.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";
 import { platform } from "./platform.js";
+import { healthKey } from "./secret-health.js";
+import { TEST_WRITES_DIR, restoreDivertedDirs, snapshotDivertedDirs, testHeadline, testModeEnv, withholdSecrets } from "./test-mode.js";
 /** Does this process run steps in a sandbox — the container core ships, or
  *  one the platform registered (a pod)? */
 const isolatedRun = () => {
@@ -17,9 +25,12 @@ const isolatedRun = () => {
     return mode === "container" || (!!mode && mode in platform.isolation);
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.js";
-import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError } from "./tool-names.js";
+import { DELEGATE_TOOL, gatherSubagents, subagentPrompt, subagentTools } from "./subagents.js";
+import { ASK_TOOL, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool } 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, syncBundleFor, parseToolDef, parseFlow, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, STORAGE_DIR, adoptLegacyVersionKey, runCost, } from "./store.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
 import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
@@ -30,10 +41,17 @@ import { startTranslator, translatorSpecFor } from "./translator.js";
 import { providerPreset } from "./providers.js";
 import { buildScriptTools, parseScripts } from "./script-tools.js";
 import { libraryDir, libraryTools, libraryMemoryIndex } from "./library.js";
-import { mergeRuntimes, parseRuntime, prepareRuntime } from "./runtime.js";
+import { fingerprint, mergeRuntimes, parseRuntime, prepareRuntime } from "./runtime.js";
 import { materializeFiles, harvestFiles } from "./storage.js";
 import { chooseExecutor, ensureImage } from "./container.js";
 import { stampBundle } from "./okf.js";
+import { readBrowseSettings, readSearchSettings, resolveSearch, searchSettingsEnv, webConfig, browseSessionProblems } from "./providers.js";
+import { NEWER_ACTIONS, resolveActionApi } from "./web-actions.js";
+import { resolveLanguage, languageName } from "./language.js";
+import { resolveRegion, deriveLocale, localeProse, regionName } from "./locale.js";
+import { trimChars } from "./paths.js";
+import { resolveClock, localDate } from "./clock.js";
+export { localDate } from "./clock.js";
 // An MCP tool definition becomes an SDK server config. ${SECRET} placeholders
 // in env and headers resolve server-side, so a credential reaches the server
 // process without ever entering the model's context.
@@ -84,6 +102,34 @@ export function joinEarlierGroups(groupResults, gi, cap = CONTEXT_CHARS) {
         parts.shift();
     return parts.join("\n\n");
 }
+/**
+ * `parallel: N` — a pool of N slots the instances of one fan-out share.
+ * Fan-out always ran every instance at once, and still does unless the
+ * step says otherwise: twenty browser steps against one site, or one
+ * vendor's rate limit, is what the cap is for. Nothing is rented while an
+ * instance waits for a slot.
+ */
+export function slotPool(size) {
+    let free = Math.max(1, size);
+    const waiting = [];
+    return {
+        acquire: () => new Promise((resolve) => {
+            if (free > 0) {
+                free -= 1;
+                resolve();
+            }
+            else
+                waiting.push(resolve);
+        }),
+        release: () => {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                free += 1;
+        },
+    };
+}
 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
@@ -180,6 +226,30 @@ export function discoverSkills(agentDir, subdir = "skills") {
  * Returns null rather than throwing on unparseable YAML: a broken shared file
  * must not take down every agent under it.
  */
+/**
+ * AGENTS.md without the block a coding tool reads.
+ *
+ * AGENTS.md is two things in a foldrun folder: the account's (or
+ * workspace's) own context, which every running agent is given, and — the
+ * convention Next.js set — the file a coding agent (Claude Code, Cursor,
+ * Codex) reads before it edits the folder. The CLI writes a short managed
+ * block for the second reader between these markers; it is about editing
+ * the files, not about doing the work, so no running agent is shown it.
+ */
+export const AGENT_RULES_START = "<!-- BEGIN:foldrun-agent-rules -->";
+export const AGENT_RULES_END = "<!-- END:foldrun-agent-rules -->";
+export function withoutAgentRules(body) {
+    let out = body;
+    for (;;) {
+        const start = out.indexOf(AGENT_RULES_START);
+        if (start === -1)
+            return out;
+        const end = out.indexOf(AGENT_RULES_END, start);
+        if (end === -1)
+            return out;
+        out = out.slice(0, start) + out.slice(end + AGENT_RULES_END.length);
+    }
+}
 export function readAgentsMd(dir) {
     // Convert a pre-rename `mdagent_version:` before parsing. One name in the
     // code, one on disk — the reader no longer knows two spellings, so a file
@@ -191,7 +261,7 @@ export function readAgentsMd(dir) {
             continue;
         try {
             const parsed = matter(fs.readFileSync(file, "utf8"));
-            return { data: parsed.data, body: parsed.content.trim() };
+            return { data: parsed.data, body: withoutAgentRules(parsed.content).trim() };
         }
         catch {
             return null;
@@ -209,6 +279,53 @@ const workspaceRootOf = (agentDir) => path.join(agentDir, "..", "..");
  * writing instructions means *as well as*, because an account rule nobody can
  * silently drop is the point of having one.
  */
+/** An agent's own `runtime:` block, else its workspace's (AGENTS.md, the
+ *  Linux Foundation standard name; project.md stays accepted so nothing
+ *  that already exists breaks). */
+function ownRuntime(front, agentDir, tenant) {
+    return parseRuntime(front.runtime) ?? parseRuntime(workspaceFrontmatter(agentDir, tenant).runtime);
+}
+/** What one granted script tool's program needs. */
+function toolRuntime(def) {
+    return def.kind === "script" ? parseRuntime(def.spec.runtime) : null;
+}
+/**
+ * The runtime one agent's steps are built with: its own declaration (else its
+ * workspace's), merged with every script tool it grants. The runner builds
+ * exactly this for a step; the platform builds it ahead of time when the
+ * workspace is deployed, so a package that will not install is reported at
+ * deploy and a scheduled step finds its environment ready. One function, so
+ * the two can never disagree about what an agent needs.
+ */
+export function agentRuntimeSpec(tenant, workspace, agentDir) {
+    const file = path.join(agentDir, "agent.md");
+    if (!fs.existsSync(file))
+        return null;
+    const front = safeMatter(fs.readFileSync(file, "utf8")).data;
+    const available = { ...libraryTools(tenant), ...workspaceTools(tenant, workspace) };
+    const tools = ownToolNames(front)
+        .map((name) => available[name])
+        .filter((def) => Boolean(def))
+        .map(toolRuntime);
+    return mergeRuntimes(ownRuntime(front, agentDir, tenant), ...tools);
+}
+/** Every distinct runtime a workspace's agents need, with who needs it. */
+export function workspaceRuntimePlan(tenant, workspace) {
+    const byFp = new Map();
+    const agentsRoot = path.join(workspaceDir(tenant, workspace), "agents");
+    if (!fs.existsSync(agentsRoot))
+        return [];
+    for (const name of fs.readdirSync(agentsRoot).sort()) {
+        const spec = agentRuntimeSpec(tenant, workspace, path.join(agentsRoot, name));
+        if (!spec)
+            continue;
+        const fp = fingerprint(spec);
+        const entry = byFp.get(fp) ?? { fingerprint: fp, spec, agents: [] };
+        entry.agents.push(name);
+        byFp.set(fp, entry);
+    }
+    return [...byFp.values()];
+}
 function workspaceFrontmatter(agentDir, tenant) {
     return {
         ...(readAgentsMd(accountDir(tenant))?.data ?? {}),
@@ -216,31 +333,60 @@ function workspaceFrontmatter(agentDir, tenant) {
     };
 }
 /**
- * The calendar an agent works to. `timezone:` in AGENTS.md, nearest-wins like
- * every other key there; a flow's cron already means its own timezone, this
- * makes "today" mean it too. Unset is UTC — what the pods run — which for a
- * Sydney desk made an article dated today "one day in the future" until 10am.
- * An unknown name falls back to UTC rather than failing every step.
+ * The calendar a set of frontmatter asks for, with no cascade around it —
+ * one merged record in, one zone out. The full cascade lives in
+ * `agentClock` below and in clock.ts; this is what the account-level parts
+ * of the platform (a wallet's month, a budget window) call.
  */
 export function resolveTimezone(front) {
-    const tz = typeof front.timezone === "string" ? front.timezone.trim() : "";
-    const chosen = tz || process.env.FOLDRUN_TIMEZONE?.trim() || "UTC";
-    try {
-        new Intl.DateTimeFormat("en-CA", { timeZone: chosen });
-        return chosen;
-    }
-    catch {
-        return "UTC";
-    }
+    return resolveClock([{ level: "workspace", value: front.timezone }]).timezone;
+}
+/**
+ * The clock this step works to: agent, then flow, then workspace, then
+ * account, then FOLDRUN_TIMEZONE, then UTC. Nearest wins, and a value that
+ * is not a zone falls through to the next level with a line to say so —
+ * see clock.ts for why this exists at all.
+ */
+export function agentClock(agentDir, tenant, agentFront, flowTimezone) {
+    return resolveClock([
+        { level: "agent", value: agentFront.timezone },
+        { level: "flow", value: flowTimezone },
+        { level: "workspace", value: readAgentsMd(workspaceRootOf(agentDir))?.data?.timezone },
+        { level: "account", value: readAgentsMd(accountDir(tenant))?.data?.timezone },
+    ]);
+}
+/**
+ * The language this step works in: agent, then workspace, then account, then
+ * FOLDRUN_LANGUAGE, then English. The flow level is not read yet — a flow's
+ * timezone: travels through three signatures to get here, and this will
+ * take the same road when a flow needs it.
+ */
+export function agentLanguage(agentDir, tenant, agentFront) {
+    return resolveLanguage([
+        { level: "agent", value: agentFront.language },
+        { level: "workspace", value: readAgentsMd(workspaceRootOf(agentDir))?.data?.language },
+        { level: "account", value: readAgentsMd(accountDir(tenant))?.data?.language },
+    ]);
+}
+/**
+ * The country this step works for, on the same road as the language, then
+ * FOLDRUN_REGION, then whatever the language tag carried (`en-AU` says AU).
+ * Everything a country changes — currency, units, calendar, weekend, text
+ * direction — is derived from it in locale.ts; the three overrides
+ * (`currency:`, `calendar:`, `units:`) are read at the nearest level that
+ * wrote them.
+ */
+export function agentRegion(agentDir, tenant, agentFront, languageTag) {
+    return resolveRegion([
+        { level: "agent", value: agentFront.region },
+        { level: "workspace", value: readAgentsMd(workspaceRootOf(agentDir))?.data?.region },
+        { level: "account", value: readAgentsMd(accountDir(tenant))?.data?.region },
+    ], languageTag);
 }
-/** YYYY-MM-DD in a timezone — the date the workspace believes it is. */
-export function localDate(timeZone, now = new Date()) {
-    return new Intl.DateTimeFormat("en-CA", {
-        timeZone,
-        year: "numeric",
-        month: "2-digit",
-        day: "2-digit",
-    }).format(now);
+export function agentLocaleOverrides(agentDir, tenant, agentFront) {
+    const levels = [agentFront, readAgentsMd(workspaceRootOf(agentDir))?.data ?? {}, readAgentsMd(accountDir(tenant))?.data ?? {}];
+    const pick = (k) => levels.map((l) => l[k]).find((v) => v !== undefined && v !== null && v !== "");
+    return { currency: pick("currency"), calendar: pick("calendar"), units: pick("units") };
 }
 /**
  * The prose from AGENTS.md, outermost first.
@@ -249,6 +395,56 @@ export function localDate(timeZone, now = new Date()) {
  * template as "context every agent here shares" — and never read. Only the
  * frontmatter was, so the instructions people actually wrote reached no model.
  */
+/**
+ * The sub-agents a step may delegate to (`subagents:`), as the SDK will get
+ * them: each resolved through agentContext exactly as its own step would be
+ * (grants only — no runtime; it runs inside its parent's), then cut to what
+ * the parent holds. Problems are lines on the step, never a failed step.
+ */
+export function buildSubagentSpecs(o) {
+    const out = [];
+    const { found, missing } = gatherSubagents(o.workspaceRoot, o.names);
+    for (const m of missing)
+        o.push("error", `subagents: "${m}" is not an agent in this workspace — not delegated to`);
+    for (const sub of found) {
+        if (sub.name === o.self) {
+            o.push("error", `subagents: "${sub.name}" is this agent itself — an agent does not delegate to itself`);
+            continue;
+        }
+        try {
+            const tags = o.tags ?? [];
+            const own = agentContext(sub.dir, o.tenant, tags, { runId: o.runId, agent: sub.name }, o.flowTimezone, true);
+            const description = typeof own.front.description === "string" ? own.front.description.trim() : "";
+            if (!description) {
+                o.push("error", `subagents: "${sub.name}" has no description — the model picks a sub-agent by it; not delegated to`);
+                continue;
+            }
+            const tools = subagentTools(own.allowed, o.parentAllowed);
+            if (!tools.length) {
+                o.push("error", `subagents: "${sub.name}" holds none of its tools inside this step — it can only answer from its prompt (use agents: for that)`);
+            }
+            const body = withoutAgentRules(matter(fs.readFileSync(path.join(sub.dir, "agent.md"), "utf8")).content);
+            out.push({
+                name: sub.name,
+                description,
+                prompt: subagentPrompt({
+                    body: resolveDocLinks(body, o.workspaceRoot),
+                    name: sub.name,
+                    parent: o.self,
+                    workspace: path.basename(o.workspaceRoot),
+                    shared: sharedInstructions(sub.dir, o.tenant),
+                }),
+                tools,
+                disallowedTools: refNames(own.front.disallowedTools),
+                model: own.front.model ? resolveModel(own.front.model) : "inherit",
+            });
+        }
+        catch (err) {
+            o.push("error", `subagents: "${sub.name}" could not be read — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return out;
+}
 export function sharedInstructions(agentDir, tenant) {
     const sections = [
         ["Everyone in this account", readAgentsMd(accountDir(tenant))?.body],
@@ -311,10 +507,9 @@ export function saysUntilMarker(result, until) {
         .some((line) => 
     // Strip markdown emphasis and punctuation from BOTH ends: "**APPROVED.**"
     // is a decision written by someone using bold, not a sentence.
-    line
-        .trim()
-        .replace(/^[#>\-*_`\s]+/, "")
-        .replace(/[.!:,*_`\s]+$/, "")
+    // trimChars, not a `[…]+$` regex: that one is quadratic on a
+    // line of tabs, and this is a line an agent wrote.
+    trimChars(trimChars(line.trim(), "#>-*_`"), ".!:,*_`").trim()
         .toLowerCase() === marker);
 }
 export function resolveDocLinks(text, workspaceRoot) {
@@ -327,8 +522,10 @@ export function resolveDocLinks(text, workspaceRoot) {
     // instruction names needs to say WHERE without naming a file. Added
     // first, so a document that happens to share a folder's name still wins.
     for (const dir of [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"]) {
+        // storage/ and state/ by the one spelling that works in every tool,
+        // the shell included; the rest as they always were.
         if (fs.existsSync(path.join(workspaceRoot, dir)))
-            map.set(norm(dir), `../../${dir}/`);
+            map.set(norm(dir), dir === STORAGE_DIR || dir === "state" ? `workspace/${dir}/` : `../../${dir}/`);
     }
     for (const kind of ["knowledge", "memory"]) {
         const dir = path.join(workspaceRoot, kind);
@@ -373,7 +570,7 @@ export function resolveDocLinks(text, workspaceRoot) {
                 continue;
             }
             const fwd = entry.split(path.sep).join("/");
-            const rel = `../../state/${fwd}`;
+            const rel = `workspace/state/${fwd}`;
             map.set(norm(`state/${fwd}`), rel);
             map.set(norm(fwd), rel);
         }
@@ -385,7 +582,7 @@ export function resolveDocLinks(text, workspaceRoot) {
         // through to the plain-directory walk below.
         const index = JSON.parse(fs.readFileSync(path.join(workspaceRoot, "..", "..", STORAGE_DIR, path.basename(workspaceRoot), "index.json"), "utf8"));
         for (const f of index.files ?? [])
-            map.set(norm(`${STORAGE_DIR}/${f.path}`), `../../${STORAGE_DIR}/${f.path}`);
+            map.set(norm(`${STORAGE_DIR}/${f.path}`), `workspace/${STORAGE_DIR}/${f.path}`);
     }
     catch {
         // no file store index is normal
@@ -404,18 +601,27 @@ export function resolveDocLinks(text, workspaceRoot) {
             const fwd = entry.split(path.sep).join("/");
             if (fwd.startsWith(".store/"))
                 continue;
-            map.set(norm(`${STORAGE_DIR}/${fwd}`), `../../${STORAGE_DIR}/${fwd}`);
-            map.set(norm(fwd), `../../${STORAGE_DIR}/${fwd}`);
+            map.set(norm(`${STORAGE_DIR}/${fwd}`), `workspace/${STORAGE_DIR}/${fwd}`);
+            map.set(norm(fwd), `workspace/${STORAGE_DIR}/${fwd}`);
         }
     }
-    return text.replace(/\[\[([^\]\n]+)\]\]/g, (whole, name) => {
+    // `[` excluded from the name: with it allowed, a run of `[[` makes the
+    // engine re-scan to the end from every opening — quadratic on a result
+    // an agent wrote.
+    return text.replace(/\[\[([^\]\[\n]+)\]\]/g, (whole, name) => {
         const hit = map.get(norm(name.trim()));
         return hit ? `\`${hit}\`` : whole;
     });
 }
 function agentContext(agentDir, tenant, tags = [], 
 /** Who is running, so scripts can stamp what they write with its provenance. */
-identity = {}) {
+identity = {}, 
+/** The flow's own `timezone:`, when this step belongs to one. Between the
+ *  agent's frontmatter and the workspace's AGENTS.md in the cascade. */
+flowTimezone, 
+/** Only what the agent is granted — no runtime prepared. For a sub-agent,
+ *  whose tools are cut to its parent's and run in the parent's runtime. */
+grantsOnly = false) {
     // agentDir is <data>/<tenant>/projects/<workspace>/agents/<agent>, so the
     // workspace a secret should resolve against is two levels up.
     const workspace = path.basename(path.resolve(agentDir, "..", ".."));
@@ -426,12 +632,34 @@ identity = {}) {
     // than implied: told to read `../../knowledge/index.md`, the model asked for
     // `/knowledge/index.md` twice before working it out. Two denials and a turn,
     // for want of one sentence.
+    // The language this step works in, resolved before the prompt is built:
+    // its sentence goes in here, the env the tools read is set below, and the
+    // step prints any level that wrote something unreadable.
+    const language = agentLanguage(agentDir, tenant, front);
+    const region = agentRegion(agentDir, tenant, front, language.language);
+    // The clock is resolved further down for the env; the locale needs its
+    // zone now so "today" in a Jalali or Hijri calendar is today where the
+    // step works, not in UTC.
+    const localeZone = agentClock(agentDir, tenant, front, flowTimezone).timezone;
+    const locale = deriveLocale(language.language, region.region, agentLocaleOverrides(agentDir, tenant, front), localeZone);
+    // Said only when someone set it: an agent that never mentions a language
+    // or a region reads exactly the prompt it always did.
+    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))} ` +
+            `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` +
         `Your working directory is \`agents/${path.basename(agentDir)}/\` inside the ` +
         `\`${workspace}\` workspace. Every path in this prompt is relative to it — ` +
-        `\`outputs/\` is yours, and \`../../\` is the workspace root, so the workspace's ` +
-        `own knowledge is at \`../../knowledge/\`. Absolute paths are outside the ` +
-        `workspace and will be refused.\n\n` +
+        `\`outputs/\` is yours, and \`workspace/\` is the workspace root, in every tool ` +
+        `and in the shell: the shared file store is \`workspace/storage/\`, what runs ` +
+        `carry forward is \`workspace/state/\`. (\`../../\` reaches the same root and ` +
+        `still works, so a path like \`../../knowledge/\` below is \`workspace/knowledge/\`.) ` +
+        `Absolute paths are outside the workspace and will be refused.\n\n` +
         // A flow's whole point is that a later step works on what an earlier one
         // produced, and each agent writes to its own outputs/. A run showed what
         // omitting this costs: the checker looked in its own empty outputs/ and
@@ -452,10 +680,18 @@ identity = {}) {
         // adoptLegacyFilesDir's "move files/ to storage/" is a no-op by the time
         // the run ends — a deliverable written where this text pointed was
         // harvested from nowhere and silently never appeared.
-        `\`../../storage/\` is the workspace file store: anything you leave there is kept ` +
+        `\`workspace/storage/\` is the workspace file store: anything you leave there is kept ` +
         `after the run and shown on the Storage page for people to download. Write ` +
-        `deliverables people asked for — CSVs, reports, PDFs, images — to \`../../storage/\`; ` +
-        `use \`outputs/\` for working text the next step reads.`);
+        `deliverables people asked for — CSVs, reports, PDFs, images — to \`workspace/storage/\`; ` +
+        `use \`outputs/\` for working text the next step reads. ` +
+        // A Glob PATTERN that climbs (`../../storage/draft/*.md`) always answered
+        // "No files found", even when the file was there. On blog-desk that made
+        // every loop pass look like a first pass: the illustrator never saw the
+        // fact-check report, re-picked the cover, and 2 of 3 publish runs failed
+        // (run-munef2am-439a, 2026-09-30). checkPaths now splits such a pattern
+        // into Glob's `path` and the rest; the advice stays, as the plain form.
+        `To look for files there, open a known file with Read by its exact path, or ` +
+        `Glob with \`path: "workspace/storage/..."\` and a pattern like \`*.md\`.`);
     // 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);
@@ -593,7 +829,7 @@ identity = {}) {
     // for it. The difference is that state is small enough that inlining would
     // usually be free — that is a threshold worth adding once there is a real
     // file to size it against, not before.
-    const state = listDir(path.join(agentDir, "..", "..", "state"), "../../state/");
+    const state = listDir(path.join(agentDir, "..", "..", "state"), "workspace/state/");
     if (state.length) {
         parts.push(`# State — what you carry between runs\n\n` +
             `What this workspace keeps across runs: a count, a cursor, where you got to. ` +
@@ -627,17 +863,32 @@ identity = {}) {
     // below. The tool is the unit of code, so its dependencies live in tool.md
     // and travel with it; the agent should not have to repeat them.
     const toolRuntimes = [];
+    // The secrets a granted script tool's file lists (`secrets: [RESEND_API_KEY,
+    // EMAIL_FROM]`): granting the tool grants them, the way an API tool's
+    // referenced credentials always travelled with it. Before, only the
+    // agent's own `secrets:` counted, so an agent that granted desk_email and
+    // declared nothing failed with "RESEND_API_KEY is not set" (strata-desk,
+    // 1 Oct). `proxied` / `materialised` say how, not what, and add nothing.
+    const toolSecrets = [];
+    // Does any granted tool act outside the workspace (`outward: true`)? The
+    // retry policy reads it: see launchStep.
+    let outward = false;
     const grantOwnTool = (name) => {
         const def = available[name];
         if (!def) {
             missingTools.push(name);
             return;
         }
+        if (def.outward)
+            outward = true;
         if (def.kind === "http")
             apis.push(def.spec);
         else if (def.kind === "script") {
             scriptSpecs.push(...parseScripts([def.spec]));
-            const rt = parseRuntime(def.spec.runtime);
+            const listed = def.spec.secrets;
+            if (Array.isArray(listed))
+                toolSecrets.push(...listed.map(String).filter((n) => /^[A-Z][A-Z0-9_]*$/.test(n)));
+            const rt = toolRuntime(def);
             if (rt)
                 toolRuntimes.push(rt);
         }
@@ -681,7 +932,69 @@ identity = {}) {
     //
     // Declared-and-absent is still an error; referenced-and-absent is the API
     // tool's own missingSecrets, reported where the tool is described.
-    const declared = Array.isArray(front.secrets) ? front.secrets.map(String) : [];
+    // `web: {search: …, fetch: …}` name who answers; resolved here, early,
+    // because three later things hang off the answer — the secret the step
+    // must hold, the env the tool reads, and the egress grant for the host.
+    // `web.search` carries the account engine's settings (engines, categories,
+    // safesearch, …) beside the provider name, read off first the way
+    // browse's are, so the provider resolver sees only its own part.
+    const web = webConfig(front, workspaceFrontmatter(agentDir, tenant));
+    const searchRead = readSearchSettings(web.raw.search);
+    const searchChoice = resolveSearch(searchRead.rest, "search");
+    if (searchRead.error)
+        searchChoice.error = searchChoice.error ?? searchRead.error;
+    const fetchChoice = resolveSearch(web.raw.fetch, "fetch");
+    // A remote browser's key is materialised, not proxied: CDP is a websocket
+    // and the wrapper opens the session itself, the way it seeds a cookie.
+    // `web.browse` carries two things in one key: how the browser presents
+    // itself (engine, user agent, device, locale, timezone) and, optionally,
+    // which remote vendor renders the page. Settings are read off first so the
+    // vendor resolver sees only the vendor part, and a block of settings alone
+    // means the account's own browser with those defaults. Nearest wins: the
+    // agent's block, else the workspace's, else the account's — the shape
+    // `provider:` already uses.
+    const browseRead = readBrowseSettings(web.raw.browse);
+    const browseSettings = browseRead.settings;
+    const browseChoice = resolveSearch(browseRead.rest, "browse");
+    if (browseRead.error)
+        browseChoice.error = browseChoice.error ?? browseRead.error;
+    // What the vendor's own session is asked for, checked against what that
+    // vendor offers; a problem is on the record and the session is not sent.
+    const sessionProblems = browseChoice.error ? [] : browseSessionProblems(browseSettings, browseChoice.provider);
+    const browseSession = browseChoice.shape === "direct" && browseChoice.provider && !sessionProblems.length ? browseSettings.vendor_session : undefined;
+    // crawl, map, extract, answer, monitor: a provider each, or foldrun's own.
+    // Same three consequences as a search API — the secret the step holds, the
+    // env the web tool reads, the one host the key may reach.
+    const actionChoices = NEWER_ACTIONS.map((action) => ({ action, ...resolveActionApi(action, web.raw[action]) }));
+    const builtins = [
+        ...(searchChoice.provider && searchChoice.shape !== "direct" && !searchChoice.error ? ["search=WebSearch"] : []),
+        ...(fetchChoice.provider && fetchChoice.shape !== "direct" && !fetchChoice.error ? ["fetch=WebFetch"] : []),
+    ];
+    const webBuiltin = builtins.length ? { FOLDRUN_WEB_BUILTIN: builtins.join(",") } : {};
+    // A direct search API is paid for with the customer's own key, stored
+    // under a fixed vault name (EXA_API_KEY, BRAVE_SEARCH_API_KEY, …). Naming
+    // the API in frontmatter is declaring that secret — nobody should have to
+    // write it twice, and a run that forgot the second line would search
+    // nothing and say so only at the provider.
+    const declared = [
+        ...(Array.isArray(front.secrets) ? front.secrets.map(String) : []),
+        ...toolSecrets,
+        ...actionChoices.flatMap((c) => (c.provider ? [c.secret] : [])),
+        // Your own proxy for a vendor's session: its URL is a secret, declared by
+        // naming it, like a provider's key.
+        ...(browseSession && typeof browseSession.proxy === "object" && browseSession.proxy.own ? [browseSession.proxy.own] : []),
+        ...[searchChoice, fetchChoice, browseChoice].flatMap((c) => {
+            if (c.shape !== "direct" || !c.secret)
+                return [];
+            // Jina's reader answers without a key. Declaring an absent optional
+            // key would fail the step for a credential it never needed.
+            if (c.secretOptional && !getSecret(tenant, c.secret, workspace))
+                return [];
+            return [c.secret];
+        }),
+    ];
+    // One name once, however many places asked for it.
+    declared.splice(0, declared.length, ...new Set(declared));
     const referenced = [...new Set(apis.flatMap(secretsUsedByApi))];
     const { env: secretEnv, from: secretScopes, } = resolveSecrets(tenant, [...new Set([...declared, ...referenced])], workspace);
     const { missing: missingDeclared } = resolveSecrets(tenant, declared, workspace);
@@ -787,15 +1100,8 @@ identity = {}) {
     // Runtime: an agent's own `runtime:` block, else its workspace's. Built once
     // per declaration and cached, so scripts get their dependencies without
     // polluting the host.
-    let runtimeSpec = parseRuntime(front.runtime);
-    if (!runtimeSpec) {
-        // AGENTS.md is the Linux Foundation standard name (60k+ repos, same
-        // nearest-wins cascade we already use); project.md stays accepted so
-        // nothing that already exists breaks.
-        runtimeSpec = parseRuntime(workspaceFrontmatter(agentDir, tenant).runtime);
-    }
     // Plus whatever the tools this agent granted declared for themselves.
-    runtimeSpec = mergeRuntimes(runtimeSpec, ...toolRuntimes);
+    let runtimeSpec = mergeRuntimes(ownRuntime(front, agentDir, tenant), ...toolRuntimes);
     // Execution: a container per run when Docker is available (real isolation),
     // otherwise the host venv path so local development still works.
     const executor = chooseExecutor();
@@ -803,7 +1109,7 @@ identity = {}) {
     let runtimeError = null;
     let exec = null;
     let runtime = { interpreters: {}, env: {}, log: [], error: null };
-    if (executor === "docker") {
+    if (executor === "docker" && !grantsOnly) {
         const image = ensureImage(runtimeSpec);
         runtimeLog.push(...image.log);
         runtimeError = image.error;
@@ -821,22 +1127,103 @@ identity = {}) {
             };
         }
     }
+    else if (isolatedRun() || grantsOnly) {
+        // (A sub-agent's grants are all that is asked of it: it runs inside its
+        // parent's step and runtime.)
+        // The sandbox builds it (run-container.ts, beside pip's network and the
+        // mounted cache); building it here as well was pure waste, and on a
+        // worker image without python it was worse than waste — it logged
+        // "python3 is not available on this host" as an error on every Python
+        // step, above a sandbox build that had succeeded, and sent every reader
+        // of the trace after the wrong machine.
+    }
     else {
         runtime = prepareRuntime(tenant, runtimeSpec);
         runtimeLog.push(...runtime.log);
         runtimeError = runtime.error;
     }
-    // What day it is, in the workspace's own timezone. Not a secret, so it
-    // travels beside secretEnv rather than inside it — a value in there is
-    // redacted from every log line that quotes it.
-    const timezone = resolveTimezone(workspaceFrontmatter(agentDir, tenant));
+    // What day it is, in the calendar this step works to — the agent's own
+    // `timezone:`, else its flow's, else the workspace's, else the account's.
+    // Not a secret, so it travels beside secretEnv rather than inside it — a
+    // value in there is redacted from every log line that quotes it.
+    const clock = agentClock(agentDir, tenant, front, flowTimezone);
+    const timezone = clock.timezone;
     const clockEnv = {
-        TZ: timezone,
+        // The language the agent works in — what the search asks in, the locale
+        // the browser reports, the Accept-Language a fetch sends. Not a secret.
+        FOLDRUN_LANGUAGE: language.language,
+        // The country and what follows from it — web search's gl, a script's
+        // currency. Unset where nobody said, so nothing is invented.
+        ...(region.region ? { FOLDRUN_REGION: region.region } : {}),
+        ...(locale.currency ? { FOLDRUN_CURRENCY: locale.currency } : {}),
+        FOLDRUN_UNITS: locale.units,
+        FOLDRUN_CALENDAR: locale.calendar,
+        ...(locale.dateLocal ? { FOLDRUN_DATE_LOCAL: locale.dateLocal } : {}),
+        FOLDRUN_RTL: locale.direction === "rtl" ? "1" : "0",
+        // TZ is the form the sandbox's shell and Node both read; for a fixed
+        // offset that is not the same string Intl was given (see clock.ts).
+        TZ: clock.tz,
         FOLDRUN_DATE: localDate(timezone),
         // Where the account's own search engine answers, when the install runs
         // one — the `websearch` library tool reads it. Not a secret; rides with
         // the clock so it reaches scripts, the sandbox and verify alike.
         ...(process.env.FOLDRUN_SEARCH_URL ? { FOLDRUN_SEARCH_URL: process.env.FOLDRUN_SEARCH_URL } : {}),
+        // Whose index our web search asks when the agent named a search API.
+        // Unset means the account's own engine. The name, never the key.
+        ...(searchChoice.shape === "direct" && searchChoice.provider
+            ? { FOLDRUN_WEB_SEARCH_VIA: searchChoice.provider, FOLDRUN_WEB_SEARCH_SECRET: searchChoice.secret ?? "" }
+            : {}),
+        // The `web.search` block's SearXNG settings, as defaults the tool reads.
+        ...searchSettingsEnv(searchRead.settings),
+        ...(fetchChoice.shape === "direct" && fetchChoice.provider
+            ? { FOLDRUN_WEB_FETCH_VIA: fetchChoice.provider, FOLDRUN_WEB_FETCH_SECRET: fetchChoice.secret ?? "" }
+            : {}),
+        ...Object.fromEntries(actionChoices.flatMap((c) => (c.provider
+            ? [[`FOLDRUN_WEB_${c.action.toUpperCase()}_VIA`, c.provider], [`FOLDRUN_WEB_${c.action.toUpperCase()}_SECRET`, c.secret]]
+            : []))),
+        // Which actions the web tool may take (`web: {actions: [...]}`); unset is all.
+        ...(web.actions ? { FOLDRUN_WEB_ACTIONS: web.actions.join(",") } : {}),
+        // A model provider's own search or fetch, which the web tool hands over to.
+        ...webBuiltin,
+        // A remote browser: the wrapper connects over CDP to this vendor with
+        // the named key, and the platform leaves the account's pod alone.
+        ...(browseChoice.shape === "direct" && browseChoice.provider
+            ? { FOLDRUN_BROWSER_VENDOR: browseChoice.provider, FOLDRUN_BROWSER_SECRET: browseChoice.secret ?? "" }
+            : {}),
+        // The vendor session's settings (`web.browse.vendor_session:`), as JSON
+        // the tool maps onto that vendor's own option names. Under both names
+        // for one release: a web tool from before the rename reads the old one.
+        ...(browseSession ? { FOLDRUN_BROWSER_VENDOR_SESSION: JSON.stringify(browseSession), FOLDRUN_BROWSER_SESSION: JSON.stringify(browseSession) } : {}),
+        // The `web.browse` block, as defaults the tool reads when the call did
+        // not say otherwise. Env rather than arguments because the tool is a
+        // script the model calls: a default nobody typed should not have to be
+        // typed by the model either.
+        ...(browseSettings.engine ? { FOLDRUN_BROWSER_ENGINE: browseSettings.engine } : {}),
+        ...(browseSettings.user_agent ? { FOLDRUN_BROWSER_USER_AGENT: browseSettings.user_agent } : {}),
+        ...(browseSettings.device ? { FOLDRUN_BROWSER_DEVICE: browseSettings.device } : {}),
+        ...(browseSettings.locale ? { FOLDRUN_BROWSER_LOCALE: browseSettings.locale } : {}),
+        ...(browseSettings.timezone ? { FOLDRUN_BROWSER_TIMEZONE: browseSettings.timezone } : {}),
+        ...(browseSettings.cookies ? { FOLDRUN_BROWSER_COOKIES: browseSettings.cookies } : {}),
+        ...(browseSettings.cookie_domain ? { FOLDRUN_BROWSER_COOKIE_DOMAIN: browseSettings.cookie_domain } : {}),
+        ...(browseSettings.storage ? { FOLDRUN_BROWSER_STORAGE: browseSettings.storage } : {}),
+        ...(browseSettings.storage_origin ? { FOLDRUN_BROWSER_STORAGE_ORIGIN: browseSettings.storage_origin } : {}),
+        // The named identities, as one JSON map the tool picks from by name.
+        ...(browseSettings.identities ? { FOLDRUN_BROWSER_IDENTITIES: JSON.stringify(browseSettings.identities) } : {}),
+        // Only the non-default travels: a window, on a virtual screen if need be.
+        ...(browseSettings.headless === false ? { FOLDRUN_BROWSER_HEADLESS: "0" } : {}),
+        ...(browseSettings.version ? { FOLDRUN_BROWSER_VERSION: browseSettings.version } : {}),
+        ...(browseSettings.live ? { FOLDRUN_BROWSER_LIVE: "1" } : {}),
+        // What the agent may do, from its file: a lock the call cannot widen.
+        ...(browseSettings.allowed_domains ? { FOLDRUN_BROWSER_ALLOWED_DOMAINS: browseSettings.allowed_domains.join(",") } : {}),
+        ...(browseSettings.deny ? { FOLDRUN_BROWSER_DENY: browseSettings.deny.join(",") } : {}),
+        ...(browseSettings.boundaries ? { FOLDRUN_BROWSER_BOUNDARIES: "1" } : {}),
+        ...(browseSettings.init ? { FOLDRUN_BROWSER_INIT: browseSettings.init.join(",") } : {}),
+        ...(browseSettings.extensions ? { FOLDRUN_BROWSER_EXTENSIONS: browseSettings.extensions.join(",") } : {}),
+        ...(browseSettings.webgpu ? { FOLDRUN_BROWSER_WEBGPU: "1" } : {}),
+        ...(browseSettings.ignore_https_errors ? { FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS: "1" } : {}),
+        ...(browseSettings.state_key ? { FOLDRUN_BROWSER_STATE_KEY: browseSettings.state_key } : {}),
+        ...(browseSettings.video ? { FOLDRUN_BROWSER_VIDEO: "1" } : {}),
+        ...(browseSettings.live_view === false ? { FOLDRUN_BROWSER_LIVE_VIEW: "0" } : {}),
     };
     // Scripts declared as tools — callable by name, no bash required.
     const scriptTools = buildScriptTools(agentDir, scriptSpecs, 
@@ -866,7 +1253,7 @@ identity = {}) {
     }
     parts.push("Write deliverables for people to workspace/storage/ (kept and downloadable); write working text for later steps to outputs/; " +
         "what the next run needs goes to workspace/state/. Paths are relative to your agent directory, or start with workspace/ " +
-        "for the workspace root (../../storage/ and workspace/storage/ are the same place). There is no /tmp for you: a " +
+        "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.");
     // The run's one-line summary is the first meaningful line of the last step
     // that produced a result — read, never declared (runSummary in store.ts).
@@ -888,15 +1275,49 @@ identity = {}) {
     const disabled = [];
     const unknownTools = [];
     const shadowed = [];
+    // `web: {search: …, fetch: …}` name who answers. Unset means ours — the
+    // account's own engine, and our own fetch, both inside the run's sandbox
+    // and both on the run record. A model provider's name adds the SDK's
+    // server-side tool beside ours, which the run's endpoint executes: point
+    // the run at z.ai and z.ai's index answers the search. The web tool hands
+    // the action over to it (FOLDRUN_WEB_BUILTIN).
+    const providerWebTools = [];
+    if (browseChoice.error)
+        providerWarnings.push(browseChoice.error);
+    providerWarnings.push(...sessionProblems, ...web.problems, ...actionChoices.flatMap((c) => (c.error ? [c.error] : [])));
+    for (const [choice, builtin] of [
+        [searchChoice, "WebSearch"],
+        [fetchChoice, "WebFetch"],
+    ]) {
+        if (choice.error) {
+            providerWarnings.push(choice.error);
+        }
+        else if (choice.provider && choice.shape !== "direct") {
+            // A provider's server-side tool replaces ours. A direct search API
+            // does not: our tool stays, and reads FOLDRUN_WEB_SEARCH_VIA to know
+            // whose index to ask — through the egress proxy, with the customer's
+            // own key, on the run record.
+            providerWebTools.push(builtin);
+        }
+    }
     let wantSearch = false;
     let wantHistory = false;
     let wantDesks = false;
+    let wantAsk = false;
     for (const ref of toolRefs(front)) {
         const toolName = ref.name;
         if (ref.mode === "ask") {
             disabled.push(toolName);
             continue;
         }
+        // `web` is our own tool, granted with the rest of them above. A model
+        // provider answering search or fetch on its own side (`web: {search:
+        // zai}`) adds that provider's tool beside it; the web tool's search then
+        // names it (FOLDRUN_WEB_BUILTIN) rather than asking our engine.
+        if (toolName === "web" && !ref.linked) {
+            allowed.push(...providerWebTools);
+            continue;
+        }
         // Resolution order: built-in group, exact SDK name, then your own tools.
         // Built-ins win a bare name, because their names are a small fixed set —
         // but a tool hidden by one is worth saying out loud rather than silently
@@ -910,13 +1331,15 @@ identity = {}) {
             if (available[toolName])
                 shadowed.push(toolName);
         }
-        else if (toolName === "search" || toolName === "history" || toolName === "desks") {
+        else if (toolName === "search" || toolName === "history" || toolName === "desks" || toolName === "ask") {
             // 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
                 wantDesks = true;
             if (available[toolName])
@@ -946,8 +1369,8 @@ identity = {}) {
             { label: "memory/", dir: path.join(agentDir, "memory") },
             { label: "../../knowledge/", dir: path.join(wsRoot, "knowledge") },
             { label: "../../memory/", dir: path.join(wsRoot, "memory") },
-            { label: "../../state/", dir: path.join(wsRoot, "state") },
-            { label: `../../${STORAGE_DIR}/`, dir: path.join(wsRoot, STORAGE_DIR) },
+            { label: "workspace/state/", dir: path.join(wsRoot, "state") },
+            { label: `workspace/${STORAGE_DIR}/`, dir: path.join(wsRoot, STORAGE_DIR) },
             { label: "outputs/", dir: path.join(agentDir, "outputs") },
             { label: "[library] knowledge/", dir: libraryDir(tenant, "knowledge") },
             { label: "[library] memory/", dir: libraryDir(tenant, "memory") },
@@ -969,6 +1392,14 @@ identity = {}) {
     const historyTools = wantHistory ? buildHistoryTools(historyDigest) : { server: null, toolNames: [], promptLines: [] };
     const deskTools = wantDesks ? buildDeskTools(deskDigest) : { server: null, toolNames: [], promptLines: [] };
     allowed.push(...searchTools.toolNames, ...historyTools.toolNames, ...deskTools.toolNames);
+    // tools: [ask] — ask_person. Its server is built where the step runs (it
+    // needs the step's emit, and in a pod the proxy's address); here only the
+    // grant, the wait and the prompt's line.
+    const ask = wantAsk ? { timeoutSec: askTimeoutSec(front) } : null;
+    if (ask) {
+        allowed.push(ASK_TOOL);
+        parts.push(`# Asking a person\n\n${askPromptLine(ask.timeoutSec)}`);
+    }
     if (searchTools.promptLines.length || historyTools.promptLines.length || deskTools.promptLines.length) {
         parts.push(`# Finding things\n\n${[...searchTools.promptLines, ...historyTools.promptLines, ...deskTools.promptLines].join("\n")}`);
     }
@@ -988,12 +1419,16 @@ identity = {}) {
     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"),
         allowed: finalAllowed,
         disabled,
         unknownTools,
         shadowed,
         legacyUse,
+        retiredTools: retiredToolNames(front),
         mcpServers,
         mcpNames,
         apiTools,
@@ -1003,19 +1438,21 @@ identity = {}) {
         // than using the servers built here.
         apiSpecs: apis,
         scriptSpecs,
+        outward: outward || scriptSpecs.some((sc) => sc.outward),
         searchRoots,
         historyDigest,
         deskDigest,
         searchTools,
         historyTools,
         deskTools,
+        ask,
         // `spec` is the MERGED declaration — the agent's own block or its
         // workspace's, plus every granted tool's. The isolated path builds its
         // runtime from this; passing the agent's frontmatter alone silently drops
         // what the tools declared, and a tool whose program needs a package it
         // asked for by name fails inside the container with "cannot find" while
         // the host path, which uses this same merged spec, works fine.
-        runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec },
+        runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec, dispose: runtime.dispose },
         secretEnv: { ...runtime.env, ...secretEnv },
         formatWarning: checkFormatVersion(workspaceFrontmatter(agentDir, tenant).foldrun_version).warning,
         providerEnv,
@@ -1023,8 +1460,19 @@ identity = {}) {
         providerSecrets,
         providerWarnings,
         fallbackEnv,
-        translator,
-        fallbackTranslator,
+        region,
+        // Who answers web search and fetch, resolved once up top. The step
+        // needs them again to grant a direct API's key to its host.
+        searchChoice,
+        fetchChoice,
+        actionChoices,
+        web,
+        language,
+        // Stamped with the step's own zone: when one of these refuses, the
+        // reset time it reports is told in the calendar the step works to,
+        // not in the pod's UTC.
+        translator: translator && { ...translator, timezone },
+        fallbackTranslator: fallbackTranslator && { ...fallbackTranslator, timezone },
         apiWarnings,
         secretScopes,
         missingTools,
@@ -1053,9 +1501,9 @@ identity = {}) {
  * Never fails a step: a link is bookkeeping, and a run that did its work must
  * not be marked failed because a URL could not be minted.
  */
-function publishPublicDir(tenant, workspace, push) {
+async function publishPublicDir(tenant, workspace, push) {
     try {
-        const { added } = platform.syncPublicShares(tenant, workspace);
+        const { added } = await platform.syncPublicShares(tenant, workspace);
         if (added.length)
             push("info", `shared: ${added.join(", ")}`);
     }
@@ -1063,15 +1511,112 @@ function publishPublicDir(tenant, workspace, push) {
         push("error", `shares: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-function repriced(catalog, model, usage, sdkCost, push) {
+export function repriced(catalog, model, usage, sdkCost, push, 
+/** The step's turns each priced at its own model — set when a sub-agent
+ *  ran on a different model (ExecOutcome.turnsCostUsd). The lump `usage`
+ *  priced at the step's model would bill those turns at the wrong rate. */
+turnsCostUsd) {
     const known = usage ? catalogCost(catalog, model, usage) : null;
     if (known === null)
         return sdkCost;
+    if (typeof turnsCostUsd === "number") {
+        push("info", `cost from each model turn at its own model's rate: $${turnsCostUsd.toFixed(6)} (sub-agents ran on other models)`);
+        return turnsCostUsd;
+    }
     if (sdkCost !== null && Math.abs(known - sdkCost) > 0.000001) {
         push("info", `cost repriced from the gateway's catalogue: $${known.toFixed(6)} (sdk said $${sdkCost.toFixed(6)})`);
     }
     return known;
 }
+/**
+ * Write one attempt onto the step's history and re-total the step.
+ *
+ * runStep reports the attempt it just ran — its cost, tokens and sandbox
+ * seconds — by assigning the step's fields. Those become this attempt's row;
+ * the step's fields then become the sum of every row, which is what the
+ * run's spend, the flow's budget: and the platform's bill read. A retried
+ * step used to carry only its last attempt's cost, so a `retry: 2` step
+ * could spend three shares while reporting one.
+ */
+export function recordAttempt(step, 
+/** The step's attempt (`attempts`) these rows belong to. */
+attempt, status, startedAt, eventsBefore, 
+/** The attempt re-attached to a sandbox a previous driver left: same
+ *  attempt, so its row is replaced rather than repeated. */
+reattach = false) {
+    const tries = step.tries ?? [];
+    const lastError = step.events
+        .slice(eventsBefore)
+        .filter((e) => e.type === "error")
+        .at(-1)?.text;
+    // Re-attached: the same attempt, so its rows — the last one, and the lost
+    // slim go before it — are replaced, not repeated.
+    const kept = [...tries];
+    const attemptOf = (t) => t.attempt ?? t.n;
+    if (reattach && kept.length && attemptOf(kept.at(-1)) === attempt) {
+        kept.pop();
+        if (kept.length && attemptOf(kept.at(-1)) === attempt && kept.at(-1).status === "lost")
+            kept.pop();
+    }
+    // Tries are numbered in the order they ran: a full re-run after a lost
+    // slim go is the next try, not the same number again (live, 2026-10-01,
+    // both rows read n: 1). `attempt` says which attempt a row belongs to
+    // when its number no longer does.
+    let next = (kept.at(-1)?.n ?? 0) + 1;
+    const numbered = () => {
+        const n = next++;
+        return n === attempt ? { n } : { n, attempt };
+    };
+    // A slim go the browser pod was lost under, before this attempt re-ran
+    // on the full image: its own row, first (runStep set it aside).
+    const lost = step.podLostTry ? [{ ...numbered(), ...step.podLostTry, startedAt }] : [];
+    const row = {
+        ...numbered(),
+        status,
+        costUsd: step.costUsd,
+        tokens: step.tokens ?? null,
+        computeSecs: step.computeSecs ?? null,
+        startedAt: step.podLostTry?.finishedAt ?? startedAt,
+        finishedAt: step.finishedAt ?? new Date().toISOString(),
+        ...(status === "failed" && lastError ? { error: lastError.slice(0, 500) } : {}),
+        ...(step.image?.variant ? { image: step.image.variant } : {}),
+        ...(step.browserPod ? { browserPod: browserPodLine(step.browserPod) } : {}),
+    };
+    delete step.podLostTry;
+    step.tries = [...kept, ...lost, row];
+    const totals = sumAttempts(step.tries);
+    step.costUsd = totals.costUsd;
+    step.tokens = totals.tokens;
+    step.computeSecs = totals.computeSecs;
+}
+/** A question an agent asked mid-step goes where approvals go (the
+ *  workspace's notify:, `awaiting-approval` events), with the way to answer. */
+async function notifyQuestion(tenant, workspace, runId, agent, question, options) {
+    const origin = (process.env.FOLDRUN_PUBLIC_URL ?? "").replace(/\/+$/, "");
+    const where = origin ? `${origin}/dashboard/${encodeURIComponent(workspace)}/runs/${encodeURIComponent(runId)}${tenant !== "default" ? `?tenant=${encodeURIComponent(tenant)}` : ""}` : `run ${runId}`;
+    await sendPlainNotification(tenant, workspace, {
+        event: "awaiting-approval",
+        headline: `${agent} is asking you something`,
+        detail: `${question}${options?.length ? `\n\nOptions: ${options.join(" · ")}` : ""}\n\nAnswer it on ${where}, or \`foldrun answer ${runId} "…"\`.`,
+        runId,
+    }).catch(() => false);
+}
+/** The local stand-in for a person: the terminal, when there is one. */
+async function terminalAsk(question, options) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const list = options?.length ? `\n${options.map((o, i) => `  ${i + 1}. ${o}`).join("\n")}\n` : "";
+        const raw = (await rl.question(`\n  the agent asks: ${question}${list}\n  your answer: `)).trim();
+        const n = Number(raw);
+        return options?.length && Number.isInteger(n) && n >= 1 && n <= options.length ? options[n - 1] : raw || null;
+    }
+    finally {
+        rl.close();
+    }
+}
 async function runStep(agentDir, tenant, step, context, save, modelOverride, tags = [], effortOverride, runId, 
 /** What the previous group returned as DATA (an `output: json` step's
  *  value), beside the prose in `context`. Undefined when nothing did. */
@@ -1079,7 +1624,23 @@ priorData,
 /** The most this step may spend before it is stopped mid-turn: the run's
  *  remaining `budget:`, shared across the steps launched with it. Null
  *  means the flow set no budget. */
-stepBudgetUsd = null) {
+stepBudgetUsd = null, 
+/** Which line set that ceiling, for the error that names it. */
+stepBudgetNote, 
+/** The run is a test run — see test-mode.ts. Read off the run record by
+ *  the caller, never from anything the sandbox could have written. */
+testRun = false, 
+/** Has a person asked for the run to stop? Read on a clock by the
+ *  in-process model loop, so a stop lands mid-step and not at the next
+ *  group. The isolated path needs none: stopRun destroys the sandbox. */
+stopRequested, 
+/** The flow's `timezone:`, for the clock cascade. Undefined for a step
+ *  run outside any flow, which still gets agent → workspace → account. */
+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) {
     // 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` —
@@ -1097,14 +1658,44 @@ stepBudgetUsd = null) {
     // cover a script's own stdout.
     let redactions = [];
     let fileDir = null;
+    let disposeRuntime;
+    // Can this step's tools act outside the workspace? Set once its context is
+    // read; the verdict at the end of this function reads it.
+    let canActOutward = false;
+    const eventsAtStart = step.events.length;
     const redact = (text) => {
         let out = text;
         for (const [value, name] of redactions)
             out = out.split(value).join(`[redacted:${name}]`);
         return out;
     };
+    // The reply, the conclusion and an `output: json` value land on the same
+    // record the events do, and a model that quotes a script's stdout puts
+    // the credential in its answer rather than in a tool event. Same scrub,
+    // same place. The JSON value goes through its text form: a secret inside
+    // a nested field is still a secret, and the key name survives either way.
+    const redactText = (text) => (typeof text === "string" ? redact(text) : text);
+    const redactData = (value) => {
+        if (value === undefined || redactions.length === 0)
+            return value;
+        try {
+            return JSON.parse(redact(JSON.stringify(value)));
+        }
+        catch {
+            return value;
+        }
+    };
     const push = (type, text, extra) => {
-        step.events.push({ t: new Date().toISOString(), type, text: redact(text), ...extra });
+        const t = new Date().toISOString();
+        step.events.push({ t, type, text: redact(text), ...extra });
+        // 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) {
+            applyOperatorEvent(step, extra.operator, t);
+            if (extra.operator.kind === "asked" && runId && !testRun) {
+                void notifyQuestion(tenant, path.basename(path.resolve(agentDir, "..", "..")), runId, step.agent, extra.operator.question, extra.operator.options);
+            }
+        }
         save();
     };
     // The clock on the step itself. `??=` so a retry extends the first
@@ -1122,7 +1713,9 @@ stepBudgetUsd = null) {
             ? fs.readFileSync(stubFile, "utf8").split(/\n---\n/)
             : [`stub result from ${step.agent}`];
         const call = step.events.filter((e) => e.text.startsWith("stub call")).length;
-        push("info", `stub call ${call + 1}`);
+        // The ceiling it was given rides on the line, so the budget arithmetic
+        // around fan-out is testable without a model to stop.
+        push("info", `stub call ${call + 1}${stepBudgetUsd !== null ? ` (ceiling $${stepBudgetUsd.toFixed(2)})` : ""}`);
         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.
@@ -1140,8 +1733,15 @@ stepBudgetUsd = null) {
         // the failure of a step that returned no JSON are testable at no cost.
         if (step.output === "json") {
             const extracted = extractJson(step.result);
-            if (extracted.ok)
+            if (extracted.ok) {
                 step.data = extracted.value;
+                const schema = step.schema ?? (step.schemaPath ? readSchemaFile(path.resolve(agentDir, "..", ".."), step.schemaPath) : null);
+                const errors = schema && looksLikeSchema(schema) ? validateSchema(step.data, schema) : [];
+                if (errors.length) {
+                    push("error", `schema: the value does not fit — ${describeSchemaErrors(errors)}`);
+                    step.status = "failed";
+                }
+            }
             else {
                 push("error", `output: json — ${extracted.reason}`);
                 step.status = "failed";
@@ -1158,7 +1758,9 @@ stepBudgetUsd = null) {
         // step: the generic HTTP tool still works without the typed ones.
         for (const w of await prefetchOpenApi(tenant, openApiSources(agentDir, tenant)))
             push("error", `openapi: ${w}`);
-        const { front, clockEnv, systemPrompt, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size: agentSize, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, translator, fallbackTranslator, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent });
+        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);
+        disposeRuntime = runtime.dispose;
+        canActOutward = outward;
         // 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;
@@ -1168,7 +1770,7 @@ stepBudgetUsd = null) {
         // what crosses into containers, headers and env files is the token. A
         // failed refresh fails the step naming the secret and the provider's
         // reason, which beats a 401 three layers later.
-        const liveSecrets = await materializeSecrets(secretEnv);
+        const liveSecrets = await materializeSecrets(secretEnv, { tenant, workspace: path.basename(workspaceRootOf(agentDir)) });
         // @file values (SSH keys, certs) still carry their content at this point.
         // The in-process branch materialises them to 0600 paths on this host
         // below; the container branch passes the content across and the driver
@@ -1181,18 +1783,31 @@ stepBudgetUsd = null) {
             .map(([name, value]) => [value, name])
             // Longest first, so a value containing another is replaced whole.
             .sort((a, b) => b[0].length - a[0].length);
+        // 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}`);
+        // And one more only when something written could not be read as a zone.
+        for (const problem of clock.problems)
+            push("error", problem);
         if (providerLabel)
             push("info", `provider: ${providerLabel}`);
         for (const w of providerWarnings)
             push("error", w);
+        // A level that wrote a language nobody can read was skipped, not obeyed.
+        for (const l of language.lines)
+            push("info", l);
+        for (const l of region.lines)
+            push("info", l);
         for (const w of apiWarnings)
             push("error", `openapi: ${w}`);
         if (formatWarning)
             push("error", formatWarning);
         if (legacyUse.length)
             push("error", legacyUseError(legacyUse));
+        for (const t of retiredTools)
+            push("error", retiredToolError(t));
         for (const t of unknownTools) {
-            push("error", `tools: "${t}" is not a tool group (web, fetch, read, files, bash, search, history), an SDK tool name, or a tool in this workspace's library — nothing was granted for it`);
+            push("error", `tools: "${t}" is not a tool group (read, write, code, search, history, desks), an SDK tool name, or a tool in this workspace's library — nothing was granted for it`);
         }
         for (const name of mcpNames)
             push("info", `mcp server connected: ${name}`);
@@ -1301,12 +1916,20 @@ stepBudgetUsd = null) {
         fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
         // Expose the workspace's shared scripts/ as ./shared so every agent reaches
         // them by the same path, without each one carrying a copy.
-        // No symlinks into the agent directory — they would recurse into the
-        // workspace's own file listing. Shared paths are resolved by the script
-        // tool layer and described to the agent below.
+        // No permanent symlinks into the agent directory — they would recurse
+        // into the workspace's own file listing. Shared paths are resolved by the
+        // script tool layer and described to the agent below; the one link there
+        // is, `workspace` → the root for the shell, lives only for the length of
+        // a step (executeStep, confine.ts#linkWorkspace).
         // The confinement boundary: agents in a workspace are one team, but the
         // workspace is where isolation is enforced.
         const workspaceRoot = path.resolve(agentDir, "..", "..");
+        // Where a test run's state/ and storage/ writes go, and the line each
+        // one leaves: under the run, beside its archived outputs.
+        const divertFor = (id) => ({
+            to: path.join(workspaceRoot, "runs", id, TEST_WRITES_DIR),
+            note: (rel, summary) => push("info", `test: ${summary}`, { effect: { kind: "diverted", path: rel, summary } }),
+        });
         let prompt = step.instruction
             ? resolveDocLinks(step.instruction, workspaceRoot)
             : "Begin your run now, following your instructions.";
@@ -1323,11 +1946,18 @@ stepBudgetUsd = null) {
         if (step.output === "json") {
             // The contract the runner parses back out — stated in the prompt so
             // the instruction and the parser agree by construction, like delegate:.
+            // The schema, when there is one, is quoted whole: the model that has
+            // to satisfy it should not have to guess it from the field names.
+            const schema = step.schema ?? (step.schemaPath ? readSchemaFile(path.resolve(agentDir, "..", ".."), step.schemaPath) : null);
             prompt +=
                 `\n\n<output>\nThis step returns data. End your reply with exactly one JSON value inside a ` +
                     "```json fenced block — the value the next step will compute on. Prose before it is " +
                     `welcome (lead with a one-line headline); nothing may follow the block. If the instruction ` +
-                    `names fields, use exactly those names.\n</output>`;
+                    `names fields, use exactly those names.` +
+                    (schema && looksLikeSchema(schema)
+                        ? ` The value must satisfy this JSON Schema, and the step fails if it does not:\n${JSON.stringify(schema, null, 2).slice(0, 20_000)}`
+                        : "") +
+                    `\n</output>`;
         }
         if (step.waitFor === "event" && step.eventPayload !== undefined) {
             // Not resolved for links, like the previous step's results: it is
@@ -1377,14 +2007,40 @@ stepBudgetUsd = null) {
         for (const m of missingConsults) {
             push("error", `agents: "${m}" is not an agent in this workspace — no consult tool granted`);
         }
-        const consultNames = consults.length ? [...mcpNames, "foldrun_agents"] : mcpNames;
+        const consultNames = [
+            ...mcpNames,
+            ...(consults.length ? ["foldrun_agents"] : []),
+            ...(ask ? ["foldrun_ask"] : []),
+        ];
+        // 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.
+        const subagents = buildSubagentSpecs({
+            names: front.subagents, self: step.agent, workspaceRoot, tenant, tags, runId, flowTimezone,
+            parentAllowed: [...allowed, ...consultNames.map((n) => `mcp__${n}`)], push,
+        });
+        if (subagents.length) {
+            // The delegation tool itself, granted only when there is someone to
+            // delegate to.
+            allowed.push(DELEGATE_TOOL);
+            for (const s of subagents)
+                push("info", `subagent: ${s.name} — ${s.tools.length ? s.tools.join(", ") : "no tools"}`);
+        }
         // The last provider refusal this step saw, for the fallback decision —
         // watched on both paths, because a refusal reads the same from a pod
         // and from this process.
         let lastRefusal = "";
+        // And WHY it refused, in words, when anything on the way saw the
+        // headers that say so: the translator here, the egress proxy over
+        // there. Kept apart from `lastRefusal` — that one decides whether to
+        // fall back, this one is what a person reads afterwards.
+        let refusalWhy = "";
         const pushWatching = (type, text, extra) => {
             if (type === "error" && isProviderRefusal(text))
                 lastRefusal = text;
+            const why = refusalFromLine(text);
+            if (why)
+                refusalWhy = why;
             push(type, text, extra);
         };
         // The second supply: the block's own fallback when it declared one (a
@@ -1392,6 +2048,51 @@ stepBudgetUsd = null) {
         // fallback), else the platform's, and only for a step riding the
         // platform credential.
         const secondSupply = fallbackEnv ?? (Object.keys(providerEnv).length === 0 ? platformFallbackEnv() : null);
+        // Where this step stands on a second supply, for the refusal sentence.
+        // It starts as the truth before anything has run and becomes
+        // "exhausted" the moment the fallback has had its turn — the owner is
+        // about to remove the OpenRouter fallback, so "none" becomes the normal
+        // reading and has to look like a decision on the page.
+        let supplyState = secondSupply ? "trying" : "none";
+        // The line a person reads when this step ends failed: the reason, if
+        // anything on the way learned one, else the status put into words, and
+        // in every case where the step could go next. Pushed last so it is the
+        // last error event — which is what runFailure, the desks' headlines and
+        // `foldrun report` read.
+        const sayWhy = (status) => {
+            if (status !== "failed" || !lastRefusal)
+                return;
+            const said = Number(lastRefusal.match(/API Error: (\d{3})/)?.[1] ?? NaN);
+            const why = refusalWhy ||
+                explainRefusal({
+                    status: Number.isFinite(said) && isRefusalStatus(said) ? said : 402,
+                    timezone: clock.timezone,
+                });
+            push("error", `${why}${supplyNote(supplyState)}`);
+        };
+        // `schema:` — inline on the step, or a file under the workspace read
+        // now, host-side, so both executors are handed the same document. A
+        // file that cannot be read is a failed step before any model runs:
+        // the contract the author wrote down cannot be checked.
+        const resolvedSchema = step.schema ?? (step.schemaPath ? readSchemaFile(workspaceRoot, step.schemaPath) : null);
+        if (step.schemaPath && resolvedSchema === null) {
+            throw new Error(`schema: ${step.schemaPath} — not a readable JSON or YAML schema under the workspace`);
+        }
+        if (step.maxTurns)
+            push("info", `max_turns: ${step.maxTurns}`);
+        // `limits:` — account, workspace, agent, then this step's option;
+        // nearest wins per key. Enforced in the model loop's hook, on either
+        // path (step-exec.ts), so it is resolved here as plain values.
+        const stepLimits = cascadeLimits([
+            readAgentsMd(accountDir(tenant))?.data?.limits,
+            readAgentsMd(workspaceRootOf(agentDir))?.data?.limits,
+            front.limits,
+            step.limits,
+        ]);
+        const limitOwners = toolOwners(apiTools.owners, scriptSpecs);
+        const limitOpts = Object.keys(stepLimits).length ? { limits: stepLimits, toolOwners: limitOwners } : {};
+        if (limitOpts.limits)
+            push("info", `limits: ${Object.entries(stepLimits).map(([k, n]) => `${k} ${n}`).join(", ")} — per step; a call past one is refused`);
         const isolation = process.env.FOLDRUN_RUN_ISOLATION;
         if (isolatedRun()) {
             // The isolated path: the whole loop — model, built-in tools, scripts —
@@ -1414,24 +2115,44 @@ stepBudgetUsd = null) {
             // before anything is copied in. Null where no proxy is configured
             // (the CLI, a compose install without FOLDRUN_EGRESS_URL), and then
             // everything below materialises exactly as it always did.
-            const grant = { secrets: {} };
+            const grant = { secrets: {}, timezone: clock.timezone };
+            // A direct search API's key: granted to that API's host and no other,
+            // exactly as an http tool's key is granted to its base URL's host. The
+            // script sends the placeholder; the worker fills it on the way out.
+            for (const choice of [searchChoice, fetchChoice]) {
+                if (choice.shape === "direct" && choice.secret && choice.host && choice.secret in liveSecrets) {
+                    addGrant(grant, choice.secret, liveSecrets[choice.secret], choice.host);
+                }
+            }
+            for (const c of actionChoices) {
+                if (c.provider && c.secret in liveSecrets)
+                    addGrant(grant, c.secret, liveSecrets[c.secret], c.host);
+            }
             for (const api of apiSpecs) {
                 const host = hostOf(api.base);
                 if (!host)
                     continue;
                 for (const v of [...Object.values(api.headers), ...Object.values(api.query)]) {
-                    for (const name of placeholderNames(v))
-                        if (name in liveSecrets)
-                            addGrant(grant, name, liveSecrets[name], host);
+                    for (const name of placeholderNames(v)) {
+                        if (!(name in liveSecrets))
+                            continue;
+                        addGrant(grant, name, liveSecrets[name], host);
+                        // Which vault entry this is, so the proxy's record of what the
+                        // far end said lands on the right credential.
+                        (grant.healthKeys ??= {})[name] = healthKey(name, secretScopes[name] === "workspace" ? "workspace" : "account", path.basename(path.resolve(agentDir, "..", "..")));
+                    }
                 }
             }
-            const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant });
+            const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant, test: testRun, ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}) });
             // Which secrets must still be real inside the sandbox: a script tool
             // reads them from its environment, and unless it says `secrets:
             // proxied` it needs the value, not the name. bash is a script by
             // another route. The record says which way it went, and why.
             const materialisers = [
                 ...scriptSpecs.filter((sc) => sc.secrets !== "proxied").map((sc) => sc.name),
+                // web proxies its keys — unless it may browse: a remote browser's key
+                // goes into a websocket, and cookie and login secrets into the page.
+                ...(scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.includes("browse")) ? ["web (browse)"] : []),
                 ...(allowed.includes("Bash") ? ["bash"] : []),
             ];
             const materialise = !lease || materialisers.length > 0;
@@ -1445,14 +2166,35 @@ stepBudgetUsd = null) {
             }
             // Sandbox env for the declared secrets: the value, or its own name as
             // a placeholder that the proxy fills on the way out.
-            const sandboxSecrets = materialise
-                ? liveSecrets
-                : Object.fromEntries(declared.map((name) => [name, `\${${name}}`]));
+            const placeholders = Object.fromEntries(declared.map((name) => [name, `\${${name}}`]));
+            let sandboxSecrets = materialise ? liveSecrets : placeholders;
+            // A test run hands the sandbox no send-capable value. The env var is
+            // still there, reading TEST_MODE_WITHHELD, so a script that never
+            // checked FOLDRUN_TEST_MODE fails at the provider's door with an auth
+            // error — and sends nothing. The script tools say whether the step
+            // has a declared sender (everything withheld) or a declared reader
+            // (nothing withheld); see test-mode.ts for the order.
+            if (testRun && materialise) {
+                const held = withholdSecrets(liveSecrets, {
+                    outward: scriptSpecs.some((sc) => sc.outward),
+                    allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
+                });
+                sandboxSecrets = held.env;
+                for (const name of held.withheld) {
+                    push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
+                }
+            }
+            // On a test run the http tools always go through the proxy as
+            // placeholders, even when a script made the step materialise: the
+            // proxy is where the outward-write policy lives, and a header
+            // carrying TEST_MODE_WITHHELD would only fail where it should have
+            // been sunk or refused.
+            const apiValues = testRun && lease ? placeholders : sandboxSecrets;
             const substitutedApis = apiSpecs.map((api) => ({
                 ...api,
                 headers: Object.fromEntries(Object.entries(api.headers).map(([k, v]) => [
                     k,
-                    v.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => sandboxSecrets[name] ?? whole),
+                    v.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => apiValues[name] ?? whole),
                 ])),
             }));
             // The provider's own key and headers, when the step has a lease: the
@@ -1480,8 +2222,9 @@ stepBudgetUsd = null) {
             const isolatedArgs = (modelEnv, keyName = MODEL_KEY_NAME) => ({
                 workspaceRoot,
                 libraryRoot: libraryDir(tenant),
+                galleryRoot: platform.galleryDir() ?? undefined,
                 // Keys this step's dependency cache. Per-account by design — see
-                // run-container.ts#runtimeCacheDir for why it is not shared.
+                // run-container.ts#runtimeCacheMount for why it is not shared.
                 tenant,
                 input: {
                     agentRel: path.relative(workspaceRoot, agentDir).replaceAll("\\", "/"),
@@ -1498,12 +2241,21 @@ stepBudgetUsd = null) {
                     // field. A tool's own `runtime:` is part of what this step needs.
                     runtime: runtime.spec,
                     consults,
+                    ...(subagents.length ? { subagents } : {}),
                     timeoutSec: step.timeout,
                     budgetUsd: stepBudgetUsd,
+                    budgetNote: stepBudgetNote,
                     price: tokenPrice,
                     verify: step.verify,
                     output: step.output,
+                    schema: resolvedSchema ?? undefined,
+                    maxTurns: step.maxTurns,
+                    ...limitOpts,
                     translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
+                    // Outward steps keep a browser of their own: an executor that
+                    // could browse from the slim image through the account's pod
+                    // leaves them on the full one (browser-pod.ts).
+                    ...(outward ? { outward: true } : {}),
                     // The container sees the workspace at /workspace and the library
                     // at /library; the roots are named host-side and moved here.
                     search: searchRoots.map((r) => ({
@@ -1514,6 +2266,7 @@ stepBudgetUsd = null) {
                     })),
                     history: historyDigest,
                     desks: deskDigest,
+                    ...(ask ? { ask } : {}),
                 },
                 env: Object.fromEntries(Object.entries({
                     // The platform's own model credential, when the agent names no
@@ -1532,12 +2285,16 @@ stepBudgetUsd = null) {
                     FOLDRUN_RUN_ID: runId,
                     FOLDRUN_AGENT: step.agent,
                     FOLDRUN_WORKSPACE: path.basename(workspaceRoot),
+                    ...(testRun ? testModeEnv() : {}),
                     ...sandboxSecrets,
                 }).filter((entry) => typeof entry[1] === "string")),
                 emit: pushWatching,
                 // Stamps the sandbox, so stopping this run can destroy it.
                 runId,
                 size,
+                // A test run's state/ and storage/ changes come out under the run.
+                divert: testRun && runId ? divertFor(runId) : undefined,
+                test: testRun,
                 // Resume: a sandbox a previous driver left running, recorded on the
                 // step. Consumed once — a fresh attempt after this one (a retry, a
                 // fallback) starts its own sandbox.
@@ -1559,8 +2316,39 @@ stepBudgetUsd = null) {
             // attempt holds its own sandbox, so the meter owes the sum.
             const firstArgs = isolatedArgs(platformModelEnv());
             await lease?.commit();
-            let outcome = await runIsolated(firstArgs);
+            let credentialUsed = platformModelCredential();
+            // The arguments of the attempt whose outcome is current — what a
+            // re-run on the full image repeats, on the same model supply.
+            let lastArgs = firstArgs;
+            const runTracked = (a) => {
+                lastArgs = a;
+                return runIsolated(a);
+            };
+            let outcome = await runTracked(firstArgs);
             step.sandbox = null; // whatever happens next starts its own
+            // A 401 from a token that rotated mid-step is not a broken key: the
+            // replacement is already on its way to the mounted file. Wait for it
+            // once, then fall into the same retry the busy case uses.
+            if (outcome.status === "failed" && isAuthRefusal(lastRefusal)) {
+                push("info", `the model credential was refused mid-step — waiting for the refreshed one`);
+                const rotated = await awaitRotatedCredential(credentialUsed);
+                if (rotated) {
+                    push("info", "the credential rotated under this step; retrying on the new one");
+                    credentialUsed = rotated;
+                    lastRefusal = "";
+                    const previous = outcome.timing;
+                    // Build first: isolatedArgs is what re-grants the model key, and
+                    // commit() is what publishes the grant to Redis, where the proxy
+                    // reads it. Committing first sent the revoked token again — every
+                    // rotation retry on 2026-09-22/23 401'd this way.
+                    const retry = isolatedArgs(platformModelEnv());
+                    await lease?.commit();
+                    outcome = withEarlierTiming(await runTracked(retry), previous);
+                }
+                else {
+                    push("info", "the credential did not change — this is the key itself, not a rotation");
+                }
+            }
             for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
                 const wait = backoffMs(n, lastRefusal);
                 push("info", `provider busy (${lastRefusal.slice(0, 60)}) — waiting ${(wait / 1000).toFixed(1)}s, attempt ${n} of ${OVERLOAD_RETRIES}`);
@@ -1571,7 +2359,7 @@ stepBudgetUsd = null) {
                 const previous = outcome.timing;
                 const again = isolatedArgs(platformModelEnv());
                 await lease?.commit();
-                outcome = await runIsolated(again);
+                outcome = await runTracked(again);
                 outcome = withEarlierTiming(outcome, previous);
             }
             // The second supply, tried exactly once, and only when the primary
@@ -1594,29 +2382,81 @@ stepBudgetUsd = null) {
                         .filter((entry) => typeof entry[1] === "string")),
                 };
                 await lease?.commit();
-                outcome = await runIsolated(fallbackArgs);
+                supplyState = "exhausted";
+                outcome = await runTracked(fallbackArgs);
                 // Both attempts held sandboxes; the meter owes the sum. The first
                 // try's pod ran, was billed for by the platform, and must not
                 // vanish from the record because a second try replaced its outcome.
                 outcome = withEarlierTiming(outcome, first);
             }
+            // Slim browsing (browser-pod.ts): the step ran on the slim image and
+            // the account's browser pod went away under it, past the web tool's
+            // reconnects. Reads only — run it again from the start on the full
+            // image, where a browser in the step is always there. Anything
+            // written — fail it, naming what, and leave retry:/on-fail:/a person
+            // to decide; a second go could send or charge twice.
+            step.image = outcome.image ?? null;
+            step.browserPod = outcome.browserPod ? { ...outcome.browserPod } : null;
+            if (outcome.status === "failed" && outcome.browserPod?.lost) {
+                const decision = podLossDecision(outcome.browserPod);
+                if (decision.rerun) {
+                    push("info", decision.note);
+                    const first = outcome;
+                    // The slim go is a try of its own on the record — image slim,
+                    // status lost, its own cost, tokens and sandbox seconds — so the
+                    // run page and `foldrun report` show two tries, slim (lost) then
+                    // full, and the step's totals are the sum of both rows
+                    // (recordAttempt). Live, 2026-10-01, the step showed only the
+                    // full re-run.
+                    step.podLostTry = {
+                        status: "lost",
+                        costUsd: repriced(catalog, wireModel, first.usage ?? null, first.costUsd, push, first.turnsCostUsd),
+                        tokens: first.usage ? { input: first.usage.inputTokens, output: first.usage.outputTokens } : null,
+                        computeSecs: first.timing ? Math.round(first.timing.totalMs) / 1000 : null,
+                        finishedAt: new Date().toISOString(),
+                        error: decision.note.slice(0, 500),
+                        image: "slim",
+                        browserPod: browserPodLine(first.browserPod),
+                    };
+                    const again = { ...lastArgs, input: { ...lastArgs.input, image: "full" }, resume: null };
+                    await lease?.commit();
+                    outcome = await runTracked(again);
+                    step.image = outcome.image ?? { variant: "full", why: "re-run after the browser pod was lost" };
+                    step.browserPod = { ...first.browserPod, fallback: RERAN_ON_FULL };
+                }
+                else {
+                    push("error", decision.message);
+                    step.browserPod = { ...outcome.browserPod, failure: decision.message };
+                }
+            }
             if (lease) {
-                for (const line of await lease.drainLog())
-                    push("info", line);
+                for (const line of await lease.drainLog()) {
+                    // pushWatching, not push: a line the proxy wrote may carry the
+                    // refusal mark, and that sentence is the whole reason the proxy
+                    // reads response headers at all.
+                    if (typeof line === "string")
+                        pushWatching("info", line);
+                    else
+                        pushWatching("info", line.text, { effect: line.effect });
+                }
                 await lease.release();
             }
-            publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            // Nothing a test run left in storage/public/ reached storage/, so
+            // there is nothing to publish — and a share link is an outward act.
+            if (!testRun)
+                await publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            sayWhy(outcome.status);
             step.status = outcome.status;
-            step.result = outcome.result;
-            step.conclusion = outcome.conclusion;
+            step.result = redactText(outcome.result);
+            step.conclusion = redactText(outcome.conclusion);
             step.sandbox = null;
             // The cluster's word on why a sandbox ended without the driver saying
             // so — OOMKilled, Evicted — on the record, where the retry reads it.
             if (outcome.status === "failed" && outcome.reason)
                 push("error", `sandbox ended: ${outcome.reason}`);
             if (outcome.data !== undefined)
-                step.data = outcome.data;
-            step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push);
+                step.data = redactData(outcome.data);
+            step.costUsd = repriced(catalog, wireModel, outcome.usage ?? null, outcome.costUsd, push, outcome.turnsCostUsd);
             step.tokens = outcome.usage
                 ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
                 : null;
@@ -1646,15 +2486,32 @@ stepBudgetUsd = null) {
             step.reserved = { cpus: Number(lim.cpus) || 2, memGiB: gib };
         }
         else {
-            const consultTools = buildConsultTools(consults, { ...process.env, ...liveSecrets, ...providerEnv }, (type, text) => push(type, text));
+            // Same withholding as the sandbox path — the in-process step is what
+            // `foldrun run --test` drives on a laptop, where there is no proxy
+            // and this is the only guard there is.
+            const held = testRun
+                ? withholdSecrets(liveSecrets, {
+                    outward: scriptSpecs.some((sc) => sc.outward),
+                    allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
+                })
+                : { env: liveSecrets, withheld: [] };
+            for (const name of held.withheld) {
+                push("info", `test: ${name} withheld from scripts — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from scripts` } });
+            }
+            const stepSecrets = held.env;
+            const consultTools = buildConsultTools(consults, { ...hostSafeEnv(), ...stepSecrets, ...providerEnv }, (type, text) => push(type, text));
+            // 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;
             // @file secrets become 0600 paths here (host run), cleaned up in the
             // finally — once, however many attempts follow.
-            const mat = materializeFileSecrets(agentDir, liveSecrets);
+            const mat = materializeFileSecrets(agentDir, stepSecrets);
             fileDir = mat.dir;
             const attemptInProcess = (modelEnv) => executeStep({
                 agentDir,
                 workspaceRoot,
                 libraryRoot: libraryDir(tenant),
+                ...(subagents.length ? { subagents } : {}),
                 prompt,
                 model,
                 effort,
@@ -1668,16 +2525,25 @@ stepBudgetUsd = null) {
                     ...(searchTools.server ? { foldrun_search: searchTools.server } : {}),
                     ...(historyTools.server ? { foldrun_history: historyTools.server } : {}),
                     ...(deskTools.server ? { foldrun_desks: deskTools.server } : {}),
+                    ...(askTools ? { foldrun_ask: askTools.server } : {}),
                     ...mcpServers,
                 },
                 // Declared secrets reach the agent's scripts as env vars; the model
-                // only ever sees the variable names, not the values.
-                env: { ...process.env, ...clockEnv, ...mat.env, ...modelEnv },
+                // only ever sees the variable names, not the values. The base is
+                // the allowlisted host environment, not process.env: the SDK's
+                // Bash tool runs with this, and on a platform process.env holds
+                // every tenant's root key and the datastore credentials.
+                env: { ...hostSafeEnv(), ...clockEnv, ...(testRun ? testModeEnv() : {}), ...mat.env, ...modelEnv },
                 timeoutSec: step.timeout,
                 budgetUsd: stepBudgetUsd,
+                budgetNote: stepBudgetNote,
                 price: tokenPrice,
                 verify: step.verify,
                 output: step.output,
+                schema: resolvedSchema ?? undefined,
+                maxTurns: step.maxTurns,
+                ...limitOpts,
+                stopRequested,
                 // What the scripts saw, the verify sees: a flow can then check that
                 // the proof a step left names THIS run, not one that came before —
                 // copy-back never propagates a deletion, so a marker from an earlier
@@ -1687,26 +2553,52 @@ stepBudgetUsd = null) {
                     ...(runId ? { FOLDRUN_RUN_ID: runId } : {}),
                     FOLDRUN_AGENT: step.agent,
                     FOLDRUN_WORKSPACE: path.basename(path.resolve(agentDir, "..", "..")),
-                    ...liveSecrets,
+                    ...(testRun ? testModeEnv() : {}),
+                    ...stepSecrets,
                 },
                 emit: pushWatching,
             });
             // With a translator the step's endpoint is the translator: started
             // here, pointed at by the SDK's env, closed when the attempt ends.
+            // A test run brackets each attempt with a snapshot of state/ and
+            // storage/: the step writes them for real, because there is no
+            // sandbox to write instead, and afterwards what changed is moved
+            // under the run and the originals come back.
             const attemptThrough = async (modelEnv, spec) => {
-                if (!spec)
-                    return attemptInProcess(modelEnv);
-                const t = await startTranslator(spec);
+                const before = testRun ? snapshotDivertedDirs(workspaceRoot) : null;
+                const t = spec ? await startTranslator(spec) : null;
                 try {
-                    return await attemptInProcess({ ...modelEnv, ...t.env });
+                    return await attemptInProcess(t ? { ...modelEnv, ...t.env } : modelEnv);
                 }
                 finally {
-                    for (const line of t.drainLog())
-                        push("info", line.startsWith("translator") ? line : `translator: ${line}`);
-                    await t.close();
+                    if (t) {
+                        for (const line of t.drainLog())
+                            pushWatching("info", line.startsWith("translator") ? line : `translator: ${line}`);
+                        await t.close();
+                    }
+                    if (before && runId) {
+                        const d = divertFor(runId);
+                        restoreDivertedDirs(workspaceRoot, before, d.to, d.note);
+                    }
                 }
             };
+            let credentialUsed = platformModelCredential();
             let outcome = await attemptThrough(providerEnv, translator);
+            // Same rule as the isolated path: a credential that rotated under the
+            // step is waited out and retried before anything else is considered.
+            if (outcome.status === "failed" && isAuthRefusal(lastRefusal)) {
+                push("info", `the model credential was refused mid-step — waiting for the refreshed one`);
+                const rotated = await awaitRotatedCredential(credentialUsed);
+                if (rotated) {
+                    push("info", "the credential rotated under this step; retrying on the new one");
+                    credentialUsed = rotated;
+                    lastRefusal = "";
+                    outcome = await attemptThrough(providerEnv, translator);
+                }
+                else {
+                    push("info", "the credential did not change — this is the key itself, not a rotation");
+                }
+            }
             // Same rule as the isolated path: a busy provider is waited out on
             // the supply it refused from, before any fallback is considered.
             for (let n = 1; n <= OVERLOAD_RETRIES && outcome.status === "failed" && isTransientOverload(lastRefusal); n++) {
@@ -1720,17 +2612,20 @@ stepBudgetUsd = null) {
             // declared or platform second supply.
             if (outcome.status === "failed" && lastRefusal && secondSupply) {
                 push("info", `primary model supply refused (${lastRefusal.slice(0, 80)}) — retrying this step on the fallback provider`);
+                supplyState = "exhausted";
                 outcome = await attemptThrough(secondSupply, fallbackEnv && secondSupply === fallbackEnv ? fallbackTranslator : null);
             }
-            publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            if (!testRun)
+                await publishPublicDir(tenant, path.basename(workspaceRoot), push);
+            sayWhy(outcome.status);
             step.status = outcome.status;
-            step.result = outcome.result;
-            step.conclusion = outcome.conclusion;
+            step.result = redactText(outcome.result);
+            step.conclusion = redactText(outcome.conclusion);
             if (outcome.data !== undefined)
-                step.data = outcome.data;
+                step.data = redactData(outcome.data);
             // A consult's spend belongs to the step that asked.
             const consultCost = consultTools.drainCost();
-            const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push);
+            const stepCost = repriced(catalog, wireModel, outcome.usage, outcome.costUsd, push, outcome.turnsCostUsd);
             step.costUsd = stepCost === null && consultCost === 0 ? null : (stepCost ?? 0) + consultCost;
             step.tokens = outcome.usage
                 ? { input: outcome.usage.inputTokens, output: outcome.usage.outputTokens }
@@ -1752,9 +2647,34 @@ stepBudgetUsd = null) {
         catch {
             // best-effort — a leftover scratch file is swept with the run's outputs
         }
+        try {
+            // A private runtime build (see prepareRuntime) is this step's alone.
+            disposeRuntime?.();
+        }
+        catch {
+            // best-effort — it is in the tmpdir
+        }
     }
     step.finishedAt = new Date().toISOString();
     save();
+    return { actedThenFailedCheck: canActOutward && actedThenFailedCheck(step.events.slice(eventsAtStart)) };
+}
+/**
+ * Did this attempt call its tools and then fail only on the check after —
+ * `verify:`, `output: json`, a schema? For a step whose tools act outward
+ * that is the one failure a retry must not answer: the email went, the post
+ * is up, and the check failing says nothing about whether they happened. A
+ * second attempt sends them again. Read off the attempt's own events, which
+ * both executors write the same way (step-exec.ts): every event a failed
+ * check writes carries `check: true`. It used to read only the LAST error's
+ * wording, and a failed shell verify or judge writes its detail after its
+ * headline — so the step was retried and the email went twice. The wording
+ * is still honoured, for a driver image older than the tag.
+ */
+export function actedThenFailedCheck(events) {
+    if (!events.some((e) => e.type === "tool"))
+        return false;
+    return events.some((e) => e.type === "error" && (e.check === true || /^(verify `|output: json — |schema: the value does not fit)/.test(e.text)));
 }
 // Block until a human approves or rejects the pending steps. Polls the run
 // record — the same file the dashboard writes through the approval API — so
@@ -1855,6 +2775,53 @@ function platformFallbackEnv() {
     }
     return out;
 }
+/**
+ * A 401 the token refresh caused, rather than a key that is simply wrong.
+ *
+ * The refresher on the box turns the long-lived grant into an 8h access
+ * token every four hours, and Anthropic revokes the old one the instant the
+ * new one is minted. The platform reads the credential per step from the
+ * mounted file, which fixed the boot-time copy — but not this: a step
+ * already talking to the API when the rotation lands gets a hard 401
+ * mid-turn, and the replacement does not appear in the mounted file until
+ * the kubelet syncs it, about a minute later.
+ *
+ * That window is narrow and it is not rare. Every 401 on this account in
+ * three weeks of runs fell inside it: 02:07:22 and 02:07:24 against a 02:07
+ * refresh, 22:08:12, 22:08:17, 22:08:30 and 22:09:03 against 22:08. The
+ * desks that lost a run nightly were simply the ones scheduled on the hour
+ * the refresher shares.
+ *
+ * So: on a 401, wait for the file to hold a DIFFERENT credential, then let
+ * the caller retry with it. A token that never changes inside the window is
+ * a key that is actually invalid — no waiting fixes that, and the caller
+ * falls through to the second supply exactly as before. Moving the timer
+ * cannot fix this; a run that takes forty minutes spans any minute chosen.
+ */
+const CREDENTIAL_ROTATION_WAIT_MS = 90_000;
+const CREDENTIAL_POLL_MS = 2_000;
+function isAuthRefusal(text) {
+    return /API Error: 401|access token has (been revoked|expired)/i.test(text);
+}
+/**
+ * Wait, briefly, for the mounted credential to become one we have not
+ * already been refused on. Returns the new value, or null when the window
+ * passes without a change — which is the answer that means "this key is
+ * wrong", not "this key is stale".
+ */
+export async function awaitRotatedCredential(before, now = Date.now, read = () => platformModelCredential(), waitMs = CREDENTIAL_ROTATION_WAIT_MS, pollMs = CREDENTIAL_POLL_MS) {
+    if (!before)
+        return null;
+    const until = now() + waitMs;
+    for (;;) {
+        const current = read();
+        if (current && current !== before)
+            return current;
+        if (now() >= until)
+            return null;
+        await sleep(pollMs);
+    }
+}
 /** A model-call failure the fallback can answer: the primary refusing over
  *  credit, quota or auth — never a failure of the work itself, which would
  *  fail identically anywhere. */
@@ -1865,7 +2832,17 @@ function isProviderRefusal(text) {
     // fallback it could only time out on again. A refusal the fallback can
     // answer is about the ACCOUNT; anything about the work or the sandbox is
     // not, however similar the vocabulary.
-    return /API Error: (401|402|403|429|5\d\d)|credits?\b|quota|billing|insufficient|overloaded/i.test(text);
+    // A subscription's own ceiling is the same kind of refusal, worded
+    // differently: Claude Code on a Max plan answers "You've hit your weekly
+    // limit · resets 5am" with no status code and none of the money words.
+    // On 2026-09-21 every opus-tier step on the account failed on exactly that
+    // sentence while sonnet steps beside them ran fine — the plan has a
+    // separate weekly cap for Opus — and nothing here recognised it, so a
+    // second supply could not have answered even if one had been configured.
+    // It is not transient (isTransientOverload is right to ignore it: the
+    // window is a week), it is the account's supply being exhausted, which is
+    // precisely what the fallback provider is for.
+    return /API Error: (401|402|403|429|5\d\d)|credits?\b|quota|billing|insufficient|overloaded|(weekly|daily|monthly|usage) limit|rate.?limit(ed)?\b.*resets?\b|limit\b.*\bresets?\b/i.test(text);
 }
 /** How many times a busy provider is given another moment, and the longest
  *  any one wait may be. Three is the industry's habit and the point where
@@ -1919,7 +2896,48 @@ export function backoffMs(attempt, text = "", random = Math.random) {
     const base = Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
     return Math.round(base * (0.5 + random() * 0.5));
 }
-function platformModelEnv() {
+/**
+ * The platform's model credential, read at the moment a step needs it.
+ *
+ * It used to come only from this process's environment, which meant the
+ * worker held whatever token it was started with. Refreshing an OAuth token
+ * REVOKES the old one, so a refresh without a restart left every run
+ * answering 401 — on 2026-09-18 that took every desk down for two hours, and
+ * nothing said so until a person read a failed run. The refresher's own
+ * comment had named the fix years of incidents earlier: stop shipping the
+ * token as an env var.
+ *
+ * So: when `FOLDRUN_MODEL_KEY_FILE` names a file (the Kubernetes secret,
+ * mounted rather than injected), it is read fresh every time. The kubelet
+ * updates a mounted secret in place within about a minute of it changing, so
+ * a refreshed token reaches the next step on its own, with no restart, no
+ * timing window, and nothing to skip while work is in flight.
+ *
+ * A missing or empty file falls back to the environment, which is what a
+ * local install, the CLI and every compose setup use.
+ */
+export function platformModelCredential(env = process.env) {
+    const file = env.FOLDRUN_MODEL_KEY_FILE;
+    if (file) {
+        try {
+            const value = fs.readFileSync(file, "utf8").trim();
+            if (value)
+                return value;
+        }
+        catch {
+            // Unreadable is not the same as absent: say so once, then fall back,
+            // because a running platform that cannot read its credential file is a
+            // thing an operator needs to know about before the next step fails.
+            if (!credentialFileWarned) {
+                credentialFileWarned = true;
+                console.warn(`[model] FOLDRUN_MODEL_KEY_FILE=${file} could not be read; falling back to the environment`);
+            }
+        }
+    }
+    return env.CLAUDE_CODE_OAUTH_TOKEN || undefined;
+}
+let credentialFileWarned = false;
+export function platformModelEnv() {
     const { ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, CLAUDE_CODE_OAUTH_TOKEN, 
     // What the tiers mean when the platform's own provider is not Anthropic.
     // These belong to the credential: a base URL pointing at OpenRouter with
@@ -1931,7 +2949,9 @@ function platformModelEnv() {
         ANTHROPIC_API_KEY,
         ANTHROPIC_AUTH_TOKEN,
         ANTHROPIC_BASE_URL,
-        CLAUDE_CODE_OAUTH_TOKEN,
+        // The file wins when there is one: it is the live secret, and this
+        // process's copy is whatever it was handed at boot.
+        CLAUDE_CODE_OAUTH_TOKEN: platformModelCredential() ?? CLAUDE_CODE_OAUTH_TOKEN,
         ANTHROPIC_DEFAULT_HAIKU_MODEL,
         ANTHROPIC_DEFAULT_SONNET_MODEL,
         ANTHROPIC_DEFAULT_OPUS_MODEL,
@@ -1979,21 +2999,34 @@ function jsonItems(data, step, take) {
 function csvItems(workspaceDir, step, take) {
     const raw = step.eachPath ?? "";
     if (!raw) {
-        step.skipReason = "each: rows needs a path — `each: rows of ../../storage/x.csv`";
+        step.skipReason = "each: rows needs a path — `each: rows of workspace/storage/x.csv`";
         return [];
     }
-    const resolved = path.resolve(workspaceDir, "agents", step.agent, raw);
-    if (!resolved.startsWith(path.resolve(workspaceDir) + path.sep)) {
-        step.skipReason = `each: rows — ${raw} is outside this workspace`;
+    const read = csvDataRows(workspaceDir, step.agent, raw);
+    if ("problem" in read) {
+        step.skipReason = `each: rows — ${read.problem}`;
         return [];
     }
+    return read.data.slice(0, take).map((r) => `${read.header}\n${r}`);
+}
+/**
+ * The data rows of a CSV, path agent-relative like every path in a flow and
+ * confined to the workspace. Shared by `each: rows of`, which fans out over
+ * them, and `when: rows of`, which asks only whether there are any.
+ */
+function csvDataRows(workspaceDir, agent, raw) {
+    // `workspace/storage/x.csv` from the workspace root, anything else from
+    // the agent's folder (`../../storage/x.csv` is the same file).
+    const resolved = resolveAgentPath(workspaceDir, path.join(workspaceDir, "agents", agent), raw);
+    if (!resolved.startsWith(path.resolve(workspaceDir) + path.sep)) {
+        return { problem: `${raw} is outside this workspace` };
+    }
     let text;
     try {
         text = fs.readFileSync(resolved, "utf8");
     }
     catch {
-        step.skipReason = `each: rows — ${raw} does not exist (yet?)`;
-        return [];
+        return { problem: `${raw} does not exist (yet?)` };
     }
     // Minimal CSV: quoted fields with embedded commas/newlines survive.
     const rows = [];
@@ -2027,18 +3060,39 @@ function csvItems(workspaceDir, step, take) {
     if (row + field)
         rows.push(row + field);
     const [header, ...data] = rows.filter((r) => r.trim() !== "");
-    if (!header || data.length === 0) {
-        step.skipReason = `each: rows — ${raw} has no data rows`;
-        return [];
+    if (!header || data.length === 0)
+        return { problem: `${raw} has no data rows` };
+    return { header, data };
+}
+/**
+ * `schema: <path>` — the file, read and parsed, or null. Agent-relative like
+ * every other path in a flow (`workspace/schemas/lead.json`), confined to the
+ * workspace: a schema is the author's document, never something a step
+ * can point outside.
+ */
+export function readSchemaFile(workspaceRoot, rel) {
+    const root = path.resolve(workspaceRoot);
+    // Written `workspace/schemas/x.json`, agent-relative (`../../schemas/x.json`)
+    // or workspace-relative (`schemas/x.json`); all land on the same file.
+    const candidates = [path.resolve(root, rel.replace(/^((\.\.\/){2}|workspace\/)/, "")), path.resolve(root, "agents", "x", rel)];
+    for (const abs of candidates) {
+        if (abs !== root && !abs.startsWith(root + path.sep))
+            continue;
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+            continue;
+        const parsed = parseSchemaText(fs.readFileSync(abs, "utf8"));
+        return "problem" in parsed ? null : parsed.schema;
     }
-    return data.slice(0, take).map((r) => `${header}\n${r}`);
+    return null;
 }
-export function createFlowRun(tenant, workspace, steps, flowName, status, tags = []) {
+export function createFlowRun(tenant, workspace, steps, flowName, status, tags = [], startedBy = null, opts = {}) {
     const run = {
         id: `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
         flow: flowName,
         tags,
         status,
+        ...(startedBy ? { startedBy: startedBy.trim().toLowerCase() } : {}),
+        ...(opts.test ? { test: true } : {}),
         startedAt: new Date().toISOString(),
         finishedAt: null,
         steps: steps.map((s) => ({
@@ -2068,6 +3122,11 @@ export function createFlowRun(tenant, workspace, steps, flowName, status, tags =
             preview: s.preview,
             delegate: s.delegate,
             output: s.output,
+            schema: s.schema,
+            schemaPath: s.schemaPath,
+            parallel: s.parallel,
+            maxTurns: s.maxTurns,
+            limits: s.limits,
             attempts: 0,
             status: "pending",
             events: [],
@@ -2093,8 +3152,8 @@ export function createFlowRun(tenant, workspace, steps, flowName, status, tags =
     }
     return run;
 }
-export function startFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = [], effortOverride) {
-    const run = createFlowRun(tenant, workspace, steps, flowName, "running", tags);
+export function startFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = [], effortOverride, startedBy = null, opts = {}) {
+    const run = createFlowRun(tenant, workspace, steps, flowName, "running", tags, startedBy, opts);
     void driveRun(tenant, workspace, run, modelOverride, tags, { effortOverride });
     return run;
 }
@@ -2202,6 +3261,19 @@ export function driveRun(tenant, workspace, run, modelOverride, tags = [], opts
 }
 function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
     const effortOverride = opts.effortOverride ?? null;
+    // The flow's own calendar. Read from the flow file rather than passed in,
+    // so every door into a run — the queue, an eval, the CLI, a rerun, a
+    // reconcile that picks an abandoned run back up — gets the same clock
+    // without each caller having to remember it. A run that belongs to no
+    // flow (an ad-hoc agent run) finds nothing here and cascades from the
+    // agent to the workspace, which is what it should do.
+    let flowTimezone = null;
+    try {
+        flowTimezone = readFlow(tenant, workspace, run.flow)?.timezone ?? null;
+    }
+    catch {
+        // an unreadable flow file is reported where it is parsed for real
+    }
     const pDir = workspaceDir(tenant, workspace);
     const runRoot = pDir;
     /**
@@ -2381,6 +3453,19 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
             // is assembled) keeps the newest: when the total is over it, the
             // oldest groups are dropped whole before anything is cut mid-text.
             const contextBefore = (gi) => joinEarlierGroups(groupResults, gi);
+            // What `when:` and `case:` read: the PREVIOUS group's result alone —
+            // the nearest earlier group that produced one, so a routed-past group
+            // between is looked through rather than read as silence. The prompt
+            // gets every earlier group joined (contextBefore); routing must not,
+            // because a verdict two groups back would still open a gate a later
+            // group had overruled: a classifier's BUG line matched a `case: BUG`
+            // three groups on, after the debugger had already answered it.
+            const routingBefore = (gi) => {
+                for (let i = gi - 1; i >= 0; i--)
+                    if (groupResults[i])
+                        return groupResults[i];
+                return null;
+            };
             // The data half of the same handoff: what the nearest earlier group
             // returned through `output: json`. Rebuilt from the record rather than
             // kept only in memory, so a resumed run hands step 3 the value step 1
@@ -2444,8 +3529,11 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 const group = ordered[gi];
                 context = contextBefore(gi);
                 ctxData = dataBefore(gi);
-                if (run.budgetUsd && runCost(run) >= run.budgetUsd && group.some((s) => s.status === "pending")) {
-                    const spent = runCost(run);
+                // What the run has spent, not just what its tokens cost: on an
+                // install that prices sandbox seconds, a step that called no model
+                // still spent money, and a cap that ignored it capped nothing.
+                if (run.budgetUsd && platform.runSpend(run) >= run.budgetUsd && group.some((s) => s.status === "pending")) {
+                    const spent = platform.runSpend(run);
                     const last = run.steps.findLast((s) => s.status === "completed" || s.status === "failed") ?? run.steps[0];
                     last?.events.push({
                         t: new Date().toISOString(),
@@ -2531,6 +3619,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         t: new Date().toISOString(),
                         type: "info",
                         text: `fan-out: ${used.length} instance${used.length === 1 ? "" : "s"}` +
+                            (step.parallel && step.parallel < used.length ? `, ${step.parallel} at a time (parallel:)` : "") +
                             (dropped ? ` (more items existed — capped at ${cap})` : ""),
                     });
                     const at = run.steps.indexOf(step);
@@ -2545,6 +3634,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         result: null,
                         costUsd: null,
                         attempts: 0,
+                        tries: undefined,
                     }));
                     run.steps.splice(at + 1, 0, ...instances);
                     ordered = orderedGroups();
@@ -2557,12 +3647,25 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // this is what keeps the *next* group from starting.
                 const stopCheck = readRun(tenant, workspace, run.id);
                 if (stopCheck?.stopRequested) {
+                    let skipped = 0;
                     for (const s of run.steps) {
                         if (s.status === "pending" || s.status === "running") {
                             s.status = "skipped";
                             s.skipReason = "run stopped";
+                            skipped += 1;
                         }
                     }
+                    // Say so on the trail. stopRun wrote "run stopped" onto the
+                    // record's first step, but the save() below writes this process's
+                    // copy of the record over it, so the only witness was the
+                    // stopRequested flag — and a run that "failed" with no error line
+                    // anywhere took a code read to explain (rank-desk, 2026-09-13).
+                    const witness = run.steps.findLast((s) => s.status === "completed" || s.status === "failed") ?? run.steps[0];
+                    witness?.events.push({
+                        t: new Date().toISOString(),
+                        type: "info",
+                        text: `run stopped by a person between groups — ${skipped} remaining step${skipped === 1 ? "" : "s"} skipped`,
+                    });
                     run.status = "failed";
                     run.stopRequested = true;
                     save();
@@ -2597,39 +3700,66 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     break;
                 }
                 const ctx = context;
-                // `when:` — skip a step whose condition isn't met by prior results.
+                // The previous group's result — see routingBefore.
+                const routing = routingBefore(gi);
+                // `when:` — skip a step whose condition isn't met by the previous
+                // group's result.
                 for (const step of freshGroup) {
                     if (step.status !== "pending" || !step.when)
                         continue;
-                    const met = (ctx ?? "").toLowerCase().includes(step.when.toLowerCase());
+                    // `when: rows of <csv>` asks the data, not the prose: run only if
+                    // the file has a data row. It is the condition a fan-out's
+                    // followers need — an `each:` over an empty file skips itself but
+                    // leaves nothing for a marker to be read from, so the steps after
+                    // it used to run on nothing.
+                    const rowsOf = whenRowsPath(step.when);
+                    if (rowsOf !== null) {
+                        const read = csvDataRows(pDir, step.agent, rowsOf);
+                        if ("problem" in read) {
+                            step.status = "skipped";
+                            step.skipReason = `condition not met: when rows — ${read.problem}`;
+                            step.events.push({ t: new Date().toISOString(), type: "info", text: `skipped — ${read.problem}` });
+                        }
+                        continue;
+                    }
+                    // A marker at the start of a line, not a word anywhere in the
+                    // prose — see markerPresent. "There are no BLOCKED items" must
+                    // not open a gate keyed on BLOCKED.
+                    const met = markerPresent(routing, step.when);
                     if (!met) {
                         step.status = "skipped";
                         step.skipReason = `condition not met: when "${step.when}"`;
                         step.events.push({
                             t: new Date().toISOString(),
                             type: "info",
-                            text: `skipped — previous results do not mention "${step.when}"`,
+                            text: `skipped — the previous group's result has no line beginning "${step.when}" (when: reads a marker at the start of a line of the previous result, not a word in a sentence)`,
                         });
                     }
                 }
                 save();
                 // `case:`/`else:` — exclusive routing. Of this group's case steps,
-                // the FIRST whose text appears in the previous results runs; the
-                // rest are routed past. `else:` runs only when no case matched.
+                // the FIRST whose marker leads a line of the previous results runs;
+                // the rest are routed past. `else:` runs only when no case matched.
                 // (`when:` above stays independent — every matching when runs —
                 // which is why routing is its own vocabulary instead of a mode.)
+                //
+                // Same marker rule as `when:`, and it matters more here: routing is
+                // exclusive, so a label matched out of a sentence does not merely
+                // run an extra step, it sends the flow down the wrong branch and
+                // skips the right one. "This is not a COMPLAINT, it is a QUESTION"
+                // used to route to the complaints handler.
                 const caseSteps = freshGroup.filter((s) => s.status === "pending" && s.case);
                 if (caseSteps.length || freshGroup.some((s) => s.status === "pending" && s.else)) {
                     let matchedCase = null;
                     for (const step of caseSteps) {
-                        if (!matchedCase && (ctx ?? "").toLowerCase().includes(step.case.toLowerCase())) {
+                        if (!matchedCase && markerPresent(routing, step.case)) {
                             matchedCase = step;
                             continue;
                         }
                         step.status = "skipped";
                         step.skipReason = matchedCase
                             ? `routed past — "${matchedCase.case}" matched first`
-                            : `case not matched: "${step.case}"`;
+                            : `case not matched: the previous group's result has no line beginning "${step.case}"`;
                         step.events.push({
                             t: new Date().toISOString(),
                             type: "info",
@@ -2671,6 +3801,20 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         });
                     }
                     run.status = "awaiting-approval";
+                    // approve_within: — the deadline is stamped when the gate opens,
+                    // not counted from the run's start, so "two days to answer" means
+                    // two days from being asked however long the work before it took.
+                    // Only a gate that asks a PERSON gets one: an external event has
+                    // no one to chase.
+                    const within = readFlow(tenant, workspace, run.flow)?.approveWithin ?? null;
+                    // Always assigned, never only set: a run with two gates would
+                    // otherwise carry the FIRST gate's deadline into the second, and
+                    // a deadline already in the past expires a gate the moment it
+                    // opens. Null when this gate has none.
+                    run.approveBy =
+                        within && needsApproval.some((s) => s.waitFor !== "event")
+                            ? new Date(Date.now() + within * 1000).toISOString()
+                            : null;
                     save();
                     // The gate's declared preview, resolved now against what the run
                     // has actually produced — a glob at park time, a list of files on
@@ -2743,9 +3887,50 @@ 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");
-                const ceilingUsd = stepCeiling(run.budgetUsd, runCost(run), launching.length);
+                // 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]));
+                // The ceiling each attempt now running was given. A step records its
+                // cost only when it ends, so while it runs its ceiling stands in for
+                // what it may yet spend — otherwise every fan-out copy of one agent
+                // saw none of its siblings' spend and got the agent's whole budget.
+                const reserved = new Map();
+                // The ceiling for one attempt of one step, read NOW: what is left of
+                // the run's budget shared across the group, or the agent's own cap
+                // less what its steps have cost or hold in flight, shared with its
+                // steps in this group still waiting to start. Computed before every
+                // attempt, not once before the loop — a retry's share is what is left
+                // after the failed attempt spent, and the step's own figure already
+                // carries that spend (it is the sum of its tries).
+                const ceilingFor = (step) => stepCeilingFor(stepCeiling(run.budgetUsd, platform.runSpend(run), launching.length), agentBudgets.get(step.agent), run.steps
+                    .filter((s) => s.agent === step.agent)
+                    .reduce((sum, s) => sum + (s.costUsd ?? 0) + (s !== step && s.status === "running" ? (reserved.get(s) ?? 0) : 0), 0), step.agent, 1 + launching.filter((s) => s !== step && s.agent === step.agent && s.status === "pending" && !reserved.has(s)).length);
+                // parallel: — the instances of one fan-out template share a pool.
+                // Keyed by what the instances share (agent + instruction), since
+                // the template itself is behind them in the record as "expanded".
+                const pools = new Map();
+                const poolFor = (step) => {
+                    if (!step.parallel || !step.item)
+                        return null;
+                    const key = `${step.agent}\u0000${step.instruction}`;
+                    let pool = pools.get(key);
+                    if (!pool)
+                        pools.set(key, (pool = slotPool(step.parallel)));
+                    return pool;
+                };
                 await Promise.all(launching
                     .map(async (step) => {
+                    const pool = poolFor(step);
+                    if (pool)
+                        await pool.acquire();
+                    try {
+                        await launchStep(step);
+                    }
+                    finally {
+                        pool?.release();
+                    }
+                }));
+                async function launchStep(step) {
                     const attempts = (step.retry ?? 0) + 1;
                     // A step re-attaching to its sandbox is still on the attempt
                     // that started it; a step re-run after a backoff picks up the
@@ -2753,19 +3938,83 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     const interruptedInBackoff = !step.sandbox && !!step.attempts && /retrying in \d+s/.test(step.events[step.events.length - 1]?.text ?? "");
                     const from = step.sandbox ? Math.max(1, step.attempts ?? 1) : interruptedInBackoff ? Math.min(attempts, step.attempts + 1) : 1;
                     for (let attempt = from; attempt <= attempts; attempt++) {
+                        const ceiling = ceilingFor(step);
+                        // Nothing left is a refusal, not "no ceiling": a zero passed
+                        // down would read as unset, and the one step that must not
+                        // run would run with no cap at all. On a retry this is what
+                        // stops the second attempt spending a share the first one
+                        // already spent.
+                        if (ceiling.ceilingUsd === 0) {
+                            step.status = "failed";
+                            step.events.push({
+                                t: new Date().toISOString(),
+                                type: "error",
+                                text: attempt === from
+                                    ? `over budget — nothing left to spend before this step (${ceiling.note}); it was not started`
+                                    : `over budget — nothing left to spend for attempt ${attempt} (${ceiling.note}); not retried`,
+                            });
+                            save();
+                            return;
+                        }
+                        // Re-attaching to a sandbox is the same attempt, so its row
+                        // is replaced; anything else is a new row, a loop cycle's
+                        // re-run included.
+                        const reattach = !!step.sandbox;
+                        const attemptStartedAt = new Date().toISOString();
+                        const eventsBefore = step.events.length;
                         step.attempts = attempt;
                         step.status = "running";
+                        if (ceiling.ceilingUsd !== null)
+                            reserved.set(step, ceiling.ceilingUsd);
                         save();
-                        await runStep(path.join(pDir, "agents", step.agent), tenant, step, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, ceilingUsd);
+                        const verdict = await runStep(path.join(pDir, "agents", step.agent), tenant, step, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, ceiling.ceilingUsd, ceiling.note, run.test === true, 
+                        // save() merges a stop written by another process into
+                        // this record; the model loop polls this on a clock.
+                        () => {
+                            save();
+                            return run.stopRequested === true;
+                        }, flowTimezone, run.steps.indexOf(step)).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;
+                        recordAttempt(step, attempt, outcome === "completed" ? "completed" : "failed", attemptStartedAt, eventsBefore, reattach);
+                        save();
+                        // A stop destroys the step's sandbox, which reads here as a
+                        // failed attempt. stopRun writes "stopped by a person" onto
+                        // this step in the record, and the save() above writes this
+                        // process's copy over it — so the trail ended on the
+                        // sandbox's own last words, "sandbox ended: Error (exit 143)",
+                        // and a person's stop read as the platform killing a healthy
+                        // step (abandon-desk, 2026-09-29: stopped from the CLI after
+                        // ten minutes, then chased as an unexplained kill). Say so,
+                        // whether or not a retry was left.
+                        if (outcome === "failed" && run.stopRequested) {
+                            step.events.push({
+                                t: new Date().toISOString(),
+                                type: "info",
+                                text: "stopped by a person mid-step — its sandbox was destroyed, which is what ended this attempt; not retried",
+                            });
+                            save();
+                            break;
+                        }
                         if (outcome !== "failed" || attempt === attempts)
                             break;
-                        // A stop destroys the step's sandbox, which reads here as a
-                        // failed attempt — and a failed attempt used to be retried in
-                        // a fresh sandbox, so a stopped `retry: 2` step ran twice
-                        // more. save() merges the flag from the record.
+                        // An outward step whose tools ran and whose check then failed
+                        // is not retried: the check cannot say the send did not
+                        // happen, and a retry would do it twice.
+                        if (verdict?.actedThenFailedCheck) {
+                            step.events.push({
+                                t: new Date().toISOString(),
+                                type: "info",
+                                text: `not retried — this step's tools can act outside the workspace and ran before the check failed; another attempt could repeat what they did (${attempts - attempt} left unused)`,
+                            });
+                            save();
+                            break;
+                        }
+                        // A failed attempt used to be retried in a fresh sandbox even
+                        // after a stop, so a stopped `retry: 2` step ran twice more.
+                        // The check above ends the loop on a stop; this one covers a
+                        // stop that lands while the outward check was being written.
                         save();
                         if (run.stopRequested)
                             break;
@@ -2807,7 +4056,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             break;
                         }
                     }
-                }));
+                }
                 // on-fail: another agent takes the step over. Sequential and rare:
                 // the rescue is a second full attempt at the step's job with the
                 // failure in front of it, and its success is the step's success —
@@ -2859,7 +4108,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     rescue.attempts = 1;
                     rescue.status = "running";
                     save();
-                    await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData);
+                    await runStep(rescuerDir, tenant, rescue, ctx, save, modelOverride, tags, effortOverride, run.id, ctxData, null, undefined, run.test === true, undefined, flowTimezone, run.steps.indexOf(rescue));
                     // runStep mutates rescue.status; widen past TS's "running" narrowing.
                     const rescueOutcome = rescue.status;
                     if (rescueOutcome === "completed") {
@@ -2992,16 +4241,25 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
         }
         catch (err) {
             run.status = "failed";
+            const text = err instanceof Error ? err.message : String(err);
+            let told = false;
             run.steps.forEach((s) => {
                 if (s.status === "running") {
                     s.status = "failed";
-                    s.events.push({
-                        t: new Date().toISOString(),
-                        type: "error",
-                        text: err instanceof Error ? err.message : String(err),
-                    });
+                    s.events.push({ t: new Date().toISOString(), type: "error", text });
+                    told = true;
                 }
             });
+            // Thrown between groups, with nothing running: the error still has to
+            // land on some step's trail, or the run reads as failed for no reason.
+            if (!told) {
+                const witness = run.steps.findLast((s) => s.status !== "pending") ?? run.steps[0];
+                witness?.events.push({
+                    t: new Date().toISOString(),
+                    type: "error",
+                    text: `run failed between steps: ${text}`,
+                });
+            }
         }
         finally {
             if (!parked) {
@@ -3012,6 +4270,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // learn, and the runs list and the notification stop having to say
                 // only "completed".
                 run.summary = runSummary(run);
+                // Read before a test run's prefix goes on the summary, which would
+                // otherwise hide the word it leads with.
+                run.verdict = verdictOf(run.summary);
+                // A test run's headline says so wherever the headline goes — the
+                // runs list, the history tool, a later run's recall.
+                if (run.test && run.summary)
+                    run.summary = testHeadline(run.summary);
                 // Archive before the next run resets outputs/ — a failed run's
                 // artifacts are usually the most interesting ones, so this runs on
                 // failure too.
@@ -3049,17 +4314,6 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
         }
     })();
 }
-function readFlow(tenant, workspace, flowName) {
-    const dir = path.join(workspaceDir(tenant, workspace), "flows");
-    if (!fs.existsSync(dir))
-        return null;
-    for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
-        const flow = parseFlow(f, fs.readFileSync(path.join(dir, f), "utf8"));
-        if (flow.name === flowName)
-            return flow;
-    }
-    return null;
-}
 // Splice `[[flow:other]]` steps into the parent's step list, renumbering
 // groups so the nested flow's own parallelism survives. Depth-limited, and
 // a cycle raises rather than expanding forever.