@foldrun/core 0.3.0 → 0.5.0

package/dist/src/step-exec.js

@@ -8,10 +8,39 @@
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { spawn } from "node:child_process";
-import { checkPaths, checkBash, isFilesystemTool } from "./confine.js";
+import { checkPaths, checkBash, isFilesystemTool, linkWorkspace, workspaceLinkEnv, resolveAgentPath, isWithin } from "./confine.js";
+import { DELEGATE_TOOLS, subagentGuard, toAgentDefinitions } from "./subagents.js";
+import { hostSafeEnv } from "./host-env.js";
+import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.js";
+import { CallCounter, limitKeysFor } from "./limits.js";
+import { classifyCall, podAt, readPodEvents } from "./browser-pod.js";
+/** How often the stop flag is read while a step runs. */
+export const STOP_POLL_MS = 2000;
+/** The least a `verify:` gets when the step used up most of its `timeout:` —
+ *  capped by the timeout itself, so the step and its check together never
+ *  run past timeout + this. Under the isolated path's backstop (+60 s). */
+export const VERIFY_FLOOR_MS = 30_000;
+/** How long a `verify:` may run: what is left of the step's `timeout:`,
+ *  with a floor. Null when the flow set no timeout — `timeout:` is the only
+ *  clock there is, and a stop still ends the check. */
+export function verifyBudgetMs(timeoutSec, elapsedMs) {
+    if (!timeoutSec || timeoutSec <= 0)
+        return null;
+    const total = timeoutSec * 1000;
+    return Math.max(total - elapsedMs, Math.min(VERIFY_FLOOR_MS, total));
+}
+/** After an interrupt is asked for, how long the model loop gets to wind
+ *  down on its own before the query is aborted outright. */
+export const INTERRUPT_GRACE_MS = 10_000;
+/** The tag on every event a failed check writes — `verify:`, `output: json`,
+ *  a schema — headline and detail alike. The runner's no-retry rule for
+ *  outward steps reads it (actedThenFailedCheck); reading the wording of the
+ *  last error missed a check whose detail line came after its headline. */
+const CHECK = { check: true };
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
  *  still means something. Only ever reached when `knownPrice` below does
@@ -72,24 +101,89 @@ export function stepCeiling(budgetUsd, spentUsd, launching) {
         return null;
     return Math.max(0, budgetUsd - spentUsd) / Math.max(1, launching);
 }
-export async function executeStep(opts) {
+/**
+ * The ceiling a step actually runs under, and which line set it.
+ *
+ * Two caps can apply to one step: the flow's `budget:` gives it an equal
+ * share of what the run has left; the agent's own `budget:` is the most that
+ * agent may spend in one run, less what its steps in this run have cost or
+ * may still cost, shared across `sharing` — this step and the agent's steps
+ * launched with it that have not started yet. Without the share, twenty
+ * fan-out copies of one agent each got the whole remainder, because none of
+ * them has recorded a cent when the next one starts.
+ * The tighter one wins, and the note says which, because "over budget" with
+ * no line to go and raise is a message that sends someone to the wrong file.
+ */
+export function stepCeilingFor(flowShareUsd, agentBudgetUsd, agentSpentUsd, agent, sharing = 1) {
+    const flow = { ceilingUsd: flowShareUsd, note: "budget: in the flow file" };
+    if (!agentBudgetUsd || agentBudgetUsd <= 0)
+        return flow;
+    const left = Math.max(0, agentBudgetUsd - agentSpentUsd) / Math.max(1, sharing);
+    if (flowShareUsd !== null && flowShareUsd <= left)
+        return flow;
+    return { ceilingUsd: left, note: `budget: on the ${agent} agent` };
+}
+export async function executeStep(opts, 
+/** The model loop. Injected so the clock and the stop can be tested
+ *  without a model; production passes nothing and gets the SDK. */
+runQuery = query) {
+    // `workspace/…` for the shell, the scripts and a shell `verify:` — the
+    // file tools expand the prefix themselves. Held for the step, verify
+    // included, and gone before anyone reads the step's files back
+    // (confine.ts#linkWorkspace says why it is not permanent).
+    fs.mkdirSync(opts.agentDir, { recursive: true });
+    const link = linkWorkspace(opts.agentDir, opts.workspaceRoot);
+    if (link.note)
+        opts.emit("info", `workspace/: ${link.note}`);
+    try {
+        // And a Node program started through it is still its own main module
+        // (confine.ts#workspaceLinkEnv) — for the model's Bash, which inherits
+        // the SDK's env; the shell verify: and the scripts get it where they
+        // spawn.
+        return await executeStepInner({ ...opts, env: workspaceLinkEnv(opts.env, opts.agentDir) }, runQuery);
+    }
+    finally {
+        link.release();
+    }
+}
+async function executeStepInner(opts, runQuery) {
     const { agentDir, workspaceRoot, libraryRoot, emit } = opts;
     let status = "running";
     let costUsd = null;
     let usage = null;
+    let stopReason = null;
     const texts = [];
     fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
     fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
-    const q = query({
+    // The one handle that can end the loop from outside: the timeout and a
+    // stop both ask the query to interrupt, and abort it outright if it has
+    // not wound down within the grace period.
+    const abort = new AbortController();
+    const subagents = opts.subagents?.length ? opts.subagents : null;
+    const guardSubagent = subagents ? subagentGuard(subagents) : null;
+    // A sub-agent's calls reach both the hook (which sees its id AND name) and
+    // canUseTool (which sees only the id). Remembered here so every refusal —
+    // its own list, a path outside the workspace, a shell command — names the
+    // agent that tried, not just the step.
+    const subagentNames = new Map();
+    // `limits:` — this step's counts. A new step, a retry of one, or a
+    // fan-out instance each start from zero.
+    const counter = new CallCounter(opts.limits);
+    const q = runQuery({
         prompt: opts.prompt,
         options: {
             cwd: agentDir,
+            abortController: abort,
             model: opts.model,
             // Omitted, not passed as undefined-with-a-default: an unset effort
             // should mean "whatever this model does normally", which is not a
             // level we can name — it moves as models ship.
             ...(opts.effort ? { effort: opts.effort } : {}),
             systemPrompt: opts.systemPrompt,
+            ...(opts.maxTurns ? { maxTurns: opts.maxTurns } : {}),
+            // Sub-agents: the SDK's own delegation. Every definition carries an
+            // explicit tool list (an absent one inherits all of ours).
+            ...(subagents ? { agents: toAgentDefinitions(subagents) } : {}),
             // Restrict the toolset itself, not just approval: an agent that
             // declares no tools gets none, instead of seeing the full Claude
             // Code toolset and burning turns on denied calls.
@@ -116,13 +210,96 @@ export async function executeStep(opts) {
                 autoAllowBashIfSandboxed: false,
                 failIfUnavailable: false,
             },
-            env: opts.env,
+            // With sub-agents, the SDK would also offer its built-in ones
+            // (general-purpose has every tool the session has). Only the declared
+            // ones may run; the guard in the hook below refuses the rest as well.
+            env: subagents ? { ...(opts.env ?? process.env), CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS: "1" } : opts.env,
             mcpServers: opts.mcpServers,
-            canUseTool: async (toolName, input) => {
+            // canUseTool is only asked when the SDK wants permission, and it never
+            // asks for a read inside the cwd — so `Read workspace/storage/x` went
+            // to `<agentDir>/workspace/storage/x` unchecked and unrewritten. On
+            // 2026-09-24 that read a stray copy a broken write had left there,
+            // with no error. A PreToolUse hook runs on every call: expand the
+            // virtual prefix (and refuse an escape) here for every filesystem tool,
+            // and leave the rest of the decision to canUseTool.
+            hooks: {
+                PreToolUse: [{
+                        hooks: [async (hookInput) => {
+                                if (hookInput.hook_event_name !== "PreToolUse")
+                                    return {};
+                                // A sub-agent's calls come through here too, tagged with its
+                                // name; anything outside its own list — or from a sub-agent this
+                                // step did not declare — is refused before the shared checks
+                                // below (which apply to it unchanged). So is a delegation from
+                                // the main thread to anything but a declared sub-agent.
+                                const agentId = "agent_id" in hookInput && hookInput.agent_id ? String(hookInput.agent_id) : undefined;
+                                const agentType = agentId ? hookInput.agent_type : undefined;
+                                const via = agentId ? (agentType ?? "subagent") : undefined;
+                                if (agentId && via)
+                                    subagentNames.set(agentId, via);
+                                if (guardSubagent) {
+                                    const why = guardSubagent({ agentId, agentType, tool: hookInput.tool_name, input: (hookInput.tool_input ?? {}) });
+                                    if (why) {
+                                        emit("error", why, { subagent: via });
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: why } };
+                                    }
+                                }
+                                const verdict = isFilesystemTool(hookInput.tool_name)
+                                    ? checkPaths(hookInput.tool_name, hookInput.tool_input, { agentDir, workspaceRoot, libraryRoot })
+                                    : null;
+                                if (verdict && !verdict.ok) {
+                                    emit("error", verdict.reason, via ? { subagent: via } : undefined);
+                                    return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: verdict.reason } };
+                                }
+                                // `limits:` — last, so a call another check refused counts
+                                // toward nothing. Every call passes here, the step's own and its
+                                // sub-agents', so one count covers both. A call past a limit is
+                                // refused before it runs: the tool, and any paid API behind it,
+                                // never sees it.
+                                if (counter.active) {
+                                    const refusal = counter.take(limitKeysFor(hookInput.tool_name, hookInput.tool_input, opts.toolOwners));
+                                    if (refusal) {
+                                        emit("info", `${refusal.message} (${hookInput.tool_name} refused)`, via ? { subagent: via } : undefined);
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: refusal.message } };
+                                    }
+                                }
+                                if (!verdict?.updatedInput)
+                                    return {};
+                                return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: verdict.updatedInput } };
+                            }],
+                    }],
+                // A message a person sent into the running step reaches the model
+                // after its next tool call, as context — never as a change to what it
+                // may do. A model that is only writing, calling no tools, hears it at
+                // the next call it makes.
+                ...(opts.inbox
+                    ? {
+                        PostToolUse: [{
+                                hooks: [async (hookInput) => {
+                                        if (hookInput.hook_event_name !== "PostToolUse")
+                                            return {};
+                                        // A sub-agent's call: the message is for the step's own
+                                        // model, and draining it here would hand it to a context
+                                        // that ends with the delegation — and lose it.
+                                        if ("agent_id" in hookInput && hookInput.agent_id)
+                                            return {};
+                                        const context = await opts.inbox().catch(() => null);
+                                        return context ? { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: context } } : {};
+                                    }],
+                            }],
+                    }
+                    : {}),
+            },
+            canUseTool: async (toolName, input, options) => {
+                const via = options?.agentID ? (subagentNames.get(options.agentID) ?? "subagent") : undefined;
                 // The toolset was already narrowed to what the agent declared, so
                 // anything outside it is a denial with a reason the model can act on.
                 const fromGrantedServer = opts.mcpNames.some((n) => toolName.startsWith(`mcp__${n}__`));
+                // A call the hook counted and this refuses never ran: give it back.
+                const refund = () => { if (counter.active)
+                    counter.refund(limitKeysFor(toolName, input, opts.toolOwners)); };
                 if (!opts.allowed.includes(toolName) && !fromGrantedServer) {
+                    refund();
                     return {
                         behavior: "deny",
                         message: `Tool ${toolName} is not enabled for this agent.`,
@@ -134,14 +311,46 @@ export async function executeStep(opts) {
                         ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot })
                         : { ok: true };
                 if (!verdict.ok) {
-                    emit("error", verdict.reason);
+                    refund();
+                    emit("error", verdict.reason, via ? { subagent: via } : undefined);
                     return { behavior: "deny", message: verdict.reason };
                 }
                 return { behavior: "allow", updatedInput: verdict.updatedInput ?? input };
             },
         },
     });
-    const deadline = opts.timeoutSec ? Date.now() + opts.timeoutSec * 1000 : null;
+    // Why the loop was ended from outside, if it was. The deadline used to be
+    // checked only when a message arrived, so a step waiting on one long tool
+    // call — a crawl, a build — sailed past its timeout: with no message there
+    // was nothing to check it against. The backstop timer fires regardless,
+    // and a stop is read on a clock rather than between groups.
+    let ended = null;
+    const startedAt = Date.now();
+    const timers = [];
+    const endWith = (why) => {
+        if (ended)
+            return;
+        ended = why;
+        void q.interrupt().catch(() => { });
+        timers.push(setTimeout(() => abort.abort(), INTERRUPT_GRACE_MS));
+    };
+    if (opts.timeoutSec)
+        timers.push(setTimeout(() => endWith("timeout"), opts.timeoutSec * 1000));
+    if (opts.stopRequested) {
+        timers.push(setInterval(() => {
+            try {
+                if (opts.stopRequested())
+                    endWith("stopped");
+            }
+            catch {
+                // an unreadable record is not a stop
+            }
+        }, STOP_POLL_MS));
+    }
+    // The clocks stay referenced on purpose: a step hanging in a tool call may
+    // be the only thing keeping the loop alive, and an unreferenced timer
+    // would let the process exit around it instead of ending it. They are all
+    // cleared when the step ends, so nothing outlives the step.
     // The hard cap. Spend is counted as each assistant turn arrives — its
     // usage is in the message — so the step can stop at the ceiling rather
     // than learn afterwards that it crossed it. Cache traffic is counted as
@@ -149,73 +358,232 @@ export async function executeStep(opts) {
     // that is the honest direction to be wrong in.
     const ceiling = typeof opts.budgetUsd === "number" && opts.budgetUsd > 0 ? opts.budgetUsd : null;
     let spentUsd = 0;
+    // Every turn's usage, by the model message's id. The SDK can emit one
+    // turn as several assistant messages that repeat the same usage, so a
+    // turn is counted once — and the sum is the step's cost whenever the
+    // closing `result` never arrives: a timeout or a stop ends the loop before
+    // it, and a step that made 193 model calls was recorded as $0 (lawyer-desk,
+    // 2026-09-25 09:00).
+    // Each with the rate it is priced at: a sub-agent with its own `model:`
+    // runs its turns on that model, and pricing them at the parent's put a
+    // max sub-agent under a fast parent at a fifth of its cost — against the
+    // ceiling and on the bill.
+    const turns = new Map();
+    let anonymousTurns = 0;
+    const specByName = new Map((subagents ?? []).map((s) => [s.name, s]));
+    const priceOf = (message) => {
+        const parent = message.parent_tool_use_id;
+        if (!parent)
+            return opts.price ?? null;
+        const declared = specByName.get(delegations.get(parent) ?? "")?.model;
+        if (declared === undefined || declared === "inherit" || declared === opts.model)
+            return opts.price ?? null;
+        const model = message.message?.model;
+        return knownPrice(typeof model === "string" ? model : undefined) ?? knownPrice(declared);
+    };
+    const turnsTotal = () => [...turns.values()].reduce((sum, t) => sum + priceTurn(t.u, t.price), 0);
+    const mixedModels = () => [...turns.values()].some((t) => t.price !== (opts.price ?? null));
     // Open tool calls, by the provider's id, so the result can be paired with
     // its call and the trace can say how long each tool ran.
     const openCalls = new Map();
-    for await (const message of q) {
-        if (deadline && Date.now() > deadline) {
-            emit("error", `step exceeded its ${opts.timeoutSec}s timeout`);
-            status = "failed";
-            break;
+    // Delegations in flight: the parent's Agent call id → the sub-agent's name.
+    // The SDK tags every message a sub-agent produces with that call's id
+    // (parent_tool_use_id), which is how its tool calls are labelled here.
+    const delegations = new Map();
+    const subagentOf = (message) => {
+        const parent = message.parent_tool_use_id;
+        return parent ? (delegations.get(parent) ?? "subagent") : undefined;
+    };
+    // Slim browsing (browser-pod.ts): every call the step makes, read or
+    // write, in the order the model asked for them — the step's own and its
+    // sub-agents'. Classified when asked for, not when answered: a call in
+    // flight when the pod goes is counted as made. And the web tool's pod log,
+    // read after every tool result.
+    const pod = opts.browserPod ?? null;
+    const ledger = new Map();
+    const podState = { reconnects: 0, reconnected: 0 };
+    let podOffset = 0;
+    const readPod = (callId) => {
+        if (!pod)
+            return;
+        let text;
+        try {
+            text = fs.readFileSync(pod.events, "utf8");
         }
-        if (message.type === "assistant") {
-            const u = message.message.usage;
-            if (ceiling && u) {
-                spentUsd += priceTurn(u, opts.price ?? null);
-                if (spentUsd >= ceiling) {
-                    emit("error", `over budget — this step reached $${spentUsd.toFixed(4)} of its $${ceiling.toFixed(4)} ceiling mid-turn and was stopped (budget: in the flow file)`);
-                    status = "failed";
-                    break;
-                }
+        catch {
+            return; // nothing written yet
+        }
+        const { events, next } = readPodEvents(text, podOffset);
+        podOffset = next;
+        let closedAgain = false;
+        for (const [i, e] of events.entries()) {
+            if (e.kind === "reconnect") {
+                podState.reconnects += 1;
+                // A reconnect that reached the pod, and then the call dropped again
+                // at once (the web tool's next line is "lost"), did not get
+                // through: the pod answered while it shut down. Live, 2026-10-01,
+                // "reconnected (try 1 of 3)" was followed by "lost after 1
+                // reconnect try" and the step read "1 got through".
+                closedAgain = !!e.ok && events[i + 1]?.kind === "lost";
+                if (closedAgain)
+                    podState.closedAgain = (podState.closedAgain ?? 0) + 1;
+                else if (e.ok)
+                    podState.reconnected += 1;
+                // `at` is when the try happened: these lines reach the run when the
+                // call returns, so the run's own stamps on them are all the same.
+                emit("info", `browser pod: ${e.ok ? "reconnected" : "reconnect failed"} (try ${e.attempt ?? "?"} of ${e.of ?? "?"}${podAt(e.at)})${!e.ok && e.error ? ` — ${e.error}` : ""}${closedAgain ? ", but the pod closed again" : ""}`);
             }
-            for (const block of message.message.content) {
-                if (block.type === "text" && block.text.trim()) {
-                    texts.push(block.text);
-                    emit("text", block.text);
+            else if (!podState.lost) {
+                // A call that never reached the pod changed nothing, whatever its
+                // arguments asked for.
+                if (e.ran === false)
+                    ledger.delete(callId);
+                podState.lost = { cause: e.kind, detail: (e.kind === "needs-full" ? e.why : e.error) ?? "connection closed" };
+                emit("info", e.kind === "needs-full"
+                    ? `browser pod: this call needs a browser in the step, which the slim image has not (${podState.lost.detail}) — stopping the step`
+                    : closedAgain
+                        ? `browser pod: lost — the call dropped again after the reconnect (${podState.lost.detail}${podAt(e.at)}) — stopping the step`
+                        : `browser pod: lost after ${podState.reconnects} reconnect tr${podState.reconnects === 1 ? "y" : "ies"} (${podState.lost.detail}${podAt(e.at)}) — stopping the step`);
+                endWith("pod-lost");
+            }
+        }
+    };
+    try {
+        for await (const message of q) {
+            if (ended)
+                break;
+            if (message.type === "assistant") {
+                const m = message.message;
+                const u = m.usage;
+                if (u)
+                    turns.set(m.id ?? `turn-${anonymousTurns++}`, { u, price: priceOf(message) });
+                if (ceiling && u) {
+                    spentUsd = turnsTotal();
+                    if (spentUsd >= ceiling) {
+                        emit("error", `over budget — this step reached $${spentUsd.toFixed(4)} of its $${ceiling.toFixed(4)} ceiling mid-turn and was stopped (${opts.budgetNote ?? "budget: in the flow file"})`);
+                        status = "failed";
+                        break;
+                    }
                 }
-                else if (block.type === "tool_use") {
-                    openCalls.set(block.id, { name: block.name, at: Date.now() });
-                    emit("tool", block.name, { call: block.id });
+                const via = subagentOf(message);
+                for (const block of message.message.content) {
+                    if (block.type === "text" && block.text.trim()) {
+                        // A sub-agent's own words are its business; the parent's reply is
+                        // the step's result. (The SDK forwards only tool blocks by default.)
+                        if (via)
+                            continue;
+                        texts.push(block.text);
+                        emit("text", block.text);
+                    }
+                    else if (block.type === "tool_use") {
+                        if (!via && DELEGATE_TOOLS.includes(block.name)) {
+                            const input = block.input;
+                            const to = String(input?.subagent_type ?? "subagent");
+                            delegations.set(block.id, to);
+                            // One line a person can read: who got the job, and what it was.
+                            const job = String(input?.description ?? input?.prompt ?? "").replace(/\s+/g, " ").trim().slice(0, 160);
+                            emit("info", `delegating to ${to}${job ? `: ${job}` : ""}`, { subagent: to });
+                        }
+                        openCalls.set(block.id, { name: block.name, at: Date.now(), ...(via ? { subagent: via } : {}) });
+                        if (pod)
+                            ledger.set(block.id, classifyCall(block.name, block.input, pod));
+                        emit("tool", block.name, { call: block.id, ...(via ? { subagent: via } : {}) });
+                    }
                 }
             }
-        }
-        else if (message.type === "user") {
-            // Tool results ride back as user turns. The completion event closes
-            // the span the call opened; the runner's journal keeps both.
-            const content = message.message.content;
-            if (Array.isArray(content)) {
-                for (const block of content) {
-                    if (block.type !== "tool_result")
-                        continue;
-                    const open = openCalls.get(block.tool_use_id);
-                    if (!open)
-                        continue;
-                    openCalls.delete(block.tool_use_id);
-                    emit("tool", open.name, {
-                        call: block.tool_use_id,
-                        ms: Date.now() - open.at,
-                        ...(block.is_error ? { err: true } : {}),
-                    });
+            else if (message.type === "user") {
+                // Tool results ride back as user turns. The completion event closes
+                // the span the call opened; the runner's journal keeps both.
+                const content = message.message.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block.type !== "tool_result")
+                            continue;
+                        const open = openCalls.get(block.tool_use_id);
+                        if (!open)
+                            continue;
+                        openCalls.delete(block.tool_use_id);
+                        emit("tool", open.name, {
+                            call: block.tool_use_id,
+                            ms: Date.now() - open.at,
+                            ...(block.is_error ? { err: true } : {}),
+                            ...(open.subagent ? { subagent: open.subagent } : {}),
+                        });
+                        readPod(block.tool_use_id);
+                    }
                 }
             }
-        }
-        else if (message.type === "result") {
-            status = message.subtype === "success" ? "completed" : "failed";
-            costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
-            if ("usage" in message && message.usage) {
-                const u = message.usage;
-                usage = {
-                    // Cache traffic is input the provider still bills (at its own
-                    // rates); folding it into the input count over-approximates for
-                    // gateways with cheaper cache reads, which errs on the honest side.
-                    inputTokens: (u.input_tokens ?? 0) +
-                        (u.cache_creation_input_tokens ?? 0) +
-                        (u.cache_read_input_tokens ?? 0),
-                    outputTokens: u.output_tokens ?? 0,
-                };
+            else if (message.type === "result") {
+                status = message.subtype === "success" ? "completed" : "failed";
+                if (message.subtype === "error_max_turns") {
+                    emit("error", `stopped after ${opts.maxTurns ?? "its"} turns (max_turns: in the flow file) — the step did not finish`);
+                }
+                costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
+                stopReason = "stop_reason" in message && typeof message.stop_reason === "string" ? message.stop_reason : null;
+                if ("usage" in message && message.usage) {
+                    const u = message.usage;
+                    usage = {
+                        // Cache traffic is input the provider still bills (at its own
+                        // rates); folding it into the input count over-approximates for
+                        // gateways with cheaper cache reads, which errs on the honest side.
+                        inputTokens: (u.input_tokens ?? 0) +
+                            (u.cache_creation_input_tokens ?? 0) +
+                            (u.cache_read_input_tokens ?? 0),
+                        outputTokens: u.output_tokens ?? 0,
+                    };
+                }
             }
         }
     }
+    catch (err) {
+        // An abort we asked for is not an error of the step's; anything else is.
+        if (!ended)
+            throw err;
+    }
+    finally {
+        for (const t of timers)
+            clearTimeout(t);
+    }
+    // What the step used of each limit, on the trace whenever any is set —
+    // so "it stopped searching at 40" is read off the run, not guessed.
+    const limitLine = counter.summary();
+    if (limitLine)
+        emit("info", limitLine);
+    // No result message — a timeout, a stop, a budget stop, a stream that
+    // died — means no total from the SDK. The turns it did take were billed by
+    // the provider all the same, so the step's cost is their sum.
+    if (costUsd === null && turns.size) {
+        let input = 0;
+        let output = 0;
+        let priced = 0;
+        for (const { u: t, price } of turns.values()) {
+            input += (t.input_tokens ?? 0) + (t.cache_creation_input_tokens ?? 0) + (t.cache_read_input_tokens ?? 0);
+            output += t.output_tokens ?? 0;
+            priced += priceTurn(t, price);
+        }
+        costUsd = priced;
+        usage ??= { inputTokens: input, outputTokens: output };
+        emit("info", `cost from ${turns.size} model turn${turns.size === 1 ? "" : "s"}: $${priced.toFixed(4)} — the step ended before the model's closing total`);
+    }
+    if (ended === "timeout") {
+        emit("error", `timed out after ${opts.timeoutSec}s (timeout: in the flow file) — the step was stopped with the files it wrote so far kept`);
+        status = "failed";
+    }
+    else if (ended === "stopped") {
+        emit("error", "stopped by a person mid-step");
+        status = "failed";
+    }
+    else if (ended === "pod-lost") {
+        // The runner says what happens next — a re-run on the full image, or a
+        // failure naming what was written. Not an error of the step's own.
+        status = "failed";
+    }
+    if (pod) {
+        readPod("");
+        if (podState.lost) {
+            podState.writes = [...ledger.values()].flatMap((k) => (k.write ? [k.what] : []));
+        }
+    }
     // The SDK ends a healthy run with a `result` message. A stream that just
     // stops — subprocess OOM-killed, crashed, or torn down — used to fall
     // through as "completed", which reported a run that produced nothing as a
@@ -240,28 +608,88 @@ export async function executeStep(opts) {
         if (extracted.ok) {
             data = extracted.value;
             emit("info", `output: json — ${describeJson(data)}`);
+            // The declared shape, checked here beside the extraction: a value
+            // that parses but is not what the next step was promised is the same
+            // failure as no value, and the message names the field.
+            const errors = opts.schema !== undefined && looksLikeSchema(opts.schema) ? validateSchema(data, opts.schema) : [];
+            if (errors.length) {
+                emit("error", `schema: the value does not fit — ${describeSchemaErrors(errors)}`, CHECK);
+                status = "failed";
+            }
         }
         else {
-            emit("error", `output: json — ${extracted.reason}`);
+            emit("error", `output: json — ${extracted.reason}`, CHECK);
             status = "failed";
         }
     }
     // "Done" should mean a check passed, not that the model stopped talking.
+    // The loop's clocks are cleared by now, so the check gets its own: what is
+    // left of the step's `timeout:` (never less than VERIFY_FLOOR_MS of it),
+    // and a stop read on the same clock the loop used. No `timeout:`, no clock:
+    // it is the only one there is, here as in the loop. A `verify:` that hangs
+    // — a build waiting on a lock, a judge that never answers — used to hold
+    // the step, and the run, with nothing to end it.
     if (status === "completed" && opts.verify) {
-        const verdict = await checkVerify(agentDir, opts.verify, {
-            env: opts.verifyEnv ?? {},
-            result,
-            conclusion,
-            data,
-            modelEnv: opts.env,
-        });
-        emit(verdict.ok ? "info" : "error", `verify \`${opts.verify}\` → ${verdict.headline}`);
-        if (verdict.detail.trim())
-            emit(verdict.ok ? "info" : "error", verdict.detail.slice(0, 1000));
-        if (!verdict.ok)
+        const verifyMs = verifyBudgetMs(opts.timeoutSec, Date.now() - startedAt);
+        const halt = new AbortController();
+        let cut = null;
+        const clocks = [];
+        if (verifyMs !== null) {
+            clocks.push(setTimeout(() => {
+                cut ??= "timeout";
+                halt.abort();
+            }, verifyMs));
+        }
+        if (opts.stopRequested) {
+            clocks.push(setInterval(() => {
+                try {
+                    if (opts.stopRequested()) {
+                        cut ??= "stopped";
+                        halt.abort();
+                    }
+                }
+                catch {
+                    // an unreadable record is not a stop
+                }
+            }, STOP_POLL_MS));
+        }
+        let verdict;
+        try {
+            verdict = await checkVerify(agentDir, opts.verify, {
+                env: opts.verifyEnv ?? {},
+                result,
+                conclusion,
+                data,
+                modelEnv: opts.env,
+                signal: halt.signal,
+            });
+        }
+        finally {
+            for (const t of clocks)
+                clearTimeout(t);
+        }
+        if (cut === "timeout") {
+            emit("error", `verify \`${opts.verify}\` → timed out after ${Math.round(verifyMs / 1000)}s (what was left of timeout: in the flow file) — it was stopped`, CHECK);
+            status = "failed";
+        }
+        else if (cut === "stopped") {
+            emit("error", `verify \`${opts.verify}\` → stopped by a person mid-check`, CHECK);
             status = "failed";
+        }
+        else {
+            emit(verdict.ok ? "info" : "error", `verify \`${opts.verify}\` → ${verdict.headline}`, verdict.ok ? undefined : CHECK);
+            if (verdict.detail.trim())
+                emit(verdict.ok ? "info" : "error", verdict.detail.slice(0, 1000), verdict.ok ? undefined : CHECK);
+            if (!verdict.ok)
+                status = "failed";
+        }
     }
-    return { status, result, conclusion, ...(opts.output ? { data } : {}), costUsd, usage };
+    return {
+        status, result, conclusion, ...(opts.output ? { data } : {}), costUsd, usage,
+        ...(mixedModels() ? { turnsCostUsd: turnsTotal() } : {}),
+        stopReason,
+        ...(pod ? { browserPod: podState } : {}),
+    };
 }
 // ------------------------------------------------------------ output: json
 /**
@@ -319,8 +747,21 @@ const VERIFY_ASSERTION = /^(contains|not-contains|matches|file|judge):\s*([\s\S]
 export async function checkVerify(agentDir, verify, ctx) {
     const m = verify.trim().match(VERIFY_ASSERTION);
     if (!m) {
-        const { code, out } = await runVerify(agentDir, verify, ctx.env, ctx.data);
-        return { ok: code === 0, headline: `exit ${code ?? "error"}`, detail: out };
+        // The step's final turn, as a file named in FOLDRUN_REPLY_FILE — so one
+        // command can check the reply and the artefact together
+        // (`grep -q '^READY' "$FOLDRUN_REPLY_FILE" && test -s out.json`). A step
+        // has one `verify:`, and a shell check that could not see the reply
+        // made authors choose between the two.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-reply-"));
+        const replyFile = path.join(dir, "reply.md");
+        fs.writeFileSync(replyFile, ctx.conclusion ?? ctx.result ?? "");
+        try {
+            const { code, out } = await runVerify(agentDir, verify, { ...ctx.env, FOLDRUN_REPLY_FILE: replyFile }, ctx.data, ctx.signal);
+            return { ok: code === 0, headline: `exit ${code ?? "error"}`, detail: out };
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
     }
     const [, kind, rawValue] = m;
     const value = rawValue.trim().replace(/^["']|["']$/g, "");
@@ -345,15 +786,20 @@ export async function checkVerify(agentDir, verify, ctx) {
             }
         }
         case "file": {
-            const target = path.resolve(agentDir, value);
-            if (!target.startsWith(path.resolve(agentDir) + path.sep)) {
-                return { ok: false, headline: "path escapes the agent directory", detail: "" };
+            // Agent-relative like every path in a flow, or `workspace/…` from the
+            // workspace root; confined to the workspace. It was confined to the
+            // agent's own folder, so the one place a step's deliverable belongs —
+            // `workspace/storage/x`, or `../../storage/x` — was always "escapes".
+            const workspaceRoot = path.resolve(agentDir, "..", "..");
+            const target = resolveAgentPath(workspaceRoot, agentDir, value);
+            if (!isWithin(workspaceRoot, target) || target === workspaceRoot) {
+                return { ok: false, headline: "path escapes the workspace", detail: "" };
             }
             const ok = fs.existsSync(target) && fs.statSync(target).size > 0;
             return { ok, headline: ok ? "present and non-empty" : `${value} is missing or empty`, detail: "" };
         }
         case "judge": {
-            const verdict = await judgeReply(value, output, ctx.modelEnv ?? {});
+            const verdict = await judgeReply(value, output, ctx.modelEnv ?? {}, ctx.signal);
             const ok = /^\s*PASS\b/i.test(verdict);
             return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
         }
@@ -365,8 +811,12 @@ export async function checkVerify(agentDir, verify, ctx) {
  * Same shape as the eval judge, and answered with one word first so the
  * verdict is a prefix test rather than a reading.
  */
-async function judgeReply(rubric, output, env) {
+async function judgeReply(rubric, output, env, signal) {
     const texts = [];
+    const abortController = new AbortController();
+    if (signal?.aborted)
+        abortController.abort();
+    signal?.addEventListener("abort", () => abortController.abort(), { once: true });
     try {
         const q = query({
             prompt: `You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
@@ -379,6 +829,7 @@ async function judgeReply(rubric, output, env) {
                 settingSources: [],
                 env,
                 maxTurns: 1,
+                abortController,
             },
         });
         for await (const message of q) {
@@ -397,15 +848,37 @@ async function judgeReply(rubric, output, env) {
 }
 // Verification runs in the agent's directory with its secrets available, so
 // a check can be as simple as `npm run build` or `test -s outputs/report.md`.
-function runVerify(agentDir, command, env, data) {
+function runVerify(agentDir, command, env, data, signal) {
     return new Promise((resolve) => {
-        // No clock of the platform's: a verify like `npm run build` takes what
-        // it takes, and the step's own `timeout:` is the bound if the flow set one.
+        // The clock is the caller's (executeStep): what is left of the step's
+        // `timeout:`, ended through `signal`, which a stop also fires.
+        // The allowlisted host base plus what the caller passed: the step's
+        // secrets and identifiers on the in-process path (runner.ts), the
+        // container's own environment on the isolated one (run-container.ts).
+        // Never process.env whole — see host-env.ts.
         const child = spawn("bash", ["-lc", command], {
             cwd: agentDir,
-            env: { ...process.env, ...env },
+            // workspaceLinkEnv: `node workspace/tools/x/check.mjs` must run its
+            // check, not pass for having skipped it (confine.ts says how).
+            env: workspaceLinkEnv({ ...hostSafeEnv(), ...env }, agentDir),
             stdio: ["pipe", "pipe", "pipe"],
+            // Its own process group, so an abort ends what the shell started
+            // (`npm run build` and its children) and not only bash.
+            detached: true,
         });
+        const kill = () => {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        if (signal?.aborted)
+            kill();
+        else
+            signal?.addEventListener("abort", kill, { once: true });
+        child.on("close", () => signal?.removeEventListener("abort", kill));
         // An `output: json` step's data arrives on stdin, so a check can be
         // `jq -e '.total > 0'` — arithmetic in a real tool, reading the value
         // the step actually returned rather than re-parsing its prose.