@basein/runner 0.2.12 → 0.3.0

package/dist/replay/plan.js

@@ -20,10 +20,174 @@
  *      step to know its reach, so it can choose between the proxy, a recorded
  *      output, and skipping.
  */
-import { evalParamMapLogic, evalParamsLogic, evalResponseParamsLogic, evalResultMapLogic, evalToolInputLogic, evalToolOutputLogic, } from "./logic.js";
+import { evalParamMapLogic, evalParamsLogic, evalResponseParamsLogic, evalResultMapLogic, evalToolInputLogic, evalToolOutputLogic, LogicTimeoutError, } from "./logic.js";
 import { flatEntriesOf } from "./flatten.js";
 import { assembleBundle, bundleInput, MAX_REPLAY_REASON } from "./bundle.js";
+import { redact, redactText } from "../record/redact.js";
+import { sinkOfPlan, unsafeParameter } from "./safety.js";
+import { errText } from "../util/log.js";
+import { awaitWithin } from "../util/service-health.js";
 import { isMissingToolError, toolResultError } from "./tool-error.js";
+/** A rejection from an {@link ExecuteStep} that says what happened to the call. */
+export class StepRunError extends Error {
+    rejection;
+    constructor(message, rejection) {
+        super(message);
+        this.name = "StepRunError";
+        this.rejection = rejection;
+    }
+}
+/** What a rejection means for the step — see {@link ExecuteStep}. */
+export function rejectionOf(err) {
+    return err instanceof StepRunError ? err.rejection : "not_run";
+}
+/** A step's reasoning, as a directive shows it: one line, this long at most. */
+const MAX_REASONING_CHARS = 120;
+/** Past this, the directive's step list drops the reasoning and names tools only. */
+const MAX_DIRECTIVE_STEPS_CHARS = 2_000;
+function clipReasoning(reasoning) {
+    const first = (reasoning ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
+    return first.length > MAX_REASONING_CHARS ? `${first.slice(0, MAX_REASONING_CHARS)}…` : first;
+}
+/** A step's computed arguments, as a steer directive shows them: this long at most. */
+const MAX_DIRECTIVE_ARGS_CHARS = 240;
+/**
+ * One step's input logic, evaluated only to show its arguments, runs no longer
+ * than this (nor than `logicTimeoutMs()`).
+ *
+ * The limit is wall-clock time (a `vm` timeout), so it must tolerate a busy
+ * machine: with ten CPU-bound processes on eight cores, a trivial
+ * `return { command: 'ls ' + parameters.x }` took up to ~170 ms, and a 50 ms
+ * limit stopped more than half of them — ending the preview, and every
+ * argument with it, whenever the machine was loaded. At 250 ms none was
+ * stopped. A body stopped at this limit really is slow, and ends the preview.
+ */
+export const PREVIEW_LOGIC_MS = 250;
+/**
+ * All of a directive's argument previews together: it is written inside the
+ * prompt hook, so this is the most the preview adds to it, a stopped body
+ * included — each body's limit is clipped to what is left of it. A caller with
+ * less time left passes less (`steeringDirective`'s `previewBudgetMs`).
+ */
+export const PREVIEW_BUDGET_MS = 500;
+/** Below this much of the preview budget left, no further body is started. */
+const MIN_PREVIEW_BODY_MS = 10;
+/** Tools whose whole call is a `command`: the directive shows that, not a JSON object. */
+const SHELL_TOOLS = new Set(["Bash", "PowerShell"]);
+/**
+ * `target`, reporting any read of it. A step whose input logic reads what
+ * earlier steps accumulated cannot have its arguments known before they run.
+ * Writes land on `target`, which is a copy.
+ */
+function watchReads(target, onRead) {
+    return new Proxy(target, {
+        get(t, key, receiver) {
+            onRead();
+            return Reflect.get(t, key, receiver);
+        },
+        has(t, key) {
+            onRead();
+            return Reflect.has(t, key);
+        },
+        ownKeys(t) {
+            onRead();
+            return Reflect.ownKeys(t);
+        },
+        getOwnPropertyDescriptor(t, key) {
+            onRead();
+            return Reflect.getOwnPropertyDescriptor(t, key);
+        },
+    });
+}
+/**
+ * Whether `value` holds `target` itself, anywhere a render would reach — a
+ * body that passes the accumulation on (`return { ctx: respParams }`) without
+ * reading it. Too deep or too wide to walk, the answer is yes: a preview that
+ * cannot tell shows nothing.
+ */
+function holds(value, target, depth = 0, seen = new Set()) {
+    if (value === target)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    if (depth >= MAX_HOLDS_DEPTH || seen.size >= MAX_HOLDS_NODES)
+        return true;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    for (const v of Object.values(value))
+        if (holds(v, target, depth + 1, seen))
+            return true;
+    return false;
+}
+const MAX_HOLDS_DEPTH = 8;
+const MAX_HOLDS_NODES = 1_000;
+/** A deep copy for a look-ahead evaluation, or undefined when the value cannot be copied. */
+function copyOf(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One step's computed arguments as a steer directive shows them, or undefined
+ * when there is nothing useful to show.
+ *
+ * Data, and shaped to read as data: a shell step's command, anything else as
+ * its JSON. A command is shown WHOLE — one line, within the limit — or not at
+ * all: the model is told to pass what it sees, and a call the pin does not
+ * take (a hook that failed open, a plan already retired, a step copied out of
+ * order) runs as the model wrote it — `cat > config.yaml <<'EOF'` cut from its
+ * body empties the file. (One line also keeps a heredoc from spilling the
+ * body of a script into the prompt.) Secrets are redacted before anything is
+ * laid out — a key the redactor knows (`password`, `token`) and a
+ * secret-shaped value alike. A
+ * value too long for the line is elided whole (`"body":…`) rather than cut: a
+ * cut path or URL copied into the call would name a different target, where
+ * an elided one leaves the model to write its own and the pin to supply it.
+ */
+function renderArguments(toolName, input) {
+    if (SHELL_TOOLS.has(toolName)) {
+        const raw = typeof input.command === "string" ? input.command.trim() : "";
+        if (!raw || /[\r\n]/.test(raw))
+            return undefined;
+        const shown = redactText(raw);
+        if (/[\r\n]/.test(shown) || shown.length > MAX_DIRECTIVE_ARGS_CHARS)
+            return undefined;
+        return `command: ${shown}`;
+    }
+    const clean = redact(input);
+    if (!clean || typeof clean !== "object" || Array.isArray(clean))
+        return undefined;
+    const parts = [];
+    let used = 2;
+    let shortened = false;
+    for (const [key, value] of Object.entries(clean)) {
+        let json;
+        try {
+            json = JSON.stringify(value);
+        }
+        catch {
+            json = undefined;
+        }
+        if (json === undefined)
+            continue;
+        const name = JSON.stringify(key);
+        const whole = `${name}:${redactText(json)}`;
+        const part = used + whole.length + 1 <= MAX_DIRECTIVE_ARGS_CHARS ? whole : `${name}:…`;
+        if (part !== whole)
+            shortened = true;
+        if (used + part.length + 1 > MAX_DIRECTIVE_ARGS_CHARS) {
+            shortened = true;
+            break;
+        }
+        parts.push(part);
+        used += part.length + 1;
+    }
+    return `arguments: {${parts.join(",")}}${shortened ? " (shortened)" : ""}`;
+}
 /**
  * The recorded values for the *settings* a mapping did not name (R-CALL-21).
  *
@@ -79,6 +243,11 @@ export class ScenarioReplayPlan {
     entries;
     paramsPromise;
     params = {};
+    /** The derivation's own answer, before `paramsLogic`. What safety.ts judges. */
+    derivedParams = {};
+    /** Set once the parameters are final — derived, or settled without the derivation. */
+    paramsSettled = false;
+    fallbackTargets;
     respParams;
     stepIndex = 0;
     readyPromise;
@@ -94,6 +263,7 @@ export class ScenarioReplayPlan {
         this.entries = opts.entries ?? flatEntriesOf(opts.scenario);
         this.mode = opts.mode;
         this.paramsPromise = opts.params;
+        this.fallbackTargets = opts.fallbackTargets ?? "null";
         this.respParams = { ...(opts.respParamsInit ?? {}) };
         // The caller's own frame accumulates into the plan's `respParams`, so
         // `accumulated`, `responseModel` and every depth-0 step see one object.
@@ -179,26 +349,77 @@ export class ScenarioReplayPlan {
     }
     /**
      * Await the derivation, then apply `paramsLogic` — once, however many callers
-     * race here. A rejected derivation resolves to `{}` rather than throwing: the
-     * caller decided long ago that a replay with fallback parameters beats no
-     * replay, and a throw here would abort a turn the user is waiting on.
+     * race here. A rejected derivation settles on the fallback values
+     * ({@link useFallbackParams}) rather than throwing.
+     *
+     * Rejects only when `paramsLogic` throws. That is real: the scenario's own
+     * logic is broken, and the caller must hand over rather than run steps on
+     * parameters nobody processed.
      */
     ready() {
+        if (this.paramsSettled)
+            return Promise.resolve();
         if (!this.readyPromise) {
             this.readyPromise = this.paramsPromise
-                .catch(() => ({}))
+                .then((derived) => derived, () => undefined)
                 .then((derived) => {
-                let params = { ...derived };
-                if (this.scenario.paramsLogic) {
-                    // A throw here is real: the scenario's own logic is broken, and the
-                    // caller must abort rather than run steps with unprocessed params.
-                    params = evalParamsLogic(this.scenario.paramsLogic, params, this.intent);
-                }
-                this.params = params;
+                // Settled already, without the derivation: a late answer must not
+                // change the parameters under steps that ran on the others.
+                if (this.paramsSettled)
+                    return;
+                this.settleParams(derived ?? this.fallbackValues());
             });
         }
         return this.readyPromise;
     }
+    /**
+     * Settle the parameters without waiting any longer for the derivation: every
+     * *setting* at its recorded sample, every *target* `null` (R-PARAM-3), then
+     * `paramsLogic`. What the caller does when the derivation's budget runs out.
+     *
+     * Never `{}`. Running on an empty object put `undefined` into every argument
+     * — `{"command":"query undefined"}` — and a steered step was auto-approved
+     * with it. A target stays null here exactly as it does when the derivation
+     * answers without one, and the caller decides whether the plan can run
+     * without it (targets.ts).
+     *
+     * A derivation that answers later is ignored. Throws what `paramsLogic`
+     * throws.
+     */
+    useFallbackParams() {
+        if (this.paramsSettled)
+            return;
+        this.settleParams(this.fallbackValues());
+    }
+    /** Whether the parameters are final. */
+    get parametersSettled() {
+        return this.paramsSettled;
+    }
+    /** The derivation's own values, before `paramsLogic`. Empty until settled. */
+    get derivedValues() {
+        return this.derivedParams;
+    }
+    fallbackValues() {
+        const out = {};
+        const schema = this.scenario.paramsObject;
+        if (!schema || typeof schema !== "object")
+            return out;
+        for (const [key, p] of Object.entries(schema)) {
+            out[key] =
+                p?.kind === "setting" || this.fallbackTargets === "samples" ? p?.sampleValue : null;
+        }
+        return out;
+    }
+    settleParams(derived) {
+        const own = { ...derived };
+        let params = { ...derived };
+        if (this.scenario.paramsLogic) {
+            params = evalParamsLogic(this.scenario.paramsLogic, params, this.intent);
+        }
+        this.derivedParams = own;
+        this.params = params;
+        this.paramsSettled = true;
+    }
     /** 0-based index of the step awaiting execution (== completed step count). */
     get currentStepIndex() {
         return this.stepIndex;
@@ -243,6 +464,14 @@ export class ScenarioReplayPlan {
     get accumulated() {
         return this.respParams;
     }
+    /** The scenario's parameter schema — what the target and safety checks judge. */
+    get paramsSchema() {
+        return this.scenario.paramsObject ?? null;
+    }
+    /** The scenario's `paramsLogic`, which targets.ts reads as a consumer. */
+    get paramsLogic() {
+        return this.scenario.paramsLogic ?? null;
+    }
     /** The step awaiting execution, or undefined when the plan is done. */
     currentStep() {
         return this.currentEntry()?.step;
@@ -317,6 +546,81 @@ export class ScenarioReplayPlan {
             return { ...this.respParams };
         return evalResponseParamsLogic(this.scenario.responseParamsLogic, this.respParams, this.params, this.intent);
     }
+    /**
+     * The arguments each planned step will run with, where they are known before
+     * any step runs — for the steer directive (see {@link steeringDirective}).
+     *
+     * Known means: the parameters are settled, the step is the caller's own
+     * (a called segment's parameters are only built when it is entered), and
+     * its input logic neither reads nor passes on anything an earlier step
+     * accumulates — or it is the step at the cursor, whose accumulation is
+     * already final. Everything else is undefined, and the directive leaves
+     * those steps' arguments to the system.
+     *
+     * A look-ahead only: every body runs on copies, under a short limit, and a
+     * body that throws or runs long just leaves its step without arguments —
+     * the pin, not this, is what runs the step. The whole preview takes no more
+     * than `budgetMs` ({@link PREVIEW_BUDGET_MS}), a stopped body included; each
+     * body gets at most `bodyMs` ({@link PREVIEW_LOGIC_MS}) of it.
+     */
+    previewArguments(planned, budgetMs = PREVIEW_BUDGET_MS, bodyMs = PREVIEW_LOGIC_MS) {
+        const out = planned.map(() => undefined);
+        if (this.mode !== "steer" || !this.paramsSettled)
+            return out;
+        // NaN, a negative or a sliver: no preview, and the directive's old wording.
+        if (!(budgetMs >= MIN_PREVIEW_BODY_MS) || !(bodyMs >= 1))
+            return out;
+        const deadline = Date.now() + budgetMs;
+        // A value the pin would refuse to template into a command is never shown
+        // in one either: the model could run what the plan would not.
+        const sink = sinkOfPlan(planned);
+        if (sink && unsafeParameter(this.derivedParams, this.scenario.paramsObject, sink))
+            return out;
+        for (let i = this.stepIndex; i < planned.length; i += 1) {
+            const left = deadline - Date.now();
+            if (left < MIN_PREVIEW_BODY_MS)
+                break;
+            const entry = planned[i];
+            if (entry.depth !== 0)
+                continue;
+            const params = copyOf(this.params);
+            const accumulated = copyOf(this.respParams);
+            if (!params || !accumulated)
+                break;
+            let readsEarlier = false;
+            const resp = i === this.stepIndex
+                ? accumulated
+                : watchReads(accumulated, () => {
+                    readsEarlier = true;
+                });
+            let input;
+            try {
+                input = evalToolInputLogic(entry.step.toolInputLogic ?? "return {};", params, entry.frame.intent, resp, { timeoutMs: Math.min(bodyMs, left) });
+            }
+            catch (err) {
+                // A body that throws (often on an earlier result it does not have
+                // yet) only leaves its own step bare. One that had to be stopped
+                // either ran long — this scenario's logic is not worth running ahead —
+                // or used up what was left of the budget: either way no more of it is.
+                if (err instanceof LogicTimeoutError)
+                    break;
+                continue;
+            }
+            // Reading the accumulation, or passing it on whole (`{ ctx: respParams }`,
+            // which reads nothing yet runs with every earlier result): not known yet.
+            // Checked before rendering, which would walk into the watched copy.
+            try {
+                if (readsEarlier || (resp !== accumulated && holds(input, resp)))
+                    continue;
+                out[i] = renderArguments(entry.step.toolName ?? "", input);
+            }
+            catch {
+                // A value that throws when read (a getter the body returned): nothing
+                // to show for this step, and never a directive that fails to render.
+            }
+        }
+        return out;
+    }
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *
@@ -324,6 +628,20 @@ export class ScenarioReplayPlan {
      * whole sequence server-side. In `steer` mode it names the sequence so the
      * model initiates the expected calls — the arguments are supplied by the
      * system, so the model need not compute them.
+     *
+     * WHY A STEER DIRECTIVE SHOWS ARGUMENTS. The pin replaces the model's
+     * arguments with the step's only when the call is plausibly the step
+     * (control/pin-guard.ts): the same command head, the same file, an argument
+     * in common. Told merely that "the system supplies the arguments", a model
+     * writes a placeholder call — `ls`, `{"query":"..."}` — that the guard rightly
+     * declines, and the plan retires having run nothing. So where a step's
+     * arguments are already known they are shown under it, as data, so that the
+     * call the model writes, and the user sees, is the call that runs.
+     *
+     * `previewBudgetMs` / `previewBodyMs` bound that preview (default
+     * {@link PREVIEW_BUDGET_MS} / {@link PREVIEW_LOGIC_MS}): a caller with less
+     * of its hook's time left passes less, and under
+     * {@link MIN_PREVIEW_BODY_MS} there is no preview at all.
      */
     steeringDirective(directToolName = "mcp__bir__run_scenario", opts) {
         // A sub-task plan (segmented.md R-OUT-13) never tells the agent to stop
@@ -332,10 +650,39 @@ export class ScenarioReplayPlan {
         // The intent is a paragraph the analyser wrote; it is context, not an
         // instruction, so it is clipped rather than dumped whole into the prompt.
         const intent = this.intent.length > 240 ? `${this.intent.slice(0, 240)}…` : this.intent;
-        const lines = this.entries.slice(0, this.stopAt).map((e, i) => {
-            const why = e.step.reasoning ? ` — ${e.step.reasoning}` : "";
-            return `  ${i + 1}. ${e.step.toolName ?? ""}${why}`;
+        // Each step's reasoning is another session's narration ("I'll now drop the
+        // temp table…"), injected into this one. It is a label here, not a
+        // paragraph: its first line, clipped. A chain long enough that even the
+        // labels would run to kilobytes lists its tools alone — every tool always,
+        // because in steer mode the list *is* the instruction.
+        const planned = this.entries.slice(0, this.stopAt);
+        const args = this.previewArguments(planned, opts?.previewBudgetMs, opts?.previewBodyMs);
+        const listing = (withWhy, argsBefore) => planned.map((e, i) => {
+            const why = withWhy ? clipReasoning(e.step.reasoning) : "";
+            const head = `  ${i + 1}. ${e.step.toolName ?? ""}${why ? ` — ${why}` : ""}`;
+            const shown = i < argsBefore ? args[i] : undefined;
+            return shown ? `${head}\n     ${shown}` : head;
         });
+        const fits = (ls) => ls.join("\n").length <= MAX_DIRECTIVE_STEPS_CHARS;
+        // Within the same limit as ever, in order of use to the pin: every step's
+        // arguments, then the earliest steps' (the first call is the one a plan
+        // most often dies on), then labels, then bare names.
+        const lastArgs = args.reduce((n, a, i) => (a ? i + 1 : n), 0);
+        const candidates = [[true, lastArgs], [false, lastArgs]];
+        for (let k = lastArgs - 1; k > 0; k -= 1)
+            candidates.push([false, k]);
+        candidates.push([true, 0]);
+        let lines = listing(false, 0);
+        let argsShown = 0;
+        for (const [withWhy, before] of candidates) {
+            const ls = listing(withWhy, before);
+            if (!fits(ls))
+                continue;
+            lines = ls;
+            argsShown = before;
+            break;
+        }
+        const anyArgs = args.slice(0, argsShown).some((a) => a !== undefined);
         // A parked step (fallbk.md D3): the model is told up front that the plan is
         // partial, so the hand-over that follows is expected rather than a surprise.
         const tail = this.stopsEarly()
@@ -370,15 +717,20 @@ export class ScenarioReplayPlan {
             ...lines,
             ...(intent ? ["", `Context: ${intent}`] : []),
             "",
-            "The system supplies the exact arguments for each call — you do not need to",
+            ...(anyArgs
+                ? [
+                    "The system supplies the exact arguments for each call. Where a step shows",
+                    "its arguments above, they are the ones it runs with: pass them as shown.",
+                ]
+                : ["The system supplies the exact arguments for each call — you do not need to"]),
             ...(subTask
                 ? [
-                    "compute them. Do not call any other tools until this sequence is complete.",
+                    `${anyArgs ? "" : "compute them. "}Do not call any other tools until this sequence is complete.`,
                     "These steps are part of your task: when they are done, continue your task,",
                     "calling tools as needed.",
                 ]
                 : [
-                    "compute them. Do not call any other tools until this sequence is complete,",
+                    `${anyArgs ? "" : "compute them. "}Do not call any other tools until this sequence is complete,`,
                     "then answer the user's request from the tool results.",
                 ]),
             ...tail,
@@ -391,19 +743,20 @@ export class ScenarioReplayPlan {
      * live session already ran — with side effects — every step before the one it
      * diverged on, so re-running them would be wrong.
      *
-     * There is no try/catch around the input or output logic: a throw there
-     * propagates out, and the caller abandons the whole bundle rather than
-     * shipping a half-computed one. The tool call itself is the exception — a
-     * rejection means the step could not be run *here*, and then a recorded output
-     * is not a shortcut past a real result, it is the only result that exists.
-     * Skipping instead would drop the step *and* stop threading `respParams`, so
-     * every later step reading from it fails too.
+     * A step whose call produced no result ends the bundle there
+     * ({@link DriveOptions}): later steps would compute on a result that does not
+     * exist, and nothing may be shown in its place. The stop is returned, and the
+     * bundle says the task is not finished. With `stopOnFailure` a logic throw or
+     * a tool error ends it the same way; without it they keep their old contract
+     * (a throw propagates, an error is threaded and counted).
+     *
+     * `deadline` bounds the whole bundle: this runs inside a `PreToolUse` hook
+     * with a timeout of its own, and a step started after the host stopped
+     * waiting is a side effect nobody is told about.
      */
     async composeBundle(maxChars, execute, recordedOutputFor, onStep, opts = {}) {
-        // A local copy: composing must not corrupt the live plan's accumulation if
-        // the caller decides to keep steering afterwards.
-        // One copy per frame, for the same reason the plan copied its own: composing
-        // must not corrupt the live accumulation if the caller keeps steering.
+        // One copy per frame: composing must not corrupt the live plan's
+        // accumulation if the caller decides to keep steering afterwards.
         const resp = new Map();
         if (this.entries[0])
             resp.set(this.rootFrame().id, { ...this.respParams });
@@ -412,61 +765,102 @@ export class ScenarioReplayPlan {
         let recordedCount = 0;
         let skipped = 0;
         let errored = 0;
-        for (const entry of this.entries.slice(this.stepIndex, this.stopAt)) {
+        let stopped;
+        const stopOnFailure = opts.stopOnFailure === true;
+        for (let flatIndex = this.stepIndex; flatIndex < this.stopAt; flatIndex += 1) {
+            const entry = this.entries[flatIndex];
             const step = entry.step;
+            const before = this.stopBefore(entry, flatIndex, opts.signal, opts.deadline);
+            if (before) {
+                stopped = before;
+                break;
+            }
             const startedAt = Date.now();
-            const computed = reportingStage(onStep, entry, "tool_input_logic", {}, startedAt, () => {
-                this.enterFrame(entry, resp);
-                const respParams = resp.get(entry.frame.id) ?? {};
-                return evalToolInputLogic(step.toolInputLogic ?? "return {};", this.paramsFor(entry), entry.frame.intent, respParams);
-            });
-            let response;
-            let recorded = false;
+            let computed;
             try {
-                response = await execute(step, computed);
-                executed += 1;
+                computed = reportingStage(onStep, entry, "tool_input_logic", {}, startedAt, () => {
+                    this.enterFrame(entry, resp);
+                    const respParams = resp.get(entry.frame.id) ?? {};
+                    return evalToolInputLogic(step.toolInputLogic ?? "return {};", this.paramsFor(entry), entry.frame.intent, respParams);
+                });
             }
             catch (err) {
-                const error = err instanceof Error ? err.message : String(err);
-                const fallback = (typeof step.recordedOutput === "string" && step.recordedOutput.length > 0
-                    ? step.recordedOutput
-                    : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
-                if (!fallback) {
-                    skipped += 1;
+                if (!stopOnFailure)
+                    throw err;
+                stopped = {
+                    kind: "step_failed",
+                    stepIndex: step.stepIndex,
+                    flatIndex,
+                    stage: "tool_input_logic",
+                    error: errText(err),
+                };
+                break;
+            }
+            const call = await this.callStep(entry, flatIndex, computed, startedAt, execute, recordedOutputFor, onStep, opts, opts.deadline);
+            if (call.stopped) {
+                skipped += 1;
+                stopped = call.stopped;
+                break;
+            }
+            const { response, recorded } = call;
+            if (recorded)
+                recordedCount += 1;
+            else
+                executed += 1;
+            if (stopOnFailure && !recorded) {
+                // Judged before the output logic, which was written against a success
+                // and would only throw a second, less useful error on this one.
+                const toolError = toolResultError(response);
+                if (toolError) {
+                    errored += 1;
                     onStep?.({
                         step,
                         entry,
                         input: computed,
-                        outcome: "skipped",
-                        error,
-                        toolMissing: isMissingToolError(error) || undefined,
+                        outcome: "failed",
+                        stage: "tool_call",
+                        error: toolError,
+                        toolMissing: isMissingToolError(toolError) || undefined,
                         ms: Date.now() - startedAt,
                     });
-                    continue;
+                    entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
+                    stopped = {
+                        kind: "step_failed",
+                        stepIndex: step.stepIndex,
+                        flatIndex,
+                        stage: "tool_call",
+                        error: toolError,
+                    };
+                    break;
                 }
-                response = fallback;
-                recorded = true;
-                recordedCount += 1;
-                onStep?.({
-                    step,
-                    entry,
-                    input: computed,
-                    outcome: "recorded",
-                    error,
-                    toolMissing: isMissingToolError(error) || undefined,
-                    ms: Date.now() - startedAt,
-                });
             }
             // Thread the output for later steps' inputs. A recorded output threads
-            // too: `toolOutputLogic` was authored against exactly this shape, and a
-            // stale value beats a missing one downstream.
+            // too: `toolOutputLogic` was authored against exactly this shape.
             let derivedKeys = [];
-            if (step.toolOutputLogic) {
-                const derived = reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => evalToolOutputLogic(step.toolOutputLogic, response, this.paramsFor(entry), entry.frame.intent, resp.get(entry.frame.id) ?? {}));
-                derivedKeys = Object.keys(derived);
-                Object.assign(resp.get(entry.frame.id) ?? {}, derived);
+            try {
+                reportingStage(onStep, entry, "tool_output_logic", computed, startedAt, () => {
+                    if (step.toolOutputLogic) {
+                        const derived = evalToolOutputLogic(step.toolOutputLogic, response, this.paramsFor(entry), entry.frame.intent, resp.get(entry.frame.id) ?? {});
+                        derivedKeys = Object.keys(derived);
+                        Object.assign(resp.get(entry.frame.id) ?? {}, derived);
+                    }
+                    this.leaveFrame(entry, resp);
+                });
+            }
+            catch (err) {
+                if (!stopOnFailure)
+                    throw err;
+                // The tool ran; its output is real and belongs in front of the model.
+                entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
+                stopped = {
+                    kind: "step_failed",
+                    stepIndex: step.stepIndex,
+                    flatIndex,
+                    stage: "tool_output_logic",
+                    error: errText(err),
+                };
+                break;
             }
-            this.leaveFrame(entry, resp);
             if (!recorded) {
                 // A step's verdict is its output, not its resolution: a tool that ran
                 // and answered "Error: …" resolves like any other, and a chain of eight
@@ -486,22 +880,20 @@ export class ScenarioReplayPlan {
                     ms: Date.now() - startedAt,
                 });
             }
-            entries.push({
-                toolName: step.toolName ?? "",
-                input: bundleInput(computed),
-                response,
-                recorded,
-            });
+            entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
         }
         return {
             text: assembleBundle(entries, maxChars, {
-                handover: opts.handover,
+                // A bundle that stops short of the task — in front of a parked step, or
+                // at a step that broke — must never say "the work is done".
+                handover: opts.handover === true || stopped !== undefined,
                 subTask: this.subTask,
             }),
             executed,
             recorded: recordedCount,
             skipped,
             errored,
+            stopped,
         };
     }
     /**
@@ -510,8 +902,12 @@ export class ScenarioReplayPlan {
      * This is `direct` mode's driver, and unlike {@link composeBundle} it mutates
      * the plan — the steps really did run, so the cursor and `respParams` must say
      * so, which is what lets the outcome be `steered_full` and `stepsPinned` be
-     * truthful. A step that cannot run at all still advances the cursor: the plan
-     * is spent either way, and stalling it would leave a retired turn looking live.
+     * truthful.
+     *
+     * A step whose call produced no result stops the run there, with the cursor
+     * on it ({@link DriveOptions}). So does the deadline, checked before each
+     * step, and the caller's `signal`. A step already sent is never abandoned:
+     * its result arrives (or its own timeout does) and is reported as it is.
      *
      * `maxChars` caps the bundle exactly as a divergence bundle is capped. The
      * direct path once passed `Number.MAX_SAFE_INTEGER` here — fine at 10 KB, and
@@ -525,19 +921,24 @@ export class ScenarioReplayPlan {
         let skipped = 0;
         let errored = 0;
         let partial = false;
+        let aborted = false;
         let stopped;
         const stopOnFailure = opts.stopOnFailure === true;
-        const errText = (err) => (err instanceof Error ? err.message : String(err));
         while (!this.isDone()) {
-            if (deadline !== undefined && Date.now() >= deadline) {
-                partial = true;
-                break;
-            }
             const entry = this.entries[this.stepIndex];
             const step = entry.step;
             // Where this step sits in the flat list — what a stop reports. Taken now,
             // because the cursor has moved on by the time some stops are written.
             const flatIndex = this.stepIndex;
+            const before = this.stopBefore(entry, flatIndex, opts.signal, deadline);
+            if (before) {
+                stopped = before;
+                if (before.reason === "budget")
+                    partial = true;
+                else
+                    aborted = true;
+                break;
+            }
             const startedAt = Date.now();
             let computed;
             try {
@@ -555,48 +956,17 @@ export class ScenarioReplayPlan {
                 };
                 break;
             }
-            let response;
-            let recorded = false;
-            try {
-                response = await execute(step, computed);
-                executed += 1;
+            const call = await this.callStep(entry, flatIndex, computed, startedAt, execute, recordedOutputFor, onStep, opts, deadline);
+            if (call.stopped) {
+                skipped += 1;
+                stopped = call.stopped;
+                break;
             }
-            catch (err) {
-                const error = err instanceof Error ? err.message : String(err);
-                const fallback = (typeof step.recordedOutput === "string" && step.recordedOutput.length > 0
-                    ? step.recordedOutput
-                    : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
-                if (!fallback) {
-                    skipped += 1;
-                    onStep?.({
-                        step,
-                        entry,
-                        input: computed,
-                        outcome: "skipped",
-                        error,
-                        toolMissing: isMissingToolError(error) || undefined,
-                        ms: Date.now() - startedAt,
-                    });
-                    // Advance past a step that cannot run, without threading anything.
-                    // The frame is still left behind it: a sub-task whose last step could
-                    // not run here still hands back whatever its earlier steps emitted.
-                    this.leaveFrame(entry);
-                    this.stepIndex += 1;
-                    continue;
-                }
-                response = fallback;
-                recorded = true;
+            const { response, recorded } = call;
+            if (recorded)
                 recordedCount += 1;
-                onStep?.({
-                    step,
-                    entry,
-                    input: computed,
-                    outcome: "recorded",
-                    error,
-                    toolMissing: isMissingToolError(error) || undefined,
-                    ms: Date.now() - startedAt,
-                });
-            }
+            else
+                executed += 1;
             if (stopOnFailure && !recorded) {
                 // Judged before the output logic, which was written against a success
                 // and would only throw a second, less useful error on this one.
@@ -613,12 +983,7 @@ export class ScenarioReplayPlan {
                         toolMissing: isMissingToolError(toolError) || undefined,
                         ms: Date.now() - startedAt,
                     });
-                    entries.push({
-                        toolName: step.toolName ?? "",
-                        input: bundleInput(computed),
-                        response,
-                        recorded,
-                    });
+                    entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
                     this.stepIndex += 1;
                     stopped = {
                         kind: "step_failed",
@@ -638,12 +1003,7 @@ export class ScenarioReplayPlan {
                 if (!stopOnFailure)
                     throw err;
                 // The tool ran; its output is real and belongs in front of the model.
-                entries.push({
-                    toolName: step.toolName ?? "",
-                    input: bundleInput(computed),
-                    response,
-                    recorded,
-                });
+                entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
                 stopped = {
                     kind: "step_failed",
                     stepIndex: step.stepIndex,
@@ -672,15 +1032,10 @@ export class ScenarioReplayPlan {
                     ms: Date.now() - startedAt,
                 });
             }
-            entries.push({
-                toolName: step.toolName ?? "",
-                input: bundleInput(computed),
-                response,
-                recorded,
-            });
+            entries.push({ toolName: step.toolName ?? "", input: bundleInput(computed), response, recorded });
         }
         // Every planned step ran and the plan ends in front of a parked one.
-        if (!stopped && !partial && this.stopsEarly() && this.isDone()) {
+        if (!stopped && this.stopsEarly() && this.isDone()) {
             // `known_bad_step` here means "in front of the plan's end": the
             // controller reads the served reason and names the kind (D8).
             stopped = {
@@ -700,7 +1055,92 @@ export class ScenarioReplayPlan {
             errored,
             partial,
             stopped,
+            aborted: aborted || undefined,
         };
     }
+    /**
+     * A reason not to *start* the next step: the caller is gone, or the time is
+     * up. Undefined means go ahead.
+     */
+    stopBefore(entry, flatIndex, signal, deadline) {
+        if (signal?.aborted) {
+            return { kind: "step_failed", stepIndex: entry.step.stepIndex, flatIndex, reason: "cancelled" };
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            return { kind: "step_failed", stepIndex: entry.step.stepIndex, flatIndex, reason: "budget" };
+        }
+        return undefined;
+    }
+    /**
+     * Call one step's tool. Resolves with its result, with the recorded output
+     * that may stand in for it (only under `recordedFallback`, only for a step
+     * that could not be sent), or with the stop a missing result means.
+     */
+    async callStep(entry, flatIndex, computed, startedAt, execute, recordedOutputFor, onStep, opts, 
+    /** The driver's deadline: a recorded-output lookup is not waited on past it. */
+    deadline) {
+        const step = entry.step;
+        try {
+            return { response: await execute(step, computed), recorded: false };
+        }
+        catch (err) {
+            const error = errText(err);
+            const reason = rejectionOf(err);
+            const standIn = opts.recordedFallback === true && reason === "not_run"
+                ? ((typeof step.recordedOutput === "string" && step.recordedOutput.length > 0
+                    ? step.recordedOutput
+                    : undefined) ?? (await this.recordedWithin(recordedOutputFor, entry, deadline)))
+                : undefined;
+            onStep?.({
+                step,
+                entry,
+                input: computed,
+                outcome: standIn !== undefined ? "recorded" : "skipped",
+                error,
+                toolMissing: isMissingToolError(error) || undefined,
+                ms: Date.now() - startedAt,
+            });
+            if (standIn !== undefined)
+                return { response: standIn, recorded: true };
+            return {
+                stopped: {
+                    kind: "step_failed",
+                    stepIndex: step.stepIndex,
+                    flatIndex,
+                    stage: "tool_call",
+                    error,
+                    reason,
+                },
+            };
+        }
+    }
+    /**
+     * A step's recorded output from the source run, waited on no longer than the
+     * driver's deadline.
+     *
+     * The lookup is a service fetch (source-run.ts) of up to its own timeout,
+     * and a divergence runs it inside a `PreToolUse` whose deadline the hook
+     * must keep (C1, C9): so it is a hot-path wait on the service, through the
+     * breaker, and a lookup that has not answered in time is no recorded output.
+     * A sliver of time left is not worth a request, nor a verdict on the service.
+     */
+    async recordedWithin(recordedOutputFor, entry, deadline) {
+        if (!recordedOutputFor)
+            return undefined;
+        if (deadline !== undefined && deadline - Date.now() < MIN_RECORDED_LOOKUP_MS)
+            return undefined;
+        let pending;
+        try {
+            pending = recordedOutputFor(entry);
+        }
+        catch {
+            return undefined;
+        }
+        if (deadline === undefined)
+            return pending.catch(() => undefined);
+        return awaitWithin(pending, Math.max(0, deadline - Date.now()), "source_run");
+    }
 }
+/** Below this much time left, a recorded-output lookup is not attempted. */
+const MIN_RECORDED_LOOKUP_MS = 250;
 //# sourceMappingURL=plan.js.map