@basein/runner 0.3.15 → 0.3.17

package/dist/replay/controller.js

@@ -14,12 +14,12 @@
 import { parseQualifiedName } from "../control/correlation.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
 import { REDACT_SCAN_MAX_CHARS, redact, redactJsonText, redactText } from "../record/redact.js";
-import { capText, REPORT_PAYLOAD_MAX_BYTES, serializeCapped } from "../record/truncate.js";
+import { capText, DEFAULT_MAX_PAYLOAD_BYTES, REPORT_PAYLOAD_MAX_BYTES, serializeCapped, } from "../record/truncate.js";
 import { logDetail, logLine, errText } from "../util/log.js";
 import { serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 import { bashCommandFor } from "./bash-channel.js";
 import { BuiltinNotRunnable, BuiltinTimeout, parseBashAllow, parseBuiltinTools, runBuiltin, } from "./builtins.js";
-import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, truncate } from "./bundle.js";
+import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, testWords, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, } from "./derive.js";
 import { buildHandoverNote, MAX_HANDOVER_NOTE, } from "./handover.js";
@@ -29,7 +29,7 @@ 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 { clampToFrameStart, flattenChain, frameEdges, } from "./flatten.js";
 import { blockingTargets } from "./targets.js";
 import { isNoResult, toolResultError } from "./tool-error.js";
 import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
@@ -171,6 +171,12 @@ const HOST_RACE_MS = 200;
 const MAX_STEP_RESULTS = 200;
 /** Per-step error budget. The console shows these inline, under the step. */
 const MAX_STEP_ERROR_CHARS = 500;
+/**
+ * All of one plan's kept calls together, in characters. A plan of a few dozen
+ * calls keeps them whole; past this the rest keep a report's cut, so one turn
+ * cannot hold more than a few megabytes in the recorder.
+ */
+const TURN_CALLS_MAX_CHARS = 8 * 1024 * 1024;
 export class ReplayController {
     enabled;
     work = new ProxyWorkQueue();
@@ -400,6 +406,13 @@ export class ReplayController {
         if (match.withheld === "runner_update_required") {
             return decline("the service hands this runner no plan until it is updated — run `bir update`", "runner_update_required");
         }
+        // Held (the service's autocorrect.md AC4): the agent redid this plan's
+        // task after its last run, and the service hands the plan out again only
+        // when its owner lets it go or uses a correction. Its own code, so the
+        // turn is not read as "not ready", whose fix — calculate — is wrong here.
+        if (match.withheld === "held") {
+            return decline("the service holds this plan: the agent did its task again after its last run", "held");
+        }
         // Gate 3 — a ready scenario with steps.
         const scenario = match.scenario;
         if (!match.scenarioId || !isReadyScenario(scenario)) {
@@ -460,6 +473,15 @@ export class ReplayController {
                     : "known_bad_first_step");
         }
         const planned = stopAt === undefined ? entries : entries.slice(0, stopAt);
+        // Another host's adapter steps through a plan call by call and knows no
+        // tests (AC5): asked for a step its test left out, it is refused, reads
+        // that as the plan's end, and the model's own calls after it are booked as
+        // a broken step — the step counts drift when two steps share a tool. Such
+        // a plan is declined for it here, before anything is spent, until the
+        // adapter reads `when`.
+        if (host && planned.some(underTest)) {
+            return decline(`the ${host.app} adapter cannot yet run a plan whose steps run only when a test says so`, "host_tests_unsupported");
+        }
         // Gate 6 — tool coverage, over the steps that will actually run. A
         // built-in on `BIR_BUILTIN_TOOLS` counts as reachable: the runner
         // executes it itself (replay/builtins.ts), so a chain that starts with a
@@ -611,6 +633,10 @@ export class ReplayController {
         }
         state.mode = mode;
         state.stepsPlanned = entries.length;
+        // The chain this plan was served at: what its own calls are marked with
+        // when they are recorded into a redo of the turn (AC2).
+        if (typeof scenario.chainRevision === "number")
+            state.chainRevision = scenario.chainRevision;
         // Why the plan stops, when a call is what stops it: the note names the
         // sub-task rather than a tool (R-CALL-36).
         state.flatStop =
@@ -647,6 +673,8 @@ export class ReplayController {
             stops: stopLines(entries),
             coverage: coverageOf(entries.map((e) => e.step), state.wrapped, allowServers, builtinTools).join(","),
             tools: entries.map((e) => e.step.toolName ?? "").join(","),
+            // Which steps run only under a test, by flat position (AC5).
+            tests: testLines(entries),
         });
         return state;
     }
@@ -963,6 +991,41 @@ export class ReplayController {
                 return this.concurrentCall(state, plan, toolName);
             }
         }
+        // The steps this request does not need are left out before the call is
+        // judged, and a test that says "the other half" stops the plan here
+        // (AC5). Only a steer plan's cursor moves with the model's calls.
+        if (state.mode === "steer") {
+            if (this.settleCursor(state, plan, "above") === "stopped") {
+                const note = this.takeNote(state);
+                return note ? this.deliverInstead(note, toolName, otherHost) : { kind: "abort" };
+            }
+            if (plan.isDone()) {
+                // What was left of the plan was not needed: it is complete, and this
+                // call is the model's own — unless a parked step is next, whose
+                // hand-over is told in place of this call.
+                this.finishSteer(state, plan);
+                const note = this.takeNote(state);
+                return note ? this.deliverInstead(note, toolName, otherHost) : { kind: "passthrough" };
+            }
+            // A call to a step that was just left out is told so in its place —
+            // even when the note already went out, which a model may not have read:
+            // read as a divergence, it would end the plan. Twice at most, so a model
+            // that means the call for itself is not refused for ever.
+            const skip = state.skipNote;
+            if (skip && toolName !== plan.expectedTool() && skip.tools.has(toolName) && (skip.refused ?? 0) < 2) {
+                skip.delivered = true;
+                skip.refused = (skip.refused ?? 0) + 1;
+                return this.deliverInstead(skip.text, toolName, otherHost);
+            }
+            // A call to the next step's tool: a note the model has read is done
+            // with. One it has not read yet waits for the pin guard (the control
+            // server's `pinTaken` / `skipNoteFor`): when the left-out step and the
+            // next one share a tool, the call may be the left-out one, made because
+            // the note was late — its arguments then fail the guard, and the note
+            // goes in its place rather than the call running as written.
+            if (skip && toolName === plan.expectedTool() && skip.delivered)
+                state.skipNote = undefined;
+        }
         // A direct plan does not steer individual calls: the model was asked for one
         // tool call and made a different one. That is divergence.
         const expected = plan.expectedTool();
@@ -1353,6 +1416,11 @@ export class ReplayController {
                 ms: Date.now() - pin.pinnedAt,
             });
         }
+        // With this output in, the next steps' tests can be decided: the ones this
+        // request does not need are left out, and one that says "the other half"
+        // hands over here, its note on this very PostToolUse (AC5).
+        if (this.settleCursor(state, plan, "above") === "stopped")
+            return false;
         const done = plan.isDone();
         logDetail("replay.thread", {
             n: pin.stepIndex,
@@ -1360,7 +1428,17 @@ export class ReplayController {
             emitted: derivedKeys.join(",") || undefined,
             done,
         });
-        if (done && plan.stopsEarly()) {
+        if (done)
+            this.finishSteer(state, plan);
+        return done;
+    }
+    /**
+     * A steer plan whose cursor reached its end: in front of a parked step (or a
+     * call the service could not answer), which hands over; otherwise it ran to
+     * its end — and from here every call is the model's own.
+     */
+    finishSteer(state, plan) {
+        if (plan.atStop()) {
             // Every planned step ran, and the next one is parked (fallbk.md D3) — or
             // is a call the service could not answer (segmented.md R-CALL-29).
             const parked = plan.stopStep();
@@ -1371,24 +1449,155 @@ export class ReplayController {
                 position: plan.stepCount,
                 delivery: "above",
             });
-            return true;
+            return;
         }
-        if (done) {
-            this.upgrade(state, "steered_full");
-            state.ranToEnd = true;
-            // A completing retire: the last step threaded and the plan's work is over
-            // (segmented.md R-MONEY-3). Everything the agent spends after this is the
-            // agent's own, not this plan's.
-            this.retire(state, undefined, true);
-            logLine("replay.done", {
-                scenario: state.scenarioId ?? undefined,
-                mode: state.mode,
-                steps: `${plan.stepCount}/${plan.stepCount}`,
-                outcome: state.outcome,
-                ms: Date.now() - state.armedAt,
+        this.upgrade(state, "steered_full");
+        state.ranToEnd = true;
+        // A completing retire: the last step threaded and the plan's work is over
+        // (segmented.md R-MONEY-3). Everything the agent spends after this is the
+        // agent's own, not this plan's.
+        this.retire(state, undefined, true);
+        // The steps that ran: a step its test left out is no step done (AC5).
+        const before = this.ranBefore(plan, plan.stepCount);
+        logLine("replay.done", {
+            scenario: state.scenarioId ?? undefined,
+            mode: state.mode,
+            steps: `${before.left.length > 0 ? before.ran.length : plan.stepCount}/${plan.stepCount}`,
+            notTaken: before.left.length || undefined,
+            outcome: state.outcome,
+            ms: Date.now() - state.armedAt,
+        });
+    }
+    /**
+     * Move a plan's own cursor past the steps this request does not need, and
+     * act on what its tests decide (the service's autocorrect.md AC5). Every
+     * verdict is recorded as it is made. `stopped` means the plan handed over —
+     * the other half, a test that could not answer, or no step needed at all —
+     * and its note waits in {@link takeNote}. Otherwise the steps left out are
+     * named in a note for the model ({@link takeSkipNote}), and the caller goes
+     * on: a step is due, or the plan is done.
+     *
+     * Nothing at all for a plan without tests, which behaves exactly as before.
+     */
+    settleCursor(state, plan, delivery) {
+        if (!plan.hasTests())
+            return "ready";
+        // Never throws: a sub-task whose results cannot go back after its last
+        // step was left out is a stop like any other (`result_map`).
+        const settled = plan.settleTests(this.observeStep(state));
+        // The recorded outputs of the steps left out are passed over, so a
+        // divergence's bundle later stands each step's own in (source-run.ts).
+        const source = state.sourceRun;
+        if (source) {
+            for (const l of settled.left) {
+                for (let i = l.flatIndex; i < l.until; i += 1) {
+                    const entry = plan.allEntries()[i];
+                    if (entry)
+                        source.leftOut(entry);
+                }
+            }
+        }
+        if (settled.stop) {
+            const stop = settled.stop;
+            const position = stop.flatIndex ?? plan.currentStepIndex;
+            this.handOver(state, {
+                kind: stop.kind,
+                step: plan.allSteps()[position],
+                entry: plan.allEntries()[position],
+                position,
+                error: stop.error,
+                delivery,
+                stopReason: stop.reason,
+                whenText: stop.whenText,
+                subTask: stop.subTask,
             });
+            return "stopped";
+        }
+        if (settled.left.length === 0)
+            return "ready";
+        if (plan.isDone() && !plan.atStop() && state.stepsPinned === 0) {
+            // Every step was left out: none of the plan's work is this request's,
+            // and the model does the task (AC5). Reported like any hand-over before
+            // a step ran.
+            this.handOver(state, {
+                kind: "other_branch",
+                step: plan.allSteps()[0],
+                entry: plan.allEntries()[0],
+                position: 0,
+                delivery,
+                noneNeeded: true,
+            });
+            return "stopped";
         }
-        return done;
+        state.skipNote = {
+            text: this.skipNoteText(state, plan, settled.left),
+            // Every tool of a sub-task left out whole, not its call's intent: a call
+            // the model makes to any of them is one to a step left out.
+            tools: new Set(settled.left.flatMap((l) => (l.tools.length > 0 ? l.tools : [l.toolName]))),
+            delivered: false,
+            complete: plan.isDone() && !plan.atStop(),
+        };
+        return "ready";
+    }
+    /** What the model is told about steps a test left out (AC5). */
+    skipNoteText(state, plan, left) {
+        const named = left.map((l) => `step ${l.flatIndex + 1} (${l.toolName})`);
+        const texts = [...new Set(left.map((l) => l.text).filter((t) => !!t))];
+        const why = texts.length === 1 ? ` — only for when ${texts[0]}` : "";
+        const what = left.length === 1 ? `Not needed for this request: ${named[0]}${why}.` : `Not needed for this request: ${named.join(", ")}${why}.`;
+        let next;
+        if (plan.isDone() && !plan.atStop()) {
+            next =
+                state.armedBy === "intent"
+                    ? "The sequence is complete: continue your task, calling tools as needed."
+                    : "The sequence is complete: answer the user's request from the tool results.";
+        }
+        else {
+            const entry = plan.currentEntry();
+            next = `Leave ${left.length === 1 ? "it" : "them"} out, and call step ${plan.currentStepIndex + 1}${entry?.step.toolName ? ` (${entry.step.toolName})` : ""} next.`;
+        }
+        return `[BaseInstRunner calculated replay] ${what} ${next}`;
+    }
+    /**
+     * The note naming the steps a test just left out, claimed for delivery on a
+     * `PostToolUse` (AC5). Returned once; undefined when there is none.
+     */
+    takeSkipNote(state) {
+        const skip = state?.skipNote;
+        if (!skip || skip.delivered)
+            return undefined;
+        skip.delivered = true;
+        return skip.text;
+    }
+    /**
+     * The same note, for a call the model is about to make to one of the steps
+     * it names — when the note has not reached the model yet. The control server
+     * gives it in place of that call, whether the plan is still steering or has
+     * just finished: a step left out must never run because the note was late.
+     */
+    skipNoteFor(state, toolName) {
+        const skip = state?.skipNote;
+        if (!skip || skip.delivered || !skip.tools.has(toolName))
+            return undefined;
+        skip.delivered = true;
+        return skip.text;
+    }
+    /**
+     * The pin guard took a call to the next step as that step: a note still
+     * waiting to say that a step before it was left out has nothing left to
+     * stop, and goes — as it went at the call before the guard existed.
+     */
+    pinTaken(state) {
+        if (state?.skipNote && !state.skipNote.complete)
+            state.skipNote = undefined;
+    }
+    /**
+     * The plan's own calls of the turn, whole, in the order it made them — for
+     * the turn's newest run when the agent redoes the task (AC2). Empty unless
+     * the control server asked for them to be kept ({@link ReplayState.keepCalls}).
+     */
+    turnCallsOf(state) {
+        return state?.turnCalls ? [...state.turnCalls.values()] : [];
     }
     /**
      * The result of a call pinned under a plan that has since handed over
@@ -1619,7 +1828,12 @@ export class ReplayController {
                 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",
+                // Not a sub-task's result mapping after its last step was left out
+                // (`result_map`): that step did not run (AC5).
+                ranThisStep: stop.stage === "tool_output_logic" && stop.reason !== "result_map",
+                // The other half (AC5): what the steps from here are for.
+                whenText: stop.whenText,
+                subTask: stop.subTask,
             });
             if (stop.reason === "cancelled") {
                 // The caller is gone and reads nothing. The note stays undelivered: a
@@ -1650,6 +1864,20 @@ export class ReplayController {
                 partial: result.partial,
             };
         }
+        if (result.executed === 0 && result.recorded === 0 && result.notTaken > 0) {
+            // Every step was left out by its test: none of the plan's work is this
+            // request's (AC5). The model does the task, told so.
+            this.handOver(state, {
+                kind: "other_branch",
+                step: plan.allSteps()[0],
+                entry: plan.allEntries()[0],
+                position: 0,
+                delivery: "none",
+                ran: 0,
+                noneNeeded: true,
+            });
+            return handedOver(this.takeNote(state) ?? state.handover?.note) ?? { ok: false, why: "" };
+        }
         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
@@ -1725,12 +1953,15 @@ export class ReplayController {
         const steps = this.stepResultsOf(state);
         const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
         // A costless decline is noise on both sides — *unless* it says something the
-        // recording page cannot learn any other way: a step that actually broke, or
-        // the gate that declined. The service accepts a costless report that carries
-        // either (its errorshandling.md).
+        // recording page cannot learn any other way: a step that actually broke, the
+        // gate that declined, or a plan that stood in front of the other half of
+        // its task (AC5), which the service takes the agent's work after as its
+        // evidence of that half. The service accepts a costless report that carries
+        // any of them (its errorshandling.md).
         if (isBaseline &&
             total <= 0 &&
             !state.declined &&
+            state.handover?.kind !== "other_branch" &&
             !steps?.some((s) => s.status === "failed")) {
             return undefined;
         }
@@ -1771,9 +2002,18 @@ export class ReplayController {
             declined: state.declined,
             // Where the plan handed the task to the model (fallbk.md). Only on
             // `fell_back`: a hand-over before any step ran is `failed`, and a parked
-            // step found after a divergence is still a divergence.
-            fallbackStepIndex: state.outcome === "fell_back" ? state.handover?.stepIndex : undefined,
-            fallbackKind: state.outcome === "fell_back" ? state.handover?.kind : undefined,
+            // step found after a divergence is still a divergence. Except the other
+            // half of an "if … otherwise" (AC5), named whatever the outcome: the
+            // agent's work after it is the service's evidence of that half, whether
+            // or not a step ran first.
+            fallbackStepIndex: state.outcome === "fell_back" || state.handover?.kind === "other_branch"
+                ? state.handover?.stepIndex
+                : undefined,
+            fallbackKind: state.outcome === "fell_back" || state.handover?.kind === "other_branch"
+                ? state.handover?.kind
+                : undefined,
+            // The agent did not take the plan's result and redid the task (AC1).
+            ...(d.redoneBy ? { redoneBy: d.redoneBy } : {}),
             // Segments of this plan's recording that armed later in the turn
             // (segmented.md R-MONEY-4): their share comes off this plan's baseline.
             sharedWith: state.sharedWith.length > 0 ? [...state.sharedWith] : undefined,
@@ -2113,9 +2353,11 @@ export class ReplayController {
         // 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.
+        // could not be sent from here, or the hook's clock, is still a divergence;
+        // so is a stop in front of the other half (AC5), which broke nothing.
         const broke = composed.errored > 0 ||
             (stop !== undefined &&
+                stop.kind !== "other_branch" &&
                 stop.reason !== "not_run" &&
                 stop.reason !== "budget" &&
                 stop.reason !== "cancelled");
@@ -2125,7 +2367,12 @@ export class ReplayController {
         // 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");
+        // A bundle that stops in front of the other half (AC5) is a hand-over,
+        // however the plan got there: booked as the contract books one — `fell_back`
+        // when a step did its work — so the service takes the agent's work after
+        // it as that half's evidence. Booked `diverged`, it never did.
+        const otherHalf = stop?.kind === "other_branch";
+        this.upgrade(state, broke || !didWork ? "failed" : otherHalf ? "fell_back" : "diverged");
         state.stepsPinned += composed.executed;
         // The headline number of this whole design: recovering from a divergence
         // costs nothing, because the proxies were already connected.
@@ -2153,20 +2400,34 @@ export class ReplayController {
             // 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");
+                const note = this.stopNote(state, plan, stop, "none", composed.left);
                 return this.deliverInstead(note, toolName, state.host !== undefined);
             }
+            // The rest is the other half (AC5): the model is told so, in place of
+            // its call, before it does any of the plan's remaining steps.
+            if (stop?.kind === "other_branch" && stop.flatIndex !== undefined) {
+                const note = this.stopNote(state, plan, stop, "none", composed.left);
+                return this.deliverInstead(note, toolName, state.host !== undefined);
+            }
+            // Every remaining step was left out by its test: the steps the session
+            // ran were the whole of the plan this request needs, and it ran to its
+            // end (newestRun.md N7 reads that).
+            const ranOut = !stop && composed.endedAt >= plan.stepCount;
+            const parkedNext = plan.stopsEarly() && composed.endedAt === plan.stepCount;
+            if (ranOut && !parkedNext && composed.notTaken > 0 && state.stepsPinned > 0)
+                state.ranToEnd = true;
             return { kind: "abort" };
         }
         // 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.
+        // outcome stays as judged above, so the report carries no fallback fields
+        // (the other half of an "if … otherwise" excepted: see `buildReport`).
         let text = composed.text;
-        if (stop && stop.kind === "step_failed" && stop.flatIndex !== undefined) {
-            const note = this.stopNote(state, plan, stop, "below");
+        if (stop && (stop.kind === "step_failed" || stop.kind === "other_branch") && stop.flatIndex !== undefined) {
+            const note = this.stopNote(state, plan, stop, "below", composed.left);
             text = `${note}\n\n${composed.text}`;
         }
-        else if (plan.stopsEarly()) {
+        else if (plan.stopsEarly() && composed.endedAt === plan.stepCount) {
             const parked = plan.stopStep();
             const stopKind = this.stopKindOf(state, plan.stopEntry());
             state.handover = {
@@ -2180,6 +2441,8 @@ export class ReplayController {
                     position: plan.stepCount,
                     delivery: "below",
                     executedAbove: plan.currentStepIndex,
+                    // The steps the bundle left out ran no more than the cursor's (AC5).
+                    leftOut: composed.left,
                 }),
                 delivered: true,
             };
@@ -2202,7 +2465,9 @@ export class ReplayController {
      * 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) {
+    stopNote(state, plan, stop, delivery, 
+    /** The steps the bundle left out (AC5): no step that ran. */
+    left = []) {
         const position = stop.flatIndex ?? plan.currentStepIndex;
         const step = plan.allSteps()[position];
         const entry = plan.allEntries()[position];
@@ -2219,8 +2484,12 @@ export class ReplayController {
             // 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",
+            // An output-logic failure stops after its step's tool ran (plan.ts) —
+            // not a sub-task's result mapping after its last step was left out.
+            ranThisStep: stop.stage === "tool_output_logic" && stop.reason !== "result_map",
+            whenText: stop.whenText,
+            subTask: stop.subTask,
+            leftOut: left,
         });
         state.handover ??= {
             kind: stop.kind,
@@ -2267,21 +2536,25 @@ export class ReplayController {
             segment: state.flatStop?.segmentId ?? undefined,
             ran,
             outcome: state.outcome,
-            why: h.kind === "unusable_call"
-                ? "a sub-task of this chain cannot run — the agent does that part itself"
-                : h.kind === "known_bad_step"
-                    ? "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"
-                        : 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 === "host_rejected" || h.stopReason === "host_edited"
-                                    ? "the host stopped this step itself — no fault of the plan; 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",
+            why: h.kind === "other_branch"
+                ? h.noneNeeded
+                    ? "no step of the plan was needed for this request — the agent does the task"
+                    : `this request is the other half: the steps from here are only for when ${h.whenText ?? "their test says so"} — the agent continues`
+                : h.kind === "unusable_call"
+                    ? "a sub-task of this chain cannot run — the agent does that part itself"
+                    : h.kind === "known_bad_step"
+                        ? "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"
+                            : 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 === "host_rejected" || h.stopReason === "host_edited"
+                                        ? "the host stopped this step itself — no fault of the plan; 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",
         });
     }
     /**
@@ -2295,12 +2568,46 @@ export class ReplayController {
             return "nondeterministic_step";
         return state.flatStop ? "unusable_call" : "known_bad_step";
     }
+    /**
+     * The steps before flat position `bound` that ran, 1-based, and the ones
+     * their tests left out (AC5) — the plan cursor's own, and a divergence
+     * bundle's (`extra`). `left` is empty when no step was left out; `ran` is
+     * then not filled, since every step before `bound` ran.
+     */
+    ranBefore(plan, bound, extra = []) {
+        const left = [...(plan?.leftOut() ?? []), ...extra].filter((l) => l.flatIndex < bound);
+        if (left.length === 0)
+            return { ran: [], left };
+        const out = new Set();
+        for (const l of left)
+            for (let i = l.flatIndex; i < Math.min(l.until, bound); i += 1)
+                out.add(i);
+        const ran = [];
+        for (let i = 0; i < bound; i += 1)
+            if (!out.has(i))
+                ran.push(i + 1);
+        return { ran, left };
+    }
     noteFor(state, h) {
         const plan = state.plan;
-        const executed = h.ran ?? (h.ranThisStep ? h.position + 1 : h.position);
+        // The steps before the stop — or the bound a caller gives — less the ones
+        // their tests left out (AC5): a note must never say a step ran that did not.
+        // A `result_map` stop rests on the step left out, which is then named so.
+        const bound = h.ran ?? (h.ranThisStep || h.stopReason === "result_map" ? h.position + 1 : h.position);
+        const before = this.ranBefore(plan, bound, h.leftOut);
+        const skipped = before.left.length > 0;
+        const executed = skipped ? before.ran.length : bound;
+        const executedAbove = h.executedAbove === undefined || !skipped
+            ? h.executedAbove
+            : before.ran.filter((n) => n <= h.executedAbove).length;
         // A step its host stopped was dealt with there — refused, answered, or
         // run with a person's arguments — so it is not among what is left to do.
-        const handled = h.ranThisStep === true || h.stopReason === "host_rejected" || h.stopReason === "host_edited";
+        // Nor is the step a test left out, after which a sub-task's results could
+        // not go back (`result_map`, AC5).
+        const handled = h.ranThisStep === true ||
+            h.stopReason === "host_rejected" ||
+            h.stopReason === "host_edited" ||
+            h.stopReason === "result_map";
         let params;
         try {
             params = plan?.parameters;
@@ -2327,13 +2634,30 @@ 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,
+            ...(skipped
+                ? {
+                    ranSteps: before.ran,
+                    leftOut: before.left.map((l) => ({
+                        from: l.flatIndex + 1,
+                        to: Math.min(l.until, bound),
+                        toolName: l.toolName,
+                        text: l.text,
+                    })),
+                }
+                : {}),
+            executedAbove,
             inFlight: h.inFlight,
             ranThisStep: h.ranThisStep,
             totalSteps: plan?.totalSteps ?? state.stepsPlanned,
-            remainingTools: plan ? plan.toolsFrom(handled ? h.position + 1 : h.position) : [],
+            // A step that runs only under a test is marked so: the list must not
+            // read as steps this request needs (AC5).
+            remainingTools: plan ? plan.remainingFrom(handled ? h.position + 1 : h.position) : [],
             params,
             delivery: h.delivery,
+            whenText: h.whenText ?? null,
+            subTask: h.subTask ?? null,
+            // "None was needed" is the note's own wording for the end of the plan.
+            ...(h.noneNeeded ? { stepIndex: plan?.totalSteps ?? state.stepsPlanned } : {}),
         });
     }
     /**
@@ -2449,7 +2773,13 @@ export class ReplayController {
         if (!force && !this.recordedFallback)
             return undefined;
         const source = state.sourceRun;
-        return source ? (entry) => source.outputFor(entry) : undefined;
+        if (!source)
+            return undefined;
+        // A step a test left out passes over its recorded output, unless a
+        // correction added it (AC5, source-run.ts).
+        return Object.assign((entry) => source.outputFor(entry), {
+            leftOut: (entry) => source.leftOut(entry),
+        });
     }
     /**
      * Wait for a plan's parameters within `budgetMs`, then judge whether the plan
@@ -2631,9 +2961,23 @@ export class ReplayController {
         // step of the same number — the very mix-up the payloads are there to end.
         const own = !info.entry || info.entry.depth === 0;
         // A step whose input logic threw never had an input: the `{}` the plan
-        // reports there is a placeholder, not a call with no arguments.
-        const sent = own && info.stage !== "tool_input_logic" ? info.input : undefined;
-        const received = own ? info.output : undefined;
+        // reports there is a placeholder, not a call with no arguments. Nor had a
+        // step its test left out or stopped in front of (AC5).
+        const noCall = info.stage === "tool_input_logic" || info.stage === "when_logic" || status === "not_taken";
+        const sent = own && !noCall ? info.input : undefined;
+        const received = own && !noCall ? info.output : undefined;
+        // The call, kept whole for the turn's newest run (AC2): only one that
+        // really went out — it answered, or it answered with an error.
+        if (state.keepCalls &&
+            !noCall &&
+            info.input !== undefined &&
+            (status === "ok" || (status === "failed" && info.stage === "tool_call"))) {
+            // By frame, not by scenario: a chain that calls the same sub-task twice
+            // makes two calls of each of its steps, and both are the turn's (AC5
+            // review). A frame is one call of one sub-task.
+            const callKey = info.entry ? `${info.entry.frame.id}#${info.entry.stepIndex}` : key;
+            this.keepCall(state, callKey, info, status === "failed");
+        }
         state.stepResults.set(key, {
             stepIndex: info.step.stepIndex,
             toolName: info.step.toolName ?? "",
@@ -2654,6 +2998,42 @@ export class ReplayController {
             chainRevision: info.entry && info.entry.depth > 0 ? info.entry.frame.chainRevision : undefined,
         });
     }
+    /**
+     * Keep one call of the plan whole (AC2): its arguments and its answer,
+     * redacted and capped as a recorded call's are. Later news about the same
+     * step replaces earlier, in place, so the order is the order the calls went
+     * out. Past {@link TURN_CALLS_MAX_CHARS} a call keeps only a report's cut.
+     */
+    keepCall(state, key, info, failed) {
+        const calls = (state.turnCalls ??= new Map());
+        if (calls.size >= MAX_STEP_RESULTS && !calls.has(key))
+            return;
+        const spent = state.turnCallChars ?? 0;
+        const room = spent < TURN_CALLS_MAX_CHARS;
+        const input = room
+            ? serializeCapped(redact(info.input ?? {}))
+            : reportPayload(serializeCapped(redact(info.input ?? {})), true);
+        const answer = info.output === undefined ? undefined : room ? heldPayload(info.output) : reportPayload(info.output);
+        const inSegment = info.entry && info.entry.depth > 0;
+        const call = {
+            scenarioId: inSegment ? info.entry.scenarioId : (state.scenarioId ?? info.entry?.scenarioId ?? ""),
+            stepIndex: info.step.stepIndex,
+            chainRevision: inSegment
+                ? (info.entry.frame.chainRevision ?? null)
+                : (state.chainRevision ?? null),
+            toolName: info.step.toolName ?? "",
+            input,
+            ...(failed
+                ? { error: info.error ? capText(redactText(info.error), DEFAULT_MAX_PAYLOAD_BYTES) : answer }
+                : answer !== undefined
+                    ? { output: answer }
+                    : {}),
+        };
+        const before = calls.get(key);
+        const size = (c) => c ? c.input.length + (c.output?.length ?? 0) + (c.error?.length ?? 0) : 0;
+        state.turnCallChars = spent - size(before) + size(call);
+        calls.set(key, call);
+    }
     /** The step verdicts, in chain order, for the execution report. */
     stepResultsOf(state) {
         if (state.stepResults.size === 0)
@@ -2694,6 +3074,16 @@ export class ReplayController {
             });
             return;
         }
+        if (info.outcome === "not_taken") {
+            const text = testWords(info.step.when?.text);
+            logLine("replay.step_not_taken", {
+                n: info.step.stepIndex,
+                tool: info.step.toolName ?? info.step.callIntent ?? undefined,
+                scenario: info.entry && info.entry.depth > 0 ? info.entry.scenarioId : undefined,
+                why: `its test said this request does not need it${text ? ` — only for when ${text}` : ""}; left out, and the plan goes on`,
+            });
+            return;
+        }
         logLine("replay.step", {
             n: info.step.stepIndex,
             tool: mcp?.toolName ?? info.step.toolName,
@@ -2726,6 +3116,12 @@ export class ReplayController {
         }
         state.retired = true;
         state.pinned.clear();
+        // A note naming a step to call next is void once the plan is: after a
+        // divergence its bundle may have run that step already, and after a
+        // hand-over it contradicts the hand-over's note. Only "the sequence is
+        // complete", from a plan that finished, still holds (AC5 review).
+        if (state.skipNote && !(completing && state.skipNote.complete))
+            state.skipNote = undefined;
         // A call waiting for a pin to thread has nothing left to wait for.
         this.notifyPins(state);
     }
@@ -2849,6 +3245,47 @@ function reportPayload(json, clean = false) {
     }
     return capText(redactJsonText(json), REPORT_PAYLOAD_MAX_BYTES);
 }
+/**
+ * A plan call's answer as a recorded call keeps it (autocorrect.md AC2): the
+ * JSON redacted by its keys and capped at 64 KiB the way the control server
+ * records every call — whole, not cut to what a report carries. Text that is
+ * not JSON, or too long to scan, is redacted as text.
+ */
+function heldPayload(text) {
+    if (text.length <= REDACT_SCAN_MAX_CHARS) {
+        try {
+            return serializeCapped(redact(JSON.parse(text)));
+        }
+        catch {
+            /* not JSON: kept as text */
+        }
+    }
+    return capText(text, DEFAULT_MAX_PAYLOAD_BYTES, redactText);
+}
+/** Whether an entry runs only under a test (AC5): its own, or a sub-task's it is in. */
+function underTest(entry) {
+    if (entry.step.when)
+        return true;
+    for (let f = entry.frame; f; f = f.parent)
+        if (f.when)
+            return true;
+    return false;
+}
+/** The tests of a flat chain, by flat position, for the `plan.armed` line (AC5). */
+function testLines(entries) {
+    // A sub-task's test sits where the sub-task begins — at its callee's first
+    // step when its chain begins with a call.
+    const { startsAt } = frameEdges(entries);
+    const lines = entries
+        .map((e, i) => {
+        const own = e.step.when;
+        const call = (startsAt.get(i) ?? []).find((f) => f.when)?.when;
+        const t = own ?? call;
+        return t ? `${i}:${call && !own ? "call/" : ""}${t.otherwise}` : undefined;
+    })
+        .filter((s) => s !== undefined);
+    return lines.length > 0 ? lines.join(",") : undefined;
+}
 /**
  * The index a hand-over reports, in the *caller's* chain (R-CALL-32).
  *