@foldrun/core 0.4.0 → 0.5.0

package/dist/src/step-exec.js

@@ -8,17 +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
@@ -84,15 +106,19 @@ export function stepCeiling(budgetUsd, spentUsd, launching) {
  *
  * 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 earlier steps in this run cost.
+ * 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) {
+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);
+    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` };
@@ -101,10 +127,31 @@ 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 });
@@ -112,6 +159,16 @@ runQuery = query) {
     // 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: {
@@ -124,6 +181,9 @@ runQuery = query) {
             ...(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.
@@ -150,13 +210,96 @@ runQuery = query) {
                 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.`,
@@ -168,7 +311,8 @@ runQuery = query) {
                         ? 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 };
@@ -181,6 +325,7 @@ runQuery = query) {
     // 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)
@@ -213,31 +358,136 @@ runQuery = query) {
     // 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();
+    // 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");
+        }
+        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" : ""}`);
+            }
+            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 u = message.message.usage;
+                const m = message.message;
+                const u = m.usage;
+                if (u)
+                    turns.set(m.id ?? `turn-${anonymousTurns++}`, { u, price: priceOf(message) });
                 if (ceiling && u) {
-                    spentUsd += priceTurn(u, opts.price ?? null);
+                    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;
                     }
                 }
+                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") {
-                        openCalls.set(block.id, { name: block.name, at: Date.now() });
-                        emit("tool", block.name, { call: block.id });
+                        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 } : {}) });
                     }
                 }
             }
@@ -257,7 +507,9 @@ runQuery = query) {
                             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);
                     }
                 }
             }
@@ -267,6 +519,7 @@ runQuery = query) {
                     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 = {
@@ -291,6 +544,27 @@ runQuery = query) {
         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";
@@ -299,6 +573,17 @@ runQuery = query) {
         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
@@ -328,31 +613,83 @@ runQuery = query) {
             // 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)}`);
+                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
 /**
@@ -410,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, "");
@@ -436,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) };
         }
@@ -456,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 ` +
@@ -470,6 +829,7 @@ async function judgeReply(rubric, output, env) {
                 settingSources: [],
                 env,
                 maxTurns: 1,
+                abortController,
             },
         });
         for await (const message of q) {
@@ -488,19 +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: { ...hostSafeEnv(), ...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.