@basein/runner 0.2.11 → 0.3.0

package/dist/replay/controller.js

@@ -12,38 +12,159 @@
  * ignore. Nothing throws at a hook.
  */
 import { parseQualifiedName } from "../control/correlation.js";
-import { isHousekeeping } from "../record/housekeeping.js";
+import { isHousekeepingCall } from "../record/housekeeping.js";
 import { redact } from "../record/redact.js";
 import { serializeCapped } from "../record/truncate.js";
 import { logDetail, logLine, errText } from "../util/log.js";
-import { MAX_REPLAY_REASON } from "./bundle.js";
+import { serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
+import { bashCommandFor } from "./bash-channel.js";
+import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, } from "./derive.js";
-import { buildHandoverNote } from "./handover.js";
-import { ProxyWorkQueue } from "./executor.js";
-import { ScenarioReplayPlan } from "./plan.js";
+import { buildHandoverNote, MAX_HANDOVER_NOTE, } from "./handover.js";
+import { NO_PROXY, NoSessionProxyError, ProxyWorkQueue, QUEUE_CLOSED } from "./executor.js";
+import { logicTimeoutMs, MAX_LOGIC_TIMEOUT_MS } from "./logic.js";
+import { PREVIEW_BUDGET_MS, ScenarioReplayPlan, StepRunError, } from "./plan.js";
 import { PRICING_VERSION } from "./pricing.js";
+import { hasShellStep, sinkOf, sinkOfPlan, unsafeParameter } from "./safety.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { clampToFrameStart, flattenChain, } from "./flatten.js";
 import { blockingTargets } from "./targets.js";
-import { toolResultError } from "./tool-error.js";
+import { isNoResult, toolResultError } from "./tool-error.js";
 import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
 export const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
 /** How long a `/proxy/poll` is held open before it answers empty. */
 export const POLL_HOLD_MS = 25_000;
+/**
+ * The longest a prompt ever waits for a steer plan's parameters so that its
+ * directive can preview them ({@link ReplayController.settleForPreview}).
+ * `UserPromptSubmit` is on the user's critical path: a preview is worth a
+ * little of it, never the derivation's whole budget.
+ */
+export const PREVIEW_SETTLE_MAX_MS = 1_200;
+/**
+ * Whether the pin guard holds a call to this tool to the step's exact shape —
+ * the same command head, the same file (control/pin-guard.ts) — so that a call
+ * written without the directive's preview is declined rather than pinned.
+ */
+function pinnedToShape(toolName) {
+    const name = toolName ?? "";
+    return !parseQualifiedName(name) && sinkOf(name) !== undefined;
+}
 export const DEFAULT_BUDGETS = {
-    matchMs: 2_500,
+    // The longest a prompt waits for the service to say whether this is a known
+    // task; a match that has not answered by then is a turn run normally. The
+    // control server stops waiting at all for a while after one that answered
+    // slowly (`BIR_MATCH_SLOW_MS`). `BIR_MATCH_BUDGET_MS` in the recorder.
+    matchMs: 1_500,
     deriveMs: 8_000,
-    planMs: 120_000,
+    planMs: 100_000,
     stepMs: 60_000,
+    hookDeriveMs: 4_000,
+    preToolMs: 9_000,
 };
+/**
+ * The least time a dispatched step is given, however little the run has left.
+ * A step sent with 50 ms to answer is a step that may or may not have run.
+ */
+const MIN_STEP_MS = 1_000;
+/**
+ * The control server answers a `PreToolUse` by this, whatever replay is doing
+ * (its `HOOK_DEADLINE_MS` for `/tool/pre`). A deployment's `hookDeadlinesMs`
+ * can only shorten it; the server passes the one it keeps as `answerBy`
+ * ({@link PreToolOptions}).
+ */
+const PRETOOL_ROUTE_DEADLINE_MS = 12_000;
+/** Logic, the bundle and the answer's own trip: work past the last step's start. */
+const PRETOOL_MARGIN_MS = 1_000;
+/**
+ * The most {@link ReplayBudgets.preToolMs} may be: the last step started at the
+ * budget's end still gets its {@link MIN_STEP_MS} and the margin before the
+ * route's deadline answers the host. Past it, a divergence kept starting steps
+ * — writes, unattended — after the model had been told to carry on itself.
+ */
+export const MAX_PRETOOL_REPLAY_MS = PRETOOL_ROUTE_DEADLINE_MS - MIN_STEP_MS - PRETOOL_MARGIN_MS;
+/**
+ * The longest a direct run may take by its budgets, end to end.
+ *
+ * `bir-scenario` gives `/scenario/run` 290 s (`BIR_SCENARIO_RUN_TIMEOUT_MS`),
+ * just under Claude Code's 5-minute idle timeout for an MCP call, and a run
+ * that answers after its client stopped waiting is a replay thrown away with
+ * its steps already done. So the budgets are held to 270 s, and the defaults
+ * sit far below it: 8 s of derivation + 100 s of plan (more only when an
+ * operator sets `BIR_REPLAY_BUDGET_MS` or `BIR_REPLAY_PLAN_BUDGET_MS`) + 12 s
+ * of slack (one last step's 1 s, six 1 s logic bodies, a 5 s margin —
+ * {@link clampDirectRun}) = 120 s.
+ *
+ * Only `/scenario/run` is held to it. `bir replay` (`runAdHoc`) answers the
+ * operator's own command, which no MCP client times out, and keeps the budgets
+ * the environment asked for.
+ */
+export const DIRECT_RUN_CEILING_MS = 270_000;
+/** Transport, the bundle and redaction: work a direct run does outside every budget. */
+const DIRECT_RUN_MARGIN_MS = 5_000;
+/**
+ * Logic bodies a direct run can still evaluate once its plan deadline has
+ * passed: `paramsLogic` before the plan (after the derivation's own wait), and
+ * for the step started just before the deadline its parameter mapping and
+ * input logic, its output logic and result mapping, then `responseParamsLogic`.
+ * Each is bounded by `logicTimeoutMs()` (logic.ts).
+ */
+const LOGIC_BODIES_OUTSIDE_PLAN = 6;
+/** A derivation wait longer than this is not a budget a direct run can keep. */
+const MAX_DIRECT_DERIVE_MS = 60_000;
+/** However a direct run is squeezed, its plan keeps at least this. */
+const MIN_DIRECT_PLAN_MS = 10_000;
+/**
+ * The direct-run budgets, held under {@link DIRECT_RUN_CEILING_MS}.
+ *
+ * The worst case is `deriveMs + planMs` plus what can happen past the plan's
+ * deadline: one last step's {@link MIN_STEP_MS}, {@link LOGIC_BODIES_OUTSIDE_PLAN}
+ * logic bodies, and the margin. `stepMs` never adds to it — each step is
+ * clipped to what the plan has left. Budgets that would pass the ceiling are
+ * brought under it — the derivation wait first to {@link MAX_DIRECT_DERIVE_MS},
+ * then the plan — and `clamped` says what changed, for the log.
+ */
+export function clampDirectRun(budgets, logicMs = logicTimeoutMs()) {
+    const outside = MIN_STEP_MS + LOGIC_BODIES_OUTSIDE_PLAN * logicMs + DIRECT_RUN_MARGIN_MS;
+    if (budgets.deriveMs + budgets.planMs + outside <= DIRECT_RUN_CEILING_MS)
+        return { budgets };
+    const deriveMs = Math.min(budgets.deriveMs, MAX_DIRECT_DERIVE_MS);
+    const planMs = Math.max(MIN_DIRECT_PLAN_MS, Math.min(budgets.planMs, DIRECT_RUN_CEILING_MS - deriveMs - outside));
+    const clamped = {};
+    if (deriveMs !== budgets.deriveMs)
+        clamped.deriveMs = [budgets.deriveMs, deriveMs];
+    if (planMs !== budgets.planMs)
+        clamped.planMs = [budgets.planMs, planMs];
+    return { budgets: { ...budgets, deriveMs, planMs }, clamped };
+}
+/** The `why` of a {@link RunArmedResult} with nothing armed to run. */
+export const RUN_NO_PLAN = "no_plan";
+/** The hand-over shape of a {@link RunArmedResult}, or undefined when there is no note to hand over. */
+function handedOver(note) {
+    return note ? { ok: false, why: note, note: true } : undefined;
+}
 export const DEFAULT_INTENT_MATCH = {
     enabled: true,
     budgetMs: 4_000,
     maxPerTurn: 3,
     maxRequestsPerTurn: 40,
 };
+/**
+ * How long a call waits for the previous pin to thread before it is judged to
+ * be running beside it: the control server's hook-view fallback
+ * (`PROXY_REPORT_GRACE_MS`, 1.5 s after `PostToolUse`) plus slack. Bounded by
+ * the hook's own deadline as well.
+ */
+const PIN_THREAD_WAIT_MS = 1_750;
+/**
+ * How long a call waits for a pin the host has *not* reported finished, once
+ * the control server is known to report completions: only the time for a
+ * `PostToolUse` racing this `PreToolUse` to land. Anything longer is a call
+ * running beside it, and waiting on that could stall the turn for minutes.
+ */
+const HOST_RACE_MS = 200;
 /** How many step verdicts one report carries. A chain longer than this is not
  *  a chain anybody is reading step by step, and the report has to stay small. */
 const MAX_STEP_RESULTS = 200;
@@ -52,14 +173,78 @@ const MAX_STEP_ERROR_CHARS = 500;
 export class ReplayController {
     enabled;
     work = new ProxyWorkQueue();
+    /** The budgets every path runs on, a direct run's held under {@link DIRECT_RUN_CEILING_MS}. */
     budgets;
+    /**
+     * `bir replay`'s derivation wait and plan budget: what the environment asked
+     * for, unclamped — no MCP client times that run out (see
+     * {@link DIRECT_RUN_CEILING_MS}).
+     */
+    adHocBudgets;
     intentMatch;
     opts;
+    /** See {@link ReplayOptions.recordedFallback}. */
+    recordedFallback;
+    /** Calls waiting for a plan's pins to change (see `awaitPins`). */
+    pinWaiters = new WeakMap();
+    /**
+     * Set the first time the control server reports a host completion
+     * ({@link hostCompleted}). From then on a pin the host has not finished is a
+     * call really running beside the next one, and nothing waits for it.
+     */
+    hostSignals = false;
     constructor(opts) {
         this.opts = opts;
         this.enabled = opts.enabled;
-        this.budgets = { ...DEFAULT_BUDGETS, ...(opts.budgets ?? {}) };
+        const asked = {
+            ...DEFAULT_BUDGETS,
+            planMs: positiveEnv("BIR_REPLAY_PLAN_BUDGET_MS") ?? DEFAULT_BUDGETS.planMs,
+            hookDeriveMs: positiveEnv("BIR_HOOK_DERIVE_BUDGET_MS") ?? DEFAULT_BUDGETS.hookDeriveMs,
+            preToolMs: positiveEnv("BIR_PRETOOL_REPLAY_BUDGET_MS") ?? DEFAULT_BUDGETS.preToolMs,
+            ...(opts.budgets ?? {}),
+        };
+        // A PreToolUse's replay work past the route's deadline is steps started
+        // after the host was told to go ahead without them: held under it.
+        if (Number.isNaN(asked.preToolMs))
+            asked.preToolMs = DEFAULT_BUDGETS.preToolMs;
+        if (asked.preToolMs > MAX_PRETOOL_REPLAY_MS) {
+            const from = asked.preToolMs;
+            asked.preToolMs = MAX_PRETOOL_REPLAY_MS;
+            logLine("replay.budget_clamped", {
+                budget: "BIR_PRETOOL_REPLAY_BUDGET_MS",
+                from,
+                to: MAX_PRETOOL_REPLAY_MS,
+                why: `PreToolUse is answered by ${PRETOOL_ROUTE_DEADLINE_MS} ms; a divergence step started later ` +
+                    "would run after the model was told to carry on itself",
+            });
+        }
+        // A budget set past what a direct run can keep is brought back under it,
+        // and said so once: the alternative is a run its client has already
+        // abandoned, with its steps done and its answer thrown away.
+        const logicAsked = positiveEnv("BIR_LOGIC_TIMEOUT_MS");
+        if (logicAsked !== undefined && logicAsked > MAX_LOGIC_TIMEOUT_MS) {
+            logLine("replay.budget_clamped", {
+                budget: "BIR_LOGIC_TIMEOUT_MS",
+                from: logicAsked,
+                to: MAX_LOGIC_TIMEOUT_MS,
+                why: "a logic body holds up every hook of the project while it runs",
+            });
+        }
+        const direct = clampDirectRun(asked);
+        if (direct.clamped) {
+            logLine("replay.budget_clamped", {
+                deriveMs: direct.clamped.deriveMs?.join("→"),
+                planMs: direct.clamped.planMs?.join("→"),
+                ceilingMs: DIRECT_RUN_CEILING_MS,
+                why: "a direct run must answer before run_scenario's client gives up on it (290 s); " +
+                    "`bir replay` keeps the budget asked for",
+            });
+        }
+        this.budgets = direct.budgets;
+        this.adHocBudgets = { deriveMs: asked.deriveMs, planMs: asked.planMs };
         this.intentMatch = { ...DEFAULT_INTENT_MATCH, ...(opts.intentMatch ?? {}) };
+        this.recordedFallback =
+            opts.recordedFallback ?? process.env.BIR_REPLAY_RECORDED_OUTPUTS === "1";
     }
     /**
      * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
@@ -83,6 +268,13 @@ export class ReplayController {
      * covers both "no match" and "too slow", which are the same thing from here.
      */
     async awaitMatch(pending) {
+        // The match is the service's answer, so this is a service wait on the hot
+        // path (C1): none at all while the service is cooling down. An overrun is
+        // not reported from here — the recorder's own request reports its timeout
+        // or failure when it settles, and it is the one that knows which it was.
+        pending.catch(() => undefined);
+        if (!serviceHealth.canWait())
+            return null;
         let timer;
         const budget = new Promise((resolve) => {
             timer = setTimeout(() => resolve(null), this.budgets.matchMs);
@@ -235,7 +427,30 @@ export class ReplayController {
         const mode = modeFor(planned.map((e) => e.step), wrapped, this.opts.allowServers);
         if (mode === "none")
             return decline("no step is executable", "coverage");
-        const derivation = this.startDerivation(scenario, prompt, state, ctx);
+        // Tool results feed derivation as context, and they are whatever the agent
+        // last read — a fetched page, an email. A plan that hands its parameters
+        // to a shell or a database must not take them from there: a value lifted
+        // from a page and templated into a command is the page running a command
+        // (safety.ts). Every `command` sink, not only a shell: `mcp__pg__query`
+        // runs its input unattended just the same. A tool merely *named* for a
+        // query (a search `*_query`) loses the results too, and a scenario whose
+        // target only a result names declines more often — one replay, never a
+        // command nobody asked for.
+        let deriveCtx = ctx;
+        if (ctx.recentResults?.length && sinkOfPlan(planned) === "command") {
+            deriveCtx = { liveCall: ctx.liveCall };
+            logLine("replay.derive_context", {
+                scenario: scenario.id,
+                shell: hasShellStep(planned) || undefined,
+                why: "a step's input is run by a shell or a database (or its tool is named for one, such as *_query) — " +
+                    "recent tool results are not read for its parameters, so a target only they name is not found",
+            });
+        }
+        const derivation = this.startDerivation(scenario, prompt, state, deriveCtx);
+        // Whether the derivation has answered yet — read, never waited on, when the
+        // directive is written (below).
+        let deriveAnswered = false;
+        derivation.then(() => (deriveAnswered = true), () => (deriveAnswered = true));
         const params = derivation.then((r) => r.params);
         // `params` is awaited by the plan, and by gate 7 below when there is a
         // target. Without this, the losing race in gate 7 leaves `derivation`
@@ -254,22 +469,22 @@ export class ReplayController {
         if (hasTargets(scenario.paramsObject)) {
             // Of the targets this answer left unnamed, the ones this plan could act
             // on the recorded value of. Empty means the chain finds them for itself.
-            const blocking = (missing) => blockingTargets(missing, scenario.paramsObject, planned);
-            let result;
-            try {
-                result = await this.withBudget(derivation, this.budgets.deriveMs, "derivation");
-            }
-            catch (err) {
-                // Out of budget, or the call threw. The turn has not said what this task
-                // is to act on, so every target is unnamed (R-PARAM-3).
+            const blocking = (missing) => blockingTargets(missing, scenario.paramsObject, planned, scenario.paramsLogic);
+            const budget = Math.min(this.budgets.deriveMs, this.budgets.hookDeriveMs);
+            const result = await this.waitDerivation(state, derivation, budget);
+            if (result === undefined) {
+                // Out of budget, or the service is cooling down and was not waited on.
+                // The turn has not said what this task is to act on, so every target is
+                // unnamed (R-PARAM-3).
+                const error = `derivation did not answer within ${budget}ms`;
                 const blocked = blocking(targetKeys(scenario.paramsObject));
                 if (blocked.length > 0) {
-                    return decline(`target ${blocked[0]} not found — ${errText(err)}`, "missing_target");
+                    return decline(`target ${blocked[0]} not found — ${error}`, "missing_target");
                 }
                 logLine("replay.targets_unread", {
                     scenario: scenario.id,
                     why: "the derivation did not answer, and this chain takes no target from the caller",
-                    error: errText(err),
+                    error,
                 });
             }
             if (result && !result.derived) {
@@ -301,6 +516,26 @@ export class ReplayController {
                     why: "the chain computes these from its own steps; none is read from the caller",
                 });
             }
+            // The values are in hand: one this plan must not template into its
+            // command (safety.ts) declines here, before any directive is injected,
+            // instead of arming a plan whose first call can only be denied with a
+            // hand-over — a denied call and a model round trip, for nothing. The
+            // same check still runs where the values settle later (`readyFor`).
+            // It travels as `missing_target`: the value read for a target could not
+            // be used, and no new code reaches a service that may not know it.
+            const sink = sinkOfPlan(planned);
+            if (result?.derived && sink) {
+                const bad = unsafeParameter(result.params, scenario.paramsObject, sink);
+                if (bad) {
+                    logLine("replay.unsafe_param", {
+                        scenario: scenario.id,
+                        param: bad.key,
+                        sink,
+                        why: "a value read for this request would be templated into a command unattended — declined before arming",
+                    });
+                    return decline(`the value read for ${bad.key} is not safe to put into a command unattended`, "missing_target");
+                }
+            }
         }
         // A plan armed by intent runs inside a task the agent is already doing, so
         // its directive and its bundles say "continue", never "answer the user"
@@ -313,6 +548,21 @@ export class ReplayController {
             entries,
             subTask: armedBy === "intent",
         });
+        if (mode === "steer") {
+            // A steer directive shows the arguments the steps will run with, so the
+            // call the model writes is one the pin guard accepts (plan.ts,
+            // `steeringDirective`). That needs the parameters settled — which costs
+            // nothing when the derivation has already answered: gate 7 waited for
+            // it, or there was nothing to derive. One turn of the loop lets an answer
+            // that is already in hand through; one still on its way is not waited
+            // for here, and the directive simply leaves the arguments to the system,
+            // as it always did. A `paramsLogic` that throws is not judged here: the
+            // first call that needs the parameters meets the same failure, as before.
+            if (!deriveAnswered)
+                await new Promise((resolve) => setImmediate(resolve));
+            if (deriveAnswered)
+                await state.plan.ready().catch(() => undefined);
+        }
         state.mode = mode;
         state.stepsPlanned = entries.length;
         // Why the plan stops, when a call is what stops it: the note names the
@@ -321,7 +571,9 @@ export class ReplayController {
             typeof stopAt === "number" && flat.stopAt !== undefined && stopAt <= flat.stopAt
                 ? flat.stopReason
                 : undefined;
-        if (this.opts.authUrl && this.opts.authToken) {
+        // Recorded outputs are read only when they may stand in (opt-in), so a
+        // plan never fetches a run it will not show.
+        if (this.recordedFallback && this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
                 runId: scenario.runId,
@@ -351,12 +603,75 @@ export class ReplayController {
         });
         return state;
     }
-    /** The directive to inject via `additionalContext`, or undefined when declined. */
-    directiveFor(state) {
+    /**
+     * The directive to inject via `additionalContext`, or undefined when declined.
+     *
+     * A steer directive previews each step's arguments (plan.ts,
+     * `previewArguments`), which can take up to {@link PREVIEW_BUDGET_MS}.
+     * `previewMs` — the time the caller's hook has left — lowers that bound,
+     * never raises it; under ~10 ms nothing is previewed and the directive keeps
+     * its old wording.
+     */
+    directiveFor(state, opts = {}) {
+        const asked = opts.previewMs;
         return state.plan?.steeringDirective(DIRECT_TOOL_NAME, {
             subTask: state.armedBy === "intent",
+            // NaN is a caller's arithmetic gone wrong: no time known, no preview.
+            previewBudgetMs: typeof asked === "number"
+                ? Math.max(0, Math.min(Number.isNaN(asked) ? 0 : asked, PREVIEW_BUDGET_MS))
+                : undefined,
         });
     }
+    /**
+     * Give a steer plan's parameters a short, bounded chance to settle before its
+     * directive is written, so {@link directiveFor} can show the arguments the
+     * steps run with. Resolves true when they are settled.
+     *
+     * Without it a derivation the service answers — nearly every one, since a
+     * signed-in runner has no key of its own — has never answered by the time
+     * `arm` returns (it waits one turn of the loop, on purpose), the directive
+     * says "the system supplies the exact arguments", the model writes a guessed
+     * command, the pin guard declines it, and the plan retires having run
+     * nothing.
+     *
+     * Only for the steps the pin guard holds to their exact shape — a shell
+     * command, a file write (control/pin-guard.ts) — and never longer than
+     * {@link PREVIEW_SETTLE_MAX_MS} or `budgetMs`, whichever is less: the caller
+     * passes what its prompt hook has left, less what the preview itself needs.
+     * Not at all while the service is cooling down. A late answer is not an
+     * overrun of anything, so it marks nothing against the service. `arm`
+     * itself still never waits (integ-replay R2).
+     */
+    async settleForPreview(state, budgetMs) {
+        const plan = state.plan;
+        if (!plan || state.retired || state.mode !== "steer")
+            return false;
+        if (plan.parametersSettled)
+            return true;
+        const planned = plan.allEntries().slice(0, plan.stepCount);
+        if (!planned.some((e) => pinnedToShape(e.step.toolName)))
+            return false;
+        if (state.deriveOnService && !serviceHealth.canWait())
+            return false;
+        const ms = Math.min(Number.isFinite(budgetMs) ? budgetMs : 0, PREVIEW_SETTLE_MAX_MS);
+        if (ms <= 0)
+            return false;
+        let timer;
+        try {
+            await Promise.race([
+                plan.ready().catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, ms);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        return plan.parametersSettled;
+    }
     /**
      * A hand-over note not yet delivered, claimed for delivery (fallbk.md D4).
      * Returns it once and marks it delivered; undefined when there is none.
@@ -379,9 +694,12 @@ export class ReplayController {
      */
     deliverInstead(text, toolName) {
         if (toolName === "Bash") {
-            const delimiter = "BIR_EOF";
-            const safe = text.split(delimiter).join("BIR_EOF_");
-            return { kind: "bash", command: `cat <<'${delimiter}'\n${safe}\n${delimiter}` };
+            // A short command, whatever the text's size (bash-channel.ts): a long
+            // heredoc is cut by the shell, and a long output by the host.
+            const command = bashCommandFor(truncate(text, BASH_CHANNEL_MAX));
+            if (command)
+                return { kind: "bash", command };
+            // The text could not be staged: the denial reason still carries it.
         }
         return { kind: "deny", reason: text };
     }
@@ -391,23 +709,109 @@ export class ReplayController {
      * Three tiers (§8): pin the expected call; on divergence execute the remainder
      * and hand it back through the best channel available; if even that fails,
      * abort to an ordinary turn.
+     *
+     * `hook` is optional and only ever tightens the work: `answerBy` lowers the
+     * deadline to the caller's own, and `signal` stops a divergence from
+     * starting another step once the host has been answered without it.
      */
-    async preTool(state, toolName, toolUseId) {
+    async preTool(state, toolName, toolUseId, 
+    /** The call's `tool_input`: whether a `Bash` call is only `bir` is read from it (D13). */
+    toolInput, hook = {}) {
         const plan = state.plan;
         if (!plan || state.retired)
             return { kind: "passthrough" };
         // The delivery vehicle for a direct plan is not a step in it.
-        if (this.isDirectTool(toolName))
+        if (this.isDirectTool(toolName)) {
+            state.directRequested = true;
             return { kind: "passthrough" };
-        try {
-            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
         }
-        catch (err) {
-            logLine("replay.derive_failed", {
+        // A direct run is executing this plan right now: another call beside it is
+        // the model's own, and a divergence would drive the same cursor twice.
+        if (state.running)
+            return { kind: "passthrough" };
+        // The model asked for `run_scenario` and the run never started. The usual
+        // reason is the user refusing that call — and executing the plan anyway,
+        // through a divergence, would override that refusal with the very steps it
+        // refused. The model does the task; the plan stays idle.
+        if (state.mode === "direct" && state.directRequested) {
+            logDetail("replay.direct_not_run", {
                 scenario: state.scenarioId ?? undefined,
-                why: "continuing with the scenario's recorded sample values",
-                error: errText(err),
+                tool: toolName,
+                why: "run_scenario was called but never ran (refused, or it never reached bir) — nothing is executed in its place",
+            });
+            return { kind: "passthrough" };
+        }
+        // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`. Asked
+        // before the pin, not after it: a `Bash` step is pinned by name, and a
+        // `bir scenario show` the model runs while a Bash step is expected must
+        // run as `bir`, never be swapped for the plan's command (D13). And before
+        // the wait for the parameters, which a `ToolSearch` has no use for.
+        if (isHousekeepingCall(toolName, toolInput)) {
+            logDetail("replay.housekeeping", {
+                tool: toolName,
+                step: `${plan.currentStepIndex}/${plan.stepCount}`,
+                why: "host bookkeeping, not task work — plan stays armed",
             });
+            return { kind: "passthrough" };
+        }
+        // Everything below — the wait for the parameters, and a divergence that
+        // executes the rest of the plan — happens inside this one hook, which the
+        // host waits on for a bounded time. One deadline covers all of it — and
+        // never reaches past the caller's own answer (`hook.answerBy`), less the
+        // last step's minimum and a margin.
+        // The parameters may be waited on until the margin before that answer; a
+        // step may only *start* until its minimum before it as well.
+        const answerBy = typeof hook.answerBy === "number" && Number.isFinite(hook.answerBy)
+            ? hook.answerBy - PRETOOL_MARGIN_MS
+            : Number.POSITIVE_INFINITY;
+        const deadline = Math.min(Date.now() + this.budgets.preToolMs, answerBy - MIN_STEP_MS);
+        const ready = await this.readyFor(state, plan, Math.max(0, Math.min(this.budgets.deriveMs, this.budgets.hookDeriveMs, answerBy - Date.now())));
+        // Another call may have retired the plan while this one waited — or the
+        // host may have been answered without this call's action.
+        if (state.retired || hook.signal?.aborted)
+            return { kind: "passthrough" };
+        if (!ready.ok) {
+            // Nothing may run on parameters that are unknown, unprocessed or unsafe.
+            // The model does the task itself — told so in place of this call.
+            const step = plan.currentStep();
+            if (step && ready.blame) {
+                this.recordStep(state, { step, outcome: "failed", stage: ready.stage, error: ready.error });
+            }
+            this.handOver(state, {
+                kind: "step_failed",
+                step,
+                entry: plan.currentEntry(),
+                position: plan.currentStepIndex,
+                error: ready.error,
+                delivery: "above",
+                stopReason: "not_run",
+            });
+            const note = this.takeNote(state);
+            return note ? this.deliverInstead(note, toolName) : { kind: "abort" };
+        }
+        // ONE CALL AT A TIME. A pin moves the cursor only when its output threads,
+        // which for a wrapped step is the proxy's report — landing either side of
+        // `PostToolUse`, or up to the control server's 1.5 s fallback after it
+        // when no report comes (a standalone proxy). A call arriving before that
+        // would be pinned to the very same step (it would run twice,
+        // auto-approved), or would diverge and re-execute the step still in
+        // flight. So it first waits, briefly and within this hook's deadline, for
+        // the pin to thread: the model's *next* call after a finished one is the
+        // ordinary sequential case, and must be judged against the moved cursor —
+        // never handed over as "concurrent". Only a pin still out after that is a
+        // call really running beside this one, and then the plan hands over, and
+        // this call carries the note that says so.
+        if (state.pinned.size > 0 && !state.pinned.has(toolUseId)) {
+            // With the plan's last step in flight there is nothing left to pin twice:
+            // this call is the model's own whatever that step does, so it never waits.
+            const lastInFlight = [...state.pinned.values()].some((p) => p.stepIndex + 1 >= plan.stepCount);
+            if (!lastInFlight)
+                await this.awaitPins(state, toolUseId, deadline);
+            if (state.retired || hook.signal?.aborted)
+                return { kind: "passthrough" };
+            if (state.pinned.size > 0 && !state.pinned.has(toolUseId)) {
+                return this.concurrentCall(state, plan, toolName);
+            }
         }
         // A direct plan does not steer individual calls: the model was asked for one
         // tool call and made a different one. That is divergence.
@@ -460,16 +864,140 @@ export class ReplayController {
                 return { kind: "abort" };
             }
         }
-        // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`.
-        if (isHousekeeping(toolName)) {
-            logDetail("replay.housekeeping", {
+        return await this.diverge(state, toolName, `expected ${expected ?? "no more tools"}, model called ${toolName}`, deadline, hook.signal);
+    }
+    /**
+     * A call arrived while another pinned call's output has not threaded yet
+     * (see `preTool`). The plan stops here rather than pin a step twice.
+     */
+    concurrentCall(state, plan, toolName) {
+        const outstanding = [...state.pinned.values()][0];
+        const next = (outstanding?.stepIndex ?? plan.currentStepIndex) + 1;
+        if (next >= plan.stepCount) {
+            // The call in flight is the plan's last step: nothing is left to pin
+            // twice, and this call is the model's own.
+            logDetail("replay.concurrent_call", {
+                scenario: state.scenarioId ?? undefined,
                 tool: toolName,
-                step: `${plan.currentStepIndex}/${plan.stepCount}`,
-                why: "host bookkeeping, not task work — plan stays armed",
+                why: "the last step is in flight — this call is the model's own",
             });
             return { kind: "passthrough" };
         }
-        return await this.diverge(state, toolName, `expected ${expected ?? "no more tools"}, model called ${toolName}`);
+        logLine("replay.concurrent_call", {
+            scenario: state.scenarioId ?? undefined,
+            tool: toolName,
+            inFlight: outstanding ? `${outstanding.stepIndex}:${outstanding.toolName}` : undefined,
+            why: "a second call arrived while the pinned step was still running — a plan runs one call at a time, so the rest is handed over",
+        });
+        // No outcome of its own: the model, not the plan, does the rest, so this
+        // is no divergence saving. `handOver` books `fell_back` if earlier steps
+        // threaded and `failed` if none did — and the pins still in flight stay
+        // readable, so a step among them that finishes is still counted.
+        //
+        // The pin in flight is *not* counted as run. It may be running, or it may
+        // never run at all — the user's own deny rule or PreToolUse hook blocked
+        // it, and no PostToolUse will ever come. The note says exactly that,
+        // rather than "Steps 1–N ran … do not repeat them" about a call that may
+        // not have happened.
+        const inFlight = new Map(state.pinned);
+        this.handOver(state, {
+            kind: "step_failed",
+            step: plan.allSteps()[next],
+            entry: plan.allEntries()[next],
+            position: next,
+            delivery: "above",
+            stopReason: "concurrent",
+            ran: outstanding ? outstanding.stepIndex : plan.currentStepIndex,
+            inFlight: outstanding
+                ? { stepIndex: outstanding.stepIndex, toolName: outstanding.toolName }
+                : undefined,
+        });
+        if (inFlight.size > 0)
+            state.lingering = inFlight;
+        const note = this.takeNote(state);
+        return note ? this.deliverInstead(note, toolName) : { kind: "passthrough" };
+    }
+    /**
+     * Wait until the plan's outstanding pins thread, or until waiting is no
+     * longer worth it (see `preTool`, ONE CALL AT A TIME).
+     *
+     * Always bounded by the hook's `deadline`. Within it:
+     *  - every pin finished by the host ({@link hostCompleted}): until
+     *    {@link PIN_THREAD_WAIT_MS} after the last of them finished — the
+     *    server's fallback has threaded it by then, if anything will;
+     *  - the server is known to report host completions and a pin is not
+     *    finished: a call really running beside this one, which may run for
+     *    minutes, so only {@link HOST_RACE_MS} in case its completion is racing
+     *    this hook;
+     *  - otherwise (a server that reports nothing): {@link PIN_THREAD_WAIT_MS}.
+     */
+    async awaitPins(state, toolUseId, deadline) {
+        const startedAt = Date.now();
+        const outstanding = () => [...state.pinned.entries()].filter(([id]) => id !== toolUseId).map(([, pin]) => pin);
+        for (;;) {
+            if (state.retired)
+                return;
+            const pins = outstanding();
+            if (pins.length === 0)
+                return;
+            const hostDone = pins.map((p) => p.hostDoneAt);
+            const finished = hostDone.every((t) => t !== undefined);
+            const until = Math.min(deadline, finished
+                ? Math.max(...hostDone) + PIN_THREAD_WAIT_MS
+                : startedAt + (this.hostSignals ? HOST_RACE_MS : PIN_THREAD_WAIT_MS));
+            const left = until - Date.now();
+            if (left <= 0) {
+                logDetail("replay.pin_wait", {
+                    scenario: state.scenarioId ?? undefined,
+                    waitedMs: Date.now() - startedAt,
+                    why: "the previous pinned step has not threaded — judged a call beside it",
+                });
+                return;
+            }
+            await this.pinChange(state, left);
+        }
+    }
+    /** Resolves on the next change to a plan's pins, or after `ms`. */
+    pinChange(state, ms) {
+        return new Promise((resolve) => {
+            let waiters = this.pinWaiters.get(state);
+            if (!waiters) {
+                waiters = new Set();
+                this.pinWaiters.set(state, waiters);
+            }
+            const set = waiters;
+            const done = () => {
+                clearTimeout(timer);
+                set.delete(done);
+                resolve();
+            };
+            const timer = setTimeout(done, Math.max(0, ms));
+            timer.unref?.();
+            set.add(done);
+        });
+    }
+    /** Wake every call waiting on this plan's pins. */
+    notifyPins(state) {
+        const waiters = this.pinWaiters.get(state);
+        if (!waiters || waiters.size === 0)
+            return;
+        for (const wake of [...waiters])
+            wake();
+    }
+    /**
+     * The host finished a call (`PostToolUse` / `PostToolUseFailure`) — whether
+     * or not its output has threaded yet. The control server calls this for
+     * every pinned call; it is what tells the model's next, sequential call
+     * apart from one running beside a pin (see `awaitPins`). Optional: without
+     * it every such call waits the bounded {@link PIN_THREAD_WAIT_MS}.
+     */
+    hostCompleted(state, toolUseId) {
+        const pin = state?.pinned.get(toolUseId);
+        this.hostSignals = true;
+        if (!state || !pin || pin.hostDoneAt !== undefined)
+            return;
+        pin.hostDoneAt = Date.now();
+        this.notifyPins(state);
     }
     /**
      * `PostToolUse` for a call this plan pinned.
@@ -478,17 +1006,72 @@ export class ReplayController {
      * wrapped MCP step that is the proxy's whole `CallToolResult`, which is why the
      * server threads those from `/proxy/step` rather than from the hook (§7.2).
      * Returns true when the plan is now complete.
+     *
+     * `failed` is the host's verdict that the call failed — `PostToolUseFailure`,
+     * or a proxy report with `isError` — with its error text when there is one.
+     * It outranks anything read from `output`: a built-in's response is Claude
+     * Code's rendering and is never judged here, so for an `Edit` whose
+     * `old_string` moved since the recording this is the only word there is. A
+     * step that failed must never thread as if it worked: the next step would be
+     * pinned, and auto-approved, on top of it.
+     *
+     * Not every failure is one. A call its proxy *abandoned* — the upstream
+     * closed, restarted or was cancelled mid-call, reported with `isError` and
+     * no result — may well have done its work, and so may one the host says
+     * timed out or was interrupted: the note says "may or may not have
+     * completed", never "failed", or the model runs a write a second time
+     * ({@link pinFailure}). `how` lets the caller say so outright.
      */
-    postTool(state, toolUseId, output) {
+    postTool(state, toolUseId, output, failed, how = {}) {
         const plan = state.plan;
+        if (plan && state.retired) {
+            this.lateThread(state, plan, toolUseId, output, failed, how);
+            return false;
+        }
         const pin = state.pinned.get(toolUseId);
         if (!plan || !pin || state.retired)
             return false;
         state.pinned.delete(toolUseId);
+        // A call waiting for this pin (`awaitPins`) re-reads the cursor once this
+        // synchronous method has finished moving it.
+        this.notifyPins(state);
         // The pin's own step, not `currentStep()`: `applyOutput` moves the cursor, so
         // reading it after the call would judge the *next* step, and reading it
         // before assumes no other pin ever moved it.
         const step = plan.allSteps()[pin.stepIndex];
+        // The output threads into the step at the cursor. One pin at a time
+        // (`preTool`) keeps that the pin's own step; if it ever is not, threading
+        // would feed one step's output to another's logic, so the plan stops.
+        //
+        // A proxy-threaded call that reports *no result* was sent and abandoned —
+        // its upstream died mid-call (tool-error.ts, `isNoResult`). It may or may
+        // not have done its work, and nothing may be pinned on top of it.
+        const failure = pinFailure(pin, output, failed, how);
+        const hostError = failure?.error;
+        if (step && (hostError !== undefined || plan.currentStepIndex !== pin.stepIndex)) {
+            const error = hostError ??
+                `the plan's cursor is at step ${plan.currentStepIndex}, not the pinned step ${pin.stepIndex}`;
+            const info = {
+                step,
+                outcome: "failed",
+                stage: "tool_call",
+                error,
+                ms: Date.now() - pin.pinnedAt,
+            };
+            this.logStep(info);
+            if (hostError !== undefined)
+                this.recordStep(state, info);
+            this.handOver(state, {
+                kind: "step_failed",
+                step,
+                entry: plan.allEntries()[pin.stepIndex],
+                position: pin.stepIndex,
+                error,
+                delivery: "above",
+                stopReason: failure?.reason,
+            });
+            return false;
+        }
         let derivedKeys = [];
         try {
             derivedKeys = plan.applyOutput(output);
@@ -599,38 +1182,132 @@ export class ReplayController {
         }
         return done;
     }
+    /**
+     * The result of a call pinned under a plan that has since handed over
+     * because another call ran beside it (`concurrentCall`). Nothing threads —
+     * the plan is retired and the model is doing the rest — but the step's
+     * verdict is recorded, and a step that did its work is counted: the outcome
+     * moves from `failed` to `fell_back` when it is the first that did.
+     */
+    lateThread(state, plan, toolUseId, output, failed, how = {}) {
+        const pin = state.lingering?.get(toolUseId);
+        if (!pin)
+            return;
+        state.lingering.delete(toolUseId);
+        const step = plan.allSteps()[pin.stepIndex];
+        if (!step)
+            return;
+        const ms = Date.now() - pin.pinnedAt;
+        // Read the same way as a live pin's (`pinFailure`). A call that was sent
+        // and not seen through says so in its verdict: it may have done its work.
+        const failure = pinFailure(pin, output, failed, how);
+        const error = failure
+            ? failure.reason === "uncertain"
+                ? `${failure.error} — it was sent, and may or may not have completed`
+                : failure.error
+            : toolResultError(output);
+        if (error !== undefined) {
+            const info = { step, outcome: "failed", stage: "tool_call", error, ms };
+            this.logStep(info);
+            this.recordStep(state, info);
+            return;
+        }
+        this.recordStep(state, { step, outcome: "executed", ms });
+        state.stepsPinned += 1;
+        this.upgrade(state, "fell_back");
+        logDetail("replay.thread_late", {
+            scenario: state.scenarioId ?? undefined,
+            n: pin.stepIndex,
+            why: "a step pinned before the hand-over finished — counted, not threaded",
+        });
+    }
     /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
     threadsFromProxy(state, toolUseId) {
-        return state.pinned.get(toolUseId)?.reach === "direct";
+        const pin = state.pinned.get(toolUseId) ?? state.lingering?.get(toolUseId);
+        return pin?.reach === "direct";
     }
-    /** True when this call belongs to the active plan. */
+    /**
+     * True when this call belongs to the plan: pinned by it and not yet
+     * threaded — including a pin still in flight when the plan handed over, so
+     * its result still reaches `postTool` (see `lateThread`).
+     */
     isPinned(state, toolUseId) {
-        return state.pinned.has(toolUseId);
+        return state.pinned.has(toolUseId) || state.lingering?.has(toolUseId) === true;
     }
     /**
      * `POST /scenario/run` — the whole of a `direct` plan, executed here.
      *
      * Every step runs through the proxy that already owns its upstream, so the
      * model spends nothing beyond the turn that reads the results.
+     *
+     * `signal` aborts when the caller is gone — `bir-scenario`'s request was
+     * cancelled (Esc) or timed out — so no further step is started (C4). The
+     * worst case this can take is `deriveMs + planMs` plus one step's
+     * `MIN_STEP_MS`, six logic bodies at their full limit and a 5 s margin —
+     * 120 s by default, more only for a plan budget an operator raised
+     * ({@link clampDirectRun}) — which `bir-scenario`'s own timeout (290 s) must
+     * exceed, and which is held under {@link DIRECT_RUN_CEILING_MS} whatever the
+     * environment asks for. That bound counts every body at its limit; a run
+     * that does not stall ends well inside its plan budget.
+     *
+     * One run per plan: a second call while the first is running gets the first
+     * one's answer, never a second execution of the same steps.
      */
-    async runArmed(state) {
+    async runArmed(state, signal) {
         const plan = state.plan;
         if (!plan || state.retired)
-            return { ok: false, why: "no_plan" };
-        try {
-            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
-        }
-        catch (err) {
-            logLine("replay.derive_failed", {
+            return { ok: false, why: RUN_NO_PLAN };
+        if (state.running)
+            return state.running;
+        const running = this.runArmedOnce(state, plan, signal).catch((err) => {
+            // Never a throw at a hook: a broken run is the model's task again.
+            logLine("replay.failed", {
                 scenario: state.scenarioId ?? undefined,
-                why: "continuing with the scenario's recorded sample values",
+                why: "the run threw — continuing as a normal run",
                 error: errText(err),
             });
+            this.retire(state, "failed");
+            return { ok: false, why: "the scenario could not be run" };
+        });
+        state.running = running;
+        return running;
+    }
+    async runArmedOnce(state, plan, signal) {
+        // `/scenario/run` has no hook timeout, so this is the one place the full
+        // derivation budget is waited — and still not while the service is
+        // cooling down.
+        const ready = await this.readyFor(state, plan, this.budgets.deriveMs);
+        if (state.retired)
+            return { ok: false, why: RUN_NO_PLAN };
+        if (!ready.ok) {
+            // Nothing may run on parameters that are unknown, unprocessed or unsafe.
+            // The tool answers with an error that says so, which is what a model
+            // reacts to best: it does the task itself.
+            const step = plan.currentStep();
+            if (step && ready.blame) {
+                this.recordStep(state, {
+                    step,
+                    entry: plan.currentEntry(),
+                    outcome: "failed",
+                    stage: ready.stage,
+                    error: ready.error,
+                });
+            }
+            this.handOver(state, {
+                kind: "step_failed",
+                step,
+                entry: plan.currentEntry(),
+                position: plan.currentStepIndex,
+                error: ready.error,
+                delivery: "none",
+                stopReason: "not_run",
+            });
+            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: ready.error };
         }
         const deadline = Date.now() + this.budgets.planMs;
         let result;
         try {
-            result = await plan.runToCompletion(this.executeStep(state), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true });
+            result = await plan.runToCompletion(this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true, recordedFallback: this.recordedFallback, signal });
         }
         catch (err) {
             // The scenario's own logic failed. Retire and let the model do the work.
@@ -642,15 +1319,33 @@ export class ReplayController {
             this.retire(state, "failed");
             return { ok: false, why: "not_ready" };
         }
-        // The plan stopped part-way (fallbk.md §Runner 3): a step broke, or the
-        // next one is parked. The steps that ran are real, so their bundle goes to
-        // the model — behind a note saying the rest of the task is its own.
+        // The plan stopped part-way (fallbk.md §Runner 3): a step broke or produced
+        // no result, the next one is parked, the budget ran out, or the caller left.
+        // The steps that ran are real, so their bundle goes to the model — behind a
+        // note saying the rest of the task is its own.
         if (result.stopped) {
             const stop = result.stopped;
-            const ranOk = result.executed + result.recorded - result.errored;
+            // Only live steps did work here. A recorded stand-in is last week's
+            // output (BIR_REPLAY_RECORDED_OUTPUTS): it books nothing, and a run of
+            // them alone is a baseline sample, not a hand-over "saving".
+            const ranOk = result.executed - result.errored;
             state.stepsPinned += Math.max(0, ranOk);
             const position = stop.flatIndex ?? plan.stepCount;
             const step = plan.allSteps()[position];
+            // Cut short by the clock, nothing failed: the steps that ran did their
+            // work and none is blamed. A divergence for the ledger — a partial
+            // saving, no fallback step — as a budget stop always was.
+            if (stop.reason === "budget" && ranOk > 0)
+                this.upgrade(state, "diverged");
+            // Cut short by the *caller* — Esc on run_scenario, or its client timing
+            // out — is no saving at all: the turn it ended cost next to nothing and
+            // says nothing about what the task costs. `handOver` books `fell_back`
+            // (steps did run) or `failed`, and the report is not a measurement.
+            if (stop.reason === "cancelled")
+                state.callerCancelled = true;
+            // Nothing ran *here*: there is no bundle, only the task — a recorded
+            // output is not a result that happened (plan.ts, DriveOptions).
+            const live = result.executed > 0;
             this.handOver(state, {
                 // The plan only knows it stopped in front of its end; which kind of
                 // stop that is — parked, a judgement, a call that cannot run — is
@@ -660,13 +1355,36 @@ export class ReplayController {
                 entry: plan.allEntries()[position],
                 position,
                 error: stop.error,
-                delivery: "below",
+                // A cancelled run's note is kept for the model's next call, alone —
+                // the bundle went to a caller who is gone — so it points at side
+                // effects in place, never at results "below" that nobody receives.
+                delivery: live && stop.reason !== "cancelled" ? "below" : "none",
+                stopReason: stop.reason,
+                ran: live ? undefined : 0,
+                // An output-logic failure stops *after* its step's tool ran: the step
+                // is done, its result is in the bundle, and it must not be run again.
+                ranThisStep: stop.stage === "tool_output_logic",
             });
+            if (stop.reason === "cancelled") {
+                // The caller is gone and reads nothing. The note stays undelivered: a
+                // client that timed out hands the task back to the model in this same
+                // turn, and the model's next call is where it learns which steps
+                // already ran — before it runs them a second time.
+                logLine("replay.cancelled", {
+                    scenario: state.scenarioId ?? undefined,
+                    ran: `${result.executed}/${plan.stepCount}`,
+                    why: "the caller went away — no further step was started",
+                });
+                const note = state.handover?.note ?? "";
+                return live
+                    ? { ok: true, text: `${note}\n\n${result.text}`, responseModel: {}, steps: result.executed + result.recorded, partial: true }
+                    : (handedOver(note) ?? { ok: false, why: note });
+            }
             const note = this.takeNote(state) ?? state.handover?.note ?? "";
-            if (result.executed + result.recorded === 0) {
-                // Nothing ran: there is no bundle, only the task. The tool answers with
-                // an error that says so, which is what a model reacts to best.
-                return { ok: false, why: note };
+            if (!live) {
+                // Nothing ran: the tool answers with an error that says so, which is
+                // what a model reacts to best.
+                return handedOver(note) ?? { ok: false, why: note };
             }
             return {
                 ok: true,
@@ -676,7 +1394,24 @@ export class ReplayController {
                 partial: result.partial,
             };
         }
-        state.stepsPinned += result.executed + result.recorded;
+        if (result.executed === 0) {
+            // Every step stood on its recorded output (BIR_REPLAY_RECORDED_OUTPUTS):
+            // nothing happened here, and an answer built on last week's outputs is
+            // not a replay. The model does the task.
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.allSteps()[0],
+                entry: plan.allEntries()[0],
+                position: 0,
+                error: "none of the scenario's steps could run here",
+                delivery: "none",
+                stopReason: "not_run",
+                ran: 0,
+            });
+            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: "" };
+        }
+        // Live steps only, as above: a recorded stand-in did no work here.
+        state.stepsPinned += result.executed;
         let responseModel = {};
         try {
             responseModel = plan.responseModel();
@@ -687,9 +1422,11 @@ export class ReplayController {
         // A plan whose tools errored ran to the end and did nothing. `steered_full`
         // would book the largest saving available for it; `failed` books a baseline
         // sample, which is what a replay that produced nothing is worth (mcpmark.md §13).
+        // A step that stood on a recorded output did not happen here either, so a
+        // plan with one is at best a divergence.
         this.upgrade(state, result.errored > 0
             ? "failed"
-            : result.partial || result.skipped > 0
+            : result.partial || result.skipped > 0 || result.recorded > 0
                 ? "diverged"
                 : "steered_full");
         // `runToCompletion` returned without a stop: the plan ran to its end, so
@@ -752,7 +1489,9 @@ export class ReplayController {
             durationMs: d.durationMs,
             stepsPlanned: state.stepsPlanned,
             stepsPinned: state.stepsPinned,
-            measured: d.measured,
+            // A run its caller cancelled ended the turn early: its cost is no
+            // measurement of the task, whatever the transcript says.
+            measured: d.measured && state.callerCancelled !== true,
             pricingVersion: PRICING_VERSION,
             prompt: d.prompt,
             steps,
@@ -881,6 +1620,7 @@ export class ReplayController {
             mode,
             entries: flat.entries,
             stopAt: flat.stopAt,
+            fallbackTargets: "samples",
         });
         state.plan = plan;
         state.flatStop = flat.stopReason;
@@ -899,15 +1639,19 @@ export class ReplayController {
             coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers).join(","),
             why: "bir replay — no match, an operator asked for it",
         });
-        try {
-            await this.withBudget(plan.ready(), this.budgets.deriveMs, "derivation");
-        }
-        catch (err) {
-            logLine("replay.derive_failed", { scenario: scenario.id, error: errText(err) });
-        }
+        // An operator's run keeps its own contract (R-CALL-37): out of time, the
+        // targets too take their samples. What it never does is run on `{}`.
+        const ready = await this.readyFor(state, plan, this.adHocBudgets.deriveMs, { adHoc: true });
+        if (!ready.ok)
+            return { ok: false, why: ready.error };
         const trace = [];
+        const deadline = Date.now() + this.adHocBudgets.planMs;
         try {
-            const result = await plan.runToCompletion(this.executeStep(state), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, (info) => {
+            const result = await plan.runToCompletion(this.executeStep(state, { deadline, adHoc: true }), 
+            // The operator reads a per-step trace that labels every stand-in, so
+            // `bir replay` keeps serving recorded outputs for steps that cannot be
+            // sent from here — and still stops at one that was sent and failed.
+            this.recordedSource(state, true), (info) => {
                 this.observeStep(state)(info);
                 trace.push({
                     step: info.step.stepIndex,
@@ -916,7 +1660,7 @@ export class ReplayController {
                     outcome: info.outcome,
                     ms: info.ms,
                 });
-            }, Date.now() + this.budgets.planMs);
+            }, deadline, MAX_REPLAY_REASON, { recordedFallback: true });
             let responseModel = {};
             try {
                 responseModel = plan.responseModel();
@@ -924,6 +1668,8 @@ export class ReplayController {
             catch (err) {
                 logDetail("replay.response_model_failed", { error: errText(err) });
             }
+            const stop = result.stopped;
+            const stoppedStep = stop ? plan.allSteps()[stop.flatIndex ?? plan.stepCount] : undefined;
             return {
                 ok: true,
                 text: result.text,
@@ -931,6 +1677,14 @@ export class ReplayController {
                 steps: result.executed + result.recorded,
                 partial: result.partial,
                 trace,
+                stopped: stop
+                    ? {
+                        step: stop.stepIndex,
+                        tool: stoppedStep?.toolName ?? "",
+                        reason: stop.reason ?? stop.stage ?? stop.kind,
+                        error: stop.error,
+                    }
+                    : undefined,
             };
         }
         catch (err) {
@@ -965,17 +1719,26 @@ export class ReplayController {
     }
     startDerivation(scenario, prompt, state, ctx = {}) {
         const derive = this.opts.deriveImpl ?? deriveParameters;
+        const apiKey = this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        const service = this.deriveService(scenario.id);
+        const hasSchema = Object.keys(scenario.paramsObject ?? {}).length > 0;
+        state.deriveOnService = !apiKey && service !== undefined && hasSchema;
         return derive({
             prompt,
             intent: scenario.intent ?? "",
             paramsObject: scenario.paramsObject,
-            apiKey: this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+            apiKey,
             // Where to ask when there is no key here, which is the ordinary case
             // (segmented.md R-PARAM-5).
-            service: this.deriveService(scenario.id),
+            service,
             fetchImpl: this.opts.fetchImpl,
             liveCall: ctx.liveCall,
             recentResults: ctx.recentResults,
+            // The request itself ends too. Without this a hung service or model held
+            // the socket for up to 300 s after every wait on it had given up. Long
+            // enough to cover both waits that can use its answer (the arm and the
+            // first tool call); an answer after that is read by nobody.
+            signal: timeoutSignal(Math.max(serviceTimeoutMs(), this.budgets.deriveMs)),
         })
             .then((r) => {
             state.deriveCostUsd += r.costUsd;
@@ -1026,8 +1789,14 @@ export class ReplayController {
      *
      * The plan is retired first: whatever happens next, this turn neither steers
      * nor re-injects again.
+     *
+     * This runs inside the diverging call's `PreToolUse`, so `deadline` bounds
+     * it: no step is started after it, and none is waited on past it. The bundle
+     * then says exactly what ran, and hands the rest over.
      */
-    async diverge(state, toolName, why) {
+    async diverge(state, toolName, why, deadline, 
+    /** Aborted once the host has its answer: no further step is started. */
+    signal) {
         const plan = state.plan;
         if (!plan)
             return { kind: "passthrough" };
@@ -1039,11 +1808,19 @@ export class ReplayController {
             why,
         });
         this.retire(state, undefined);
+        // The bundle, and the note in front of it, must fit the channel it goes
+        // out on whole: the host cuts a long Bash output in the middle.
+        const channelMax = toolName === "Bash" ? BASH_CHANNEL_MAX : MAX_REPLAY_REASON;
         let composed;
         try {
-            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(state), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), 
-            // A parked step ends the bundle short of the task (fallbk.md D3).
-            { handover: plan.stopsEarly() });
+            composed = await plan.composeBundle(Math.max(2_000, channelMax - MAX_HANDOVER_NOTE - 2), this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), {
+                // A parked step ends the bundle short of the task (fallbk.md D3).
+                handover: plan.stopsEarly(),
+                stopOnFailure: true,
+                recordedFallback: this.recordedFallback,
+                deadline,
+                signal,
+            });
         }
         catch (err) {
             this.upgrade(state, "failed");
@@ -1054,18 +1831,34 @@ export class ReplayController {
             });
             return { kind: "abort" };
         }
-        // Same rule as `runArmed`: a recovered chain whose tools errored is `failed`.
-        this.upgrade(state, composed.errored > 0 ? "failed" : "diverged");
-        state.stepsPinned += composed.executed + composed.recorded;
+        const stop = composed.stopped;
+        // Same rule as `runArmed`: a recovered chain whose tools errored is
+        // `failed`, and so is one that stopped at a step that broke — its logic
+        // threw, or it was sent and failed or never answered. A step that simply
+        // could not be sent from here, or the hook's clock, is still a divergence.
+        const broke = composed.errored > 0 ||
+            (stop !== undefined &&
+                stop.reason !== "not_run" &&
+                stop.reason !== "budget" &&
+                stop.reason !== "cancelled");
+        // And a divergence is booked only when something ran under the plan — a
+        // step pinned before it, or one executed now. One that stopped in front of
+        // its first step (a built-in, which only the session runs) ran nothing and
+        // delivered nothing: no saving, a baseline sample, as `handOver` books it.
+        // Recorded stand-ins are no work here (BIR_REPLAY_RECORDED_OUTPUTS).
+        const didWork = composed.executed > 0 || state.stepsPinned > 0;
+        this.upgrade(state, broke || !didWork ? "failed" : "diverged");
+        state.stepsPinned += composed.executed;
         // The headline number of this whole design: recovering from a divergence
         // costs nothing, because the proxies were already connected.
         logLine("replay.compose", {
             scenario: state.scenarioId ?? undefined,
-            remaining: composed.executed + composed.recorded + composed.skipped,
+            remaining: plan.stepCount - plan.currentStepIndex,
             executed: composed.executed,
             recorded: composed.recorded,
             skipped: composed.skipped,
             errored: composed.errored || undefined,
+            stopped: stop ? `${stop.flatIndex ?? "?"}:${stop.reason ?? stop.stage ?? stop.kind}` : undefined,
             bytes: composed.text.length,
             costUsd: state.fallbackCostUsd.toFixed(2),
         });
@@ -1076,15 +1869,26 @@ export class ReplayController {
             outcome: state.outcome,
             ms: Date.now() - state.armedAt,
         });
-        if (composed.executed + composed.recorded === 0) {
-            // Nothing survived; a bundle of nothing is worse than no bundle.
+        if (composed.executed === 0) {
+            // Nothing ran here: a bundle of nothing is worse than no bundle, and one
+            // of recorded outputs only is last week's work. The model's own call goes
+            // ahead — unless a step was *sent* and never answered. That one may have
+            // done its work, and the model must know before it does the task itself.
+            if (stop?.reason === "uncertain" && stop.flatIndex !== undefined) {
+                const note = this.stopNote(state, plan, stop, "none");
+                return this.deliverInstead(note, toolName);
+            }
             return { kind: "abort" };
         }
-        // The bundle stops in front of a parked step: say so ahead of it, and the
-        // model carries on from there. The outcome stays `diverged` — the model
-        // went off-script first — so the report carries no fallback fields.
+        // The bundle stops short of the task: say so ahead of it — which step, and
+        // what may be assumed about it — and the model carries on from there. The
+        // outcome stays as judged above, so the report carries no fallback fields.
         let text = composed.text;
-        if (plan.stopsEarly()) {
+        if (stop && stop.kind === "step_failed" && stop.flatIndex !== undefined) {
+            const note = this.stopNote(state, plan, stop, "below");
+            text = `${note}\n\n${composed.text}`;
+        }
+        else if (plan.stopsEarly()) {
             const parked = plan.stopStep();
             const stopKind = this.stopKindOf(state, plan.stopEntry());
             state.handover = {
@@ -1097,6 +1901,7 @@ export class ReplayController {
                     entry: plan.stopEntry(),
                     position: plan.stepCount,
                     delivery: "below",
+                    executedAbove: plan.currentStepIndex,
                 }),
                 delivered: true,
             };
@@ -1104,11 +1909,46 @@ export class ReplayController {
         }
         // Bash-clean delivery: the model reaches for `Bash` when it cannot call a
         // scripted tool, and a genuine command output is trusted where a `deny`
-        // reason is read as adversarial interception. Neutralise the delimiter first.
+        // reason is read as adversarial interception.
         const action = this.deliverInstead(text, toolName);
         logDetail("replay.inject", { channel: action.kind, bytes: text.length });
         return action;
     }
+    /**
+     * The note for a divergence bundle that stopped at a step, recorded as this
+     * plan's hand-over (already delivered — it goes out with the bundle), so the
+     * model's own work from here is recorded as a fragment.
+     */
+    stopNote(state, plan, stop, delivery) {
+        const position = stop.flatIndex ?? plan.currentStepIndex;
+        const step = plan.allSteps()[position];
+        const entry = plan.allEntries()[position];
+        const note = this.noteFor(state, {
+            kind: stop.kind,
+            step,
+            entry,
+            position,
+            error: stop.error,
+            delivery,
+            stopReason: stop.reason,
+            // The steps before the cursor ran in the live session — the model's own
+            // pinned calls, just above. With no bundle (`none`) they are the only
+            // steps that ran; "no step ran" would invite the model to run them again.
+            ran: delivery === "none" ? plan.currentStepIndex : undefined,
+            executedAbove: plan.currentStepIndex,
+            // An output-logic failure stops after its step's tool ran (plan.ts).
+            ranThisStep: stop.stage === "tool_output_logic",
+        });
+        state.handover ??= {
+            kind: stop.kind,
+            stepIndex: callerStepIndexOf(entry) ?? step?.stepIndex ?? position,
+            toolName: step?.toolName ?? undefined,
+            error: stop.error,
+            note,
+            delivered: true,
+        };
+        return note;
+    }
     /**
      * Hand the rest of the task to the model (fallbk.md D4/D5).
      *
@@ -1150,7 +1990,13 @@ export class ReplayController {
                     ? "the next step has failed too often — the agent continues from here"
                     : h.kind === "nondeterministic_step"
                         ? "the next step needs a judgement the plan cannot compute — the agent makes it"
-                        : "a step broke — the agent continues from here",
+                        : h.stopReason === "concurrent"
+                            ? "a second call arrived while the pinned step was still running — the agent continues from here"
+                            : h.stopReason === "budget" || h.stopReason === "cancelled"
+                                ? "the run was cut short before this step — the agent continues from here"
+                                : h.stopReason === "not_run" || h.stopReason === "uncertain"
+                                    ? "a step produced no result here — the agent continues from here"
+                                    : "a step broke — the agent continues from here",
         });
     }
     /**
@@ -1166,7 +2012,7 @@ export class ReplayController {
     }
     noteFor(state, h) {
         const plan = state.plan;
-        const executed = h.ranThisStep ? h.position + 1 : h.position;
+        const executed = h.ran ?? (h.ranThisStep ? h.position + 1 : h.position);
         let params;
         try {
             params = plan?.parameters;
@@ -1181,6 +2027,7 @@ export class ReplayController {
             stepToolName: h.step?.toolName ?? undefined,
             failureCount: h.step?.failureCount,
             error: h.error,
+            stopReason: h.stopReason,
             unusable: state.flatStop
                 ? {
                     reason: state.flatStop.reason,
@@ -1192,6 +2039,9 @@ export class ReplayController {
             ownerScenarioId: h.entry && h.entry.depth > 0 ? h.entry.scenarioId : undefined,
             inSubTask: h.entry && h.entry.depth > 0 ? (h.entry.frame.callIntent ?? null) : null,
             executed: Math.max(0, Math.min(executed, plan?.totalSteps ?? executed)),
+            executedAbove: h.executedAbove,
+            inFlight: h.inFlight,
+            ranThisStep: h.ranThisStep,
             totalSteps: plan?.totalSteps ?? state.stepsPlanned,
             remainingTools: plan ? plan.toolsFrom(h.ranThisStep ? h.position + 1 : h.position) : [],
             params,
@@ -1202,22 +2052,173 @@ export class ReplayController {
      * The executor handed to a plan: dispatch a step to the proxy that owns its
      * upstream.
      *
-     * Rejecting means "could not be run **here**" — which is the only condition
-     * under which a recorded output may stand in. A tool that ran and failed
-     * resolves with its failure as the response, exactly as it would in a session.
+     * A tool that ran and failed resolves with its failure as the response,
+     * exactly as it would in a session. A rejection is a {@link StepRunError}
+     * saying what happened to the call — not sent, sent and unanswered, or
+     * refused — because the model is told differently about each (plan.ts).
+     *
+     * `deadline` is the whole run's: no step is waited on past it (but each gets
+     * at least {@link MIN_STEP_MS}). `adHoc` is `bir replay`, which the operator
+     * asked for by id and which the allowlist does not gate.
      */
-    executeStep(state) {
+    executeStep(state, opts = {}) {
         return async (step, input) => {
-            const mcp = parseQualifiedName(step.toolName ?? "");
+            const name = step.toolName ?? "";
+            const mcp = parseQualifiedName(name);
             if (!mcp) {
-                throw new Error(`${step.toolName} is not an MCP tool — it can only run in the session`);
+                throw new StepRunError(`${name || "this step"} is a built-in tool, which only runs in the session`, "not_run");
+            }
+            // `BIR_REPLAY_ALLOW_SERVERS` is about exactly this: a call bir makes by
+            // itself, with nobody approving it. A steered plan's divergence recovery
+            // reaches here too, for steps that were only ever to be steered in the
+            // session — where the user's own permission rules apply.
+            const allow = this.opts.allowServers;
+            if (!opts.adHoc && allow && !allow.has(mcp.serverName)) {
+                throw new StepRunError(`${mcp.serverName} is not on BIR_REPLAY_ALLOW_SERVERS, so bir does not call it unattended`, "not_run");
+            }
+            const left = opts.deadline !== undefined ? opts.deadline - Date.now() : Number.POSITIVE_INFINITY;
+            const timeoutMs = Math.max(MIN_STEP_MS, Math.min(this.budgets.stepMs, left));
+            let result;
+            try {
+                result = await this.work.call(mcp.serverName, mcp.toolName, input, timeoutMs, {
+                    sessionId: state.sessionId,
+                });
+            }
+            catch (err) {
+                throw classifyWorkError(err, mcp.serverName);
+            }
+            // A proxy that answers the work with no result at all took it and lost
+            // it (tool-error.ts, `isNoResult`): sent, and may or may not have run.
+            // Threaded as `null`, it would read as a success.
+            if (result === undefined || result === null) {
+                throw new StepRunError(`the ${mcp.serverName} proxy answered with no result — the call may or may not have run`, "uncertain");
             }
-            const result = await this.work.call(mcp.serverName, mcp.toolName, input, this.budgets.stepMs, { sessionId: state.sessionId });
             // Serialize exactly as the proxy records it, or `toolOutputLogic` — which
             // was authored against that shape — silently derives nothing (§7.2).
             return serializeCapped(redact(result));
         };
     }
+    /** Where recorded outputs come from, when they may stand in at all. */
+    recordedSource(state, force = false) {
+        if (!force && !this.recordedFallback)
+            return undefined;
+        const source = state.sourceRun;
+        return source ? (entry) => source.outputFor(entry) : undefined;
+    }
+    /**
+     * Wait for a plan's parameters within `budgetMs`, then judge whether the plan
+     * may run on them. Never throws.
+     *
+     * Out of time, the parameters settle without the derivation
+     * (`useFallbackParams`: settings at their samples, targets null) — never on
+     * `{}` — and the plan runs only if it needs no target it was not given. A
+     * `paramsLogic` that throws, or a value too dangerous to template into a
+     * command (safety.ts), stops it. `adHoc` keeps `bir replay`'s contract: the
+     * operator named the scenario, so neither judgement applies.
+     */
+    async readyFor(state, plan, budgetMs, opts = {}) {
+        const logicFailed = (err) => ({
+            ok: false,
+            error: `the scenario's parameter logic failed: ${errText(err)}`,
+            stage: "params_logic",
+            // The scenario's own logic is broken: the step it stopped in front of
+            // carries the verdict, so the recording page says why it never runs.
+            blame: true,
+        });
+        if (!plan.parametersSettled) {
+            let failure;
+            const settled = plan.ready().then(() => true, (err) => {
+                failure = err;
+                return true;
+            });
+            const waited = await this.waitDerivation(state, settled, budgetMs);
+            if (failure !== undefined)
+                return logicFailed(failure);
+            if (waited === undefined) {
+                logLine("replay.derive_timeout", {
+                    scenario: state.scenarioId ?? undefined,
+                    waitedMs: budgetMs,
+                    why: opts.adHoc
+                        ? "bir replay — every parameter takes its recorded sample"
+                        : "settings take their recorded samples, targets stay unnamed — the plan runs only if it needs none",
+                });
+                try {
+                    plan.useFallbackParams();
+                }
+                catch (err) {
+                    return logicFailed(err);
+                }
+                if (!opts.adHoc) {
+                    const schema = plan.paramsSchema;
+                    const planned = plan.allEntries().slice(0, plan.stepCount);
+                    const blocked = blockingTargets(targetKeys(schema), schema, planned, plan.paramsLogic);
+                    if (blocked.length > 0) {
+                        return {
+                            ok: false,
+                            error: `the value of ${blocked[0]} could not be read from this request in time`,
+                            stage: "derive_params",
+                            blame: false,
+                        };
+                    }
+                }
+            }
+        }
+        const sink = opts.adHoc ? undefined : sinkOfPlan(plan.allEntries().slice(0, plan.stepCount));
+        if (sink) {
+            const bad = unsafeParameter(plan.derivedValues, plan.paramsSchema, sink);
+            if (bad) {
+                logLine("replay.unsafe_param", {
+                    scenario: state.scenarioId ?? undefined,
+                    param: bad.key,
+                    sink,
+                    why: "a value read for this request would be templated into a command unattended — the agent does the task instead",
+                });
+                return {
+                    ok: false,
+                    error: `the value read for ${bad.key} contains characters that are not safe to put into a command unattended`,
+                    stage: "derive_params",
+                    blame: false,
+                };
+            }
+        }
+        return { ok: true };
+    }
+    /**
+     * Wait for something the derivation decides, within `budgetMs`. Resolves
+     * undefined when the time ran out.
+     *
+     * When the service is the one deriving, this is a service wait on a hot path
+     * (C1): it does not wait at all while the service is cooling down, and an
+     * overrun is reported to the breaker so the next hook does not wait either.
+     * Even a zero wait lets an answer that has already arrived through.
+     */
+    async waitDerivation(state, pending, budgetMs) {
+        const onService = state.deriveOnService === true;
+        const budget = onService && !serviceHealth.canWait() ? 0 : budgetMs;
+        let timer;
+        const late = Symbol("late");
+        try {
+            const winner = await Promise.race([
+                pending,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(late), Math.max(0, budget));
+                    timer.unref?.();
+                }),
+            ]);
+            if (winner !== late)
+                return winner;
+            if (onService && budget > 0)
+                serviceHealth.slow("derive");
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     /**
      * Where a pinned step's output will arrive from — the proxy's report, or the
      * hook's `tool_response` (§7.2).
@@ -1307,7 +2308,7 @@ export class ReplayController {
             logLine("replay.step_skipped", {
                 n: info.step.stepIndex,
                 tool: info.step.toolName,
-                why: "its tool could not run here and it has no recorded output",
+                why: "its call produced no result here — the plan stops at it",
                 error: info.error,
             });
             return;
@@ -1353,17 +2354,8 @@ export class ReplayController {
         }
         state.retired = true;
         state.pinned.clear();
-    }
-    withBudget(p, ms, what) {
-        let timer;
-        const budget = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`${what} exceeded ${ms}ms`)), ms);
-            timer.unref?.();
-        });
-        return Promise.race([p, budget]).finally(() => {
-            if (timer)
-                clearTimeout(timer);
-        });
+        // A call waiting for a pin to thread has nothing left to wait for.
+        this.notifyPins(state);
     }
 }
 /** Every target of a schema. A parameter with no kind is one (R-PARAM-3). */
@@ -1372,6 +2364,88 @@ function targetKeys(schema) {
         return [];
     return Object.keys(schema).filter((k) => schema[k]?.kind !== "setting");
 }
+/** A positive number from the environment, or undefined. */
+function positiveEnv(name) {
+    const n = Number(process.env[name]);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/**
+ * What a rejected dispatch means for the step (plan.ts, `StepRejection`).
+ *
+ * Read from the message, because that is all the proxy sends back. Only the
+ * cases that are certain are named: nothing was sent (no proxy, no proxy that
+ * is this session's, the queue closed before any proxy took the work, the
+ * upstream already gone), or the upstream answered with a JSON-RPC error.
+ * Everything else — a timeout, an
+ * aborted wait, a connection that dropped mid-call, a shutdown while a proxy
+ * held the work (`QUEUE_CLOSED_IN_FLIGHT`), an error nobody recognises — was
+ * sent and may have done its work, and is said to be exactly that. Guessing
+ * "failed" or "not run" there is how a model is invited to run a write twice.
+ */
+function classifyWorkError(err, serverName) {
+    // Proxies are here, but none is this session's: not sent, and not the
+    // scenario's fault — recorded as not run, never as a failed step.
+    if (err instanceof NoSessionProxyError)
+        return new StepRunError(err.message, "not_run");
+    const message = errText(err);
+    if (message === NO_PROXY) {
+        return new StepRunError(`no ${serverName} proxy of this session is connected to bir (${NO_PROXY})`, "not_run");
+    }
+    if (message === QUEUE_CLOSED || /\bupstream is not available\b/i.test(message)) {
+        return new StepRunError(message, "not_run");
+    }
+    if (/^MCP error -?\d+/i.test(message))
+        return new StepRunError(message, "failed");
+    return new StepRunError(message, "uncertain");
+}
+/**
+ * What the proxy says of a call its upstream was already gone for: it was
+ * never sent (relay.ts, `upstream unavailable`; executor.ts's wording too).
+ */
+const NOT_SENT_TEXT = /\bupstream (?:is not |un)available\b/i;
+/**
+ * What a host or a proxy says of a call that was sent and not seen through: a
+ * timeout, an interrupt, a cancellation, a dropped connection. Its work may
+ * have happened — the upstream does not stop because the waiting did.
+ */
+const UNCERTAIN_TEXT = /\b(?:timed? ?out|timeout|interrupted|cancell?ed|aborted|disconnected|connection (?:closed|reset|lost|dropped)|upstream (?:closed|restarted)|relay stopped|socket hang up|ECONNRESET|EPIPE)\b/i;
+/**
+ * How a pinned call ended when it did not simply work: the error to record
+ * and, when it is not an ordinary failure, the stop reason the note words it
+ * by (handover.ts). Undefined when neither the caller nor the output says
+ * anything went wrong — the output's own tool error is judged after.
+ *
+ *  - `how` from the caller wins.
+ *  - A proxy-threaded call with *no result* was abandoned by its proxy
+ *    (intercept.ts `onAbandoned`: `isError` and a reason, nothing else) — sent
+ *    and unanswered, so `uncertain`, unless the reason says it was never sent.
+ *  - A failure whose text is a timeout, an interrupt or a dropped connection
+ *    is `uncertain` too. Anything else is a failure: the tool answered one.
+ */
+function pinFailure(pin, output, failed, how) {
+    const noResult = pin.reach === "direct" && isNoResult(output);
+    const text = failed?.trim();
+    if (failed === undefined && !noResult && !how.uncertain && !how.notSent)
+        return undefined;
+    const reason = how.notSent
+        ? "not_run"
+        : how.uncertain
+            ? "uncertain"
+            : noResult
+                ? text && NOT_SENT_TEXT.test(text)
+                    ? "not_run"
+                    : "uncertain"
+                : text && UNCERTAIN_TEXT.test(text)
+                    ? "uncertain"
+                    : undefined;
+    const error = text ||
+        (reason === "not_run"
+            ? "the call was never sent — its server was not available"
+            : reason === "uncertain" || noResult
+                ? "the call produced no result — its server stopped answering mid-call"
+                : "the tool reported an error");
+    return { error, reason };
+}
 /**
  * The index a hand-over reports, in the *caller's* chain (R-CALL-32).
  *