@basein/runner 0.3.18 → 0.3.20

package/dist/control/server.js

@@ -37,9 +37,12 @@ import { asSent, userText } from "../record/prompt-text.js";
 import { redact, redactText } from "../record/redact.js";
 import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateString, truncateStrings, } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
-import { NullRecorder, isAttentionReader, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, isScenarioDisputer, isScenarioReporter, isServiceProber, isToolListReporter, } from "../record/recorder.js";
+import { NullRecorder, isAttentionReader, isIntentMatcher, isMatchAware, isNextScenarioSource, isRecorderHealthReporter, isRunCreationAware, isScenarioDisputer, isScenarioReporter, isServiceProber, isToolListReporter, } from "../record/recorder.js";
 import { ReplayController, POLL_HOLD_MS, REPORT_TOOL_NAME, } from "../replay/controller.js";
 import { localDay } from "../replay/derive.js";
+import { RecordedValueError, markedKey } from "../replay/plan.js";
+import { evalToolInputLogic } from "../replay/logic.js";
+import { callMayChange, readsOnly } from "../replay/reads-only.js";
 import { calculateCostUsd, hasModelPricing } from "../replay/pricing.js";
 import { logDetail, logLine, logOnce, errText } from "../util/log.js";
 import { journal } from "../util/journal.js";
@@ -105,6 +108,118 @@ const PROMPT_WAIT_MS = 7_500;
 const INTENT_ARM_PROBE_MS = 500;
 /** What an intent-armed plan may spend arming — derivation — inside `PreToolUse`. */
 const INTENT_ARM_DERIVE_MS = 1_500;
+/**
+ * How long the agent's call after a decision may wait for a next scenario's
+ * values (the service's offer1.md O5): they are read while the agent decides,
+ * so this wait is only ever for a reading still on its way, or one read again
+ * with the call itself. The call is about to be replaced, so waiting costs the
+ * agent nothing; it stays well inside the route's own deadline.
+ */
+const NEXT_HIT_WAIT_MS = 6_000;
+/** How long the question "what can follow this decision" may take. It is asked in the background. */
+const NEXT_FETCH_MS = 5_000;
+/** How long a next scenario's arm waits for its values to settle, in the background. */
+const NEXT_READY_MS = 8_000;
+/** At most this many scenarios follow one decision (the service sends no more either). */
+const NEXT_MAX = 4;
+/** The turn's request a decision fragment carries, in characters (offer1.md O2). */
+const DECISION_REQUEST_MAX = 4_000;
+/**
+ * How long the agent's call after a decision waits for the service's answer
+ * to "what can follow it" when it has not come yet. Only that answer: never
+ * the arms behind it.
+ */
+const NEXT_ROUTE_WAIT_MS = 1_000;
+/** Tools whose call is its command: the same tool with another command is another call (offer1.md O8). */
+const COMMAND_TOOLS = new Set(["Bash", "PowerShell"]);
+/** A shell call's command, trimmed; empty when it has none. */
+function commandOf(args) {
+    const c = args && typeof args === "object" ? args.command : undefined;
+    return typeof c === "string" ? c.trim() : "";
+}
+/** What `replay.next_miss` says for each way a decision's next scenarios end unused. */
+const NEXT_MISS_WHY = {
+    other_values: "the agent's call has the tool a next scenario starts with, but not its values — it took that way its own way; that work is recorded, and becomes a scenario of its own",
+    own_way: "the agent's call may change something and starts none of them — it is doing a way of its own; that work is recorded, and becomes a scenario of its own, and none of these may start in the middle of it",
+    not_ready: "the scenario that starts with this call's tool was not armed in time, and the call may change something — the agent went on its own way",
+    calls_limit: "the agent's first calls after the decision started none of them — it is doing the work itself; that work is recorded, and becomes a scenario of its own",
+    turn_ended: "the turn ended before any of them was used",
+    no_delivery_tool: "the scenario would be delivered through mcp__bir__run_scenario, which no running bir server serves",
+};
+/** One argument as a call compares it: trimmed text for a scalar, canonical JSON for the rest. */
+function argText(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return canonicalJson(value);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const o = value;
+        return `{${Object.keys(o)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value ?? null) ?? "null";
+}
+/**
+ * A planned first step's input against the agent's own arguments, value for
+ * value (offer1.md O5). `missing` when the only differences are values the
+ * plan does not have — empty, or held by a mark — that the agent gave. The
+ * runner's reserved arguments (`__bir…`) are never compared.
+ */
+function sameArguments(planned, agent) {
+    if (!agent || typeof agent !== "object" || Array.isArray(agent))
+        return "other";
+    const a = agent;
+    let missing = false;
+    for (const key of new Set([...Object.keys(planned), ...Object.keys(a)])) {
+        if (key.startsWith("__bir"))
+            continue;
+        const p = argText(planned[key]);
+        const v = argText(a[key]);
+        if (p === v)
+            continue;
+        if (v !== "" && (p === "" || markedKey(planned[key]) !== undefined)) {
+            missing = true;
+            continue;
+        }
+        return "other";
+    }
+    return missing ? "missing" : "hit";
+}
+/** A next scenario's plan that was never announced: it never runs, and is never reported. */
+function dropNextState(state) {
+    state.plan = undefined;
+    state.mode = "none";
+    state.retired = true;
+    state.pinned.clear();
+    state.reported = true;
+}
+/** Drop an entry's plan, now or when its arm lands — all but `kept`, the one that hit. */
+function dropNextEntry(entry, kept) {
+    if (entry.state) {
+        if (entry.state !== kept)
+            dropNextState(entry.state);
+        return;
+    }
+    void entry.arming.then((late) => {
+        if (late && late !== kept)
+            dropNextState(late);
+    });
+}
+/**
+ * The agent's calls after a decision that are checked against its next
+ * scenarios: a scenario is a hit only on the way the agent starts, never in
+ * the middle of work it is already doing.
+ */
+const NEXT_CALLS_MAX = 5;
 /** How long a fragment's `PreToolUse` waits to learn whether its run was created. */
 const FRAGMENT_CREATE_MS = 300;
 /** What `close()` spends draining the last runs to the service before it lets go. */
@@ -946,7 +1061,20 @@ export class ControlServer {
                     lastStepHit: s.run.intent.lastStepHit ?? null,
                 }
                 : null,
-            fragment: s.run?.fragment ? { state: s.run.fragment.state } : null,
+            fragment: s.run?.fragment
+                ? { state: s.run.fragment.state, ...(s.run.fragment.decision ? { decision: true } : {}) }
+                : null,
+            // The calculated scenarios that can follow a decision of this turn
+            // (offer1.md O3): how many are ready for the agent's next call, and why
+            // the set ended once it has.
+            next: s.run?.next
+                ? {
+                    entries: s.run.next.entries.length,
+                    armed: s.run.next.entries.filter((e) => e.state?.plan && !e.state.retired).length,
+                    calls: s.run.next.calls,
+                    ended: s.run.next.ended ?? null,
+                }
+                : null,
             // The service's offer to record the turn as a recording's newest run,
             // and what became of it (newestRun.md).
             repeat: s.run?.repeat ? { state: s.run.repeat.state, of: s.run.repeat.runId } : null,
@@ -964,6 +1092,10 @@ export class ControlServer {
             // be invisible: an operator has to be able to see which of the two this
             // machine is doing without reading a log file.
             segmentArm: this.replay.segmentArm,
+            // And whether a step's intent may start a plan in its own PreToolUse,
+            // which means waiting for the probe there (it follows segmentArm unless
+            // BIR_INTENT_ARM says otherwise). For `bir doctor`.
+            intentArm: this.intentArming(),
             authUrl: resolveAuthUrl() || null,
             sessionId: this.sessionId,
             pid: process.pid,
@@ -2095,6 +2227,12 @@ export class ControlServer {
         if (!otherHost(session))
             state.reportTool = () => this.reportToolServed();
         this.declineWithoutDeliveryTool(state);
+        // A plan that stops at its decision is billed only up to the stop (the
+        // service's segmentsbreakdown.md SB-26): its hand-over takes this mark. A
+        // plan of the prompt without one keeps the window it always had.
+        if (!otherHost(session) && this.replay.stopsAtDecision(state)) {
+            state.markUsage = () => markTranscriptUsage(session.transcriptPath);
+        }
         // A steer plan with a shell or file-write step can only be followed if the
         // directive shows its computed arguments (the pin guard holds those steps
         // to their exact shape), so give its parameters a moment to settle —
@@ -2812,6 +2950,9 @@ export class ControlServer {
         run.pendingDirective = undefined;
         if (unannounced)
             this.shelveUnannounced(unannounced);
+        // The scenarios that could have followed a decision and were never used:
+        // never announced, never reported (offer1.md O7).
+        this.endNext(run, "turn_ended");
         // A `run_scenario` still waiting for this run's plan will never get it.
         this.directCalls = this.directCalls.filter((c) => c.run !== run);
         const durationMs = Date.now() - run.startedAtMs;
@@ -3021,11 +3162,21 @@ export class ControlServer {
             // that finished in three steps would be billed for everything the agent
             // did afterwards, and its saving would read as a loss.
             let end = nextMark;
+            // A plan of the prompt stopped at its decision after a step ran: its
+            // window ends at the hand-over (the service's segmentsbreakdown.md
+            // SB-26), and the agent's decision and the half it took are not on its
+            // bill. Every other plan of the prompt keeps its window: the answer is
+            // still the plan's work.
+            const atDecision = state.handover?.kind === "decision" && state.retiredMark !== undefined;
             if (state.armedBy === "intent") {
                 windowCost = this.costSince(session, state.usageMark);
                 windowMs = (state.retiredAt ?? next?.armedAt ?? Date.now()) - state.armedAt;
                 end = state.retiredMark ?? nextMark;
             }
+            else if (atDecision) {
+                windowMs = (state.retiredAt ?? Date.now()) - run.startedAtMs;
+                end = state.retiredMark;
+            }
             else if (next) {
                 windowMs = next.armedAt - run.startedAtMs;
             }
@@ -3047,11 +3198,15 @@ export class ControlServer {
             });
             if (!report)
                 return;
-            if (state.armedBy === "intent") {
+            if (state.armedBy === "intent" || atDecision) {
                 logDetail("replay.done", {
                     scenario: state.scenarioId ?? undefined,
                     windowMs: Math.max(0, windowMs),
-                    billedTo: state.retiredMark !== undefined ? "its own retire" : "the next arm or the turn",
+                    billedTo: atDecision
+                        ? "its decision"
+                        : state.retiredMark !== undefined
+                            ? "its own retire"
+                            : "the next arm or the turn",
                 });
             }
             // The plan ran to its end, and no redo of the model's own was recorded:
@@ -3612,6 +3767,7 @@ export class ControlServer {
                 // A hand-over inside `preTool` (an input logic that threw) must still
                 // schedule the fragment, even though this call ends here.
                 this.noteHandover(run);
+                this.noteDecision(session, run);
                 if (action.kind === "pin") {
                     // The same tool is not the same call. A pin swaps the model's
                     // arguments for the step's and approves them, so it is kept only for
@@ -3674,30 +3830,45 @@ export class ControlServer {
             const note = planning ? undefined : this.replay.takeNote(run.replay);
             if (note) {
                 this.noteHandover(run);
+                this.noteDecision(session, run);
                 return this.preToolAnswer(this.replay.deliverInstead(note, toolName));
             }
-            // The model is doing the matched task itself, and the service asked for
-            // that run to be recorded as the recording's newest (newestRun.md N1).
-            // Opened before the probe below, so the turn is recorded from this call
-            // on like any recording turn — a plan an intent match arms in it too.
-            if (this.repeatDue(run))
-                this.openRepeat(session, run);
-            // 2. The model is driving: look for a scenario by this iteration's intent.
-            //    Never in plan mode, where nothing may run on the user's behalf.
-            //    If the deadline answers first, it answers `{}`: the call runs as
-            //    written, and a plan armed in its place was never announced.
+            // If the deadline answers first, it answers `{}`: the call runs as
+            // written, and a plan armed in its place below was never announced.
             if (!planning && !lateSet) {
                 onLate?.(() => {
                     overran = true;
                     return {};
                 });
             }
-            const armed = planning
-                ? undefined
-                : await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
+            // 2. The agent's call after a plan's decision: the first step of a
+            //    calculated scenario that can follow it (the service's offer1.md
+            //    O4–O6)? Then that scenario runs in this call's place. Before the
+            //    probe below: this check is exact (the same tool, the same values)
+            //    and asks the service nothing at this call. Never in plan mode.
+            if (!planning) {
+                this.noteDecision(session, run);
+                const hit = await this.tryNextScenarios(session, run, toolName, modelArgs, () => overran);
+                if (hit)
+                    return hit;
+            }
+            // The model is doing the matched task itself, and the service asked for
+            // that run to be recorded as the recording's newest (newestRun.md N1).
+            // Opened before the probe below, so the turn is recorded from this call
+            // on like any recording turn — a plan an intent match arms in it too.
+            if (this.repeatDue(run))
+                this.openRepeat(session, run);
+            // 3. The model is driving: look for a scenario by this iteration's intent.
+            //    Never in plan mode, where nothing may run on the user's behalf, and
+            //    not once the deadline has answered: nothing new may start then.
+            const armed = planning || overran ? undefined : await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
             if (armed) {
-                if (!overran)
+                if (!overran) {
+                    // The plan answers in this call's place: the agent's work from here
+                    // is that plan's, never the other half after a decision (SB-16).
+                    this.dropDecisionFragment(run, run.replay);
                     return armed;
+                }
                 const late = run.replay;
                 if (late && late.armedBy === "intent" && late.plan && !late.retired) {
                     logLine("replay.decision", {
@@ -3711,12 +3882,17 @@ export class ControlServer {
                 }
                 // The call ran as the model wrote it: recorded below as its own.
             }
-            // 3. No scenario took over: the model's own work after a hand-over is
+            // 4. No scenario took over: the model's own work after a hand-over is
             //    recorded as a fragment, starting with this call.
             // Not for the call an intent match just armed a plan beside: the plan
-            //    runs next, and the fragment opens on the model's own work after it.
-            if (run.fragment?.state === "due" && !run.pendingDirective) {
-                await this.openFragment(session, run, reasoning, toolName, modelArgs);
+            //    runs next, and the fragment opens on the model's own work after it
+            //    — unless it was scheduled at a decision, whose fragment is the
+            //    other half only when the agent's own call opens it (SB-16).
+            if (run.fragment?.state === "due") {
+                if (!run.pendingDirective)
+                    await this.openFragment(session, run, reasoning, toolName, modelArgs);
+                else
+                    this.dropDecisionFragment(run, run.pendingDirective.state);
             }
         }
         // The arguments that will actually run — which is what must be correlated and
@@ -4314,14 +4490,19 @@ export class ControlServer {
         return [...out];
     }
     /**
-     * Per recording a plan of this turn came from, how far that plan got
-     * (segmented.md R-OUT-6).
+     * Per plan of this turn, its recording and how far the plan got in its own
+     * chain (segmented.md R-OUT-6).
      *
      * The server uses it to refuse a segment that starts *before* where this turn
      * already is: re-running steps the turn has just done is worse than not
-     * replaying at all. The largest position per recording wins, and a plan
-     * declined for anything but a known-bad first step reports nothing — it ran
-     * none of the recording, so it blocks none of it.
+     * replaying at all. The position is the plan's own: the step it handed over
+     * at (its decision included), or its last step when it ran to its end. The
+     * server maps it onto the recording — a segment's first position, a
+     * decision's step before it — and takes the largest per recording (the
+     * service's segmentsbreakdown.md D18). One entry per plan, so that two plans
+     * of one recording, whose own positions are on different scales, never
+     * hide each other. A plan declined for anything but a known-bad first step
+     * reports nothing — it ran none of the recording, so it blocks none of it.
      *
      * Rebuilt on every probe rather than cached: a plan that hands over between
      * two calls changes the answer.
@@ -4354,15 +4535,15 @@ export class ControlServer {
             }
             if (position === undefined)
                 continue;
-            const seen = best.get(recording);
+            const seen = best.get(state.scenarioId);
             if (!seen || position > seen.position) {
-                best.set(recording, { position, scenarioId: state.scenarioId });
+                best.set(state.scenarioId, { runId: recording, position });
             }
         }
-        return [...best].map(([runId, v]) => ({
-            runId,
+        return [...best].map(([scenarioId, v]) => ({
+            runId: v.runId,
             position: v.position,
-            scenarioId: v.scenarioId,
+            scenarioId,
         }));
     }
     /**
@@ -4446,7 +4627,10 @@ export class ControlServer {
             stepPosition: run.ordering.next,
             excludeRuns: this.excludeRunsFor(run),
             ranThrough: this.ranThroughFor(run),
-            ...(this.replay.segmentArm ? { acceptSegments: true } : {}),
+            // Segments are asked for only where one can arm: a probe that is
+            // waited on, in Claude Code (below). Any other probe gets the
+            // service's `segmentWouldArm` instead, logged as observe-only.
+            ...(this.replay.segmentArm && this.intentArming() && !otherHost(session) ? { acceptSegments: true } : {}),
             supportsCalls: true,
             // Left out for Claude Code: a missing framework means Claude Code to
             // the service, which matches a step only inside its own host.
@@ -4534,6 +4718,9 @@ export class ControlServer {
         // the jail it may not leave (replay/builtins.ts). The session's own cwd
         // from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
+        // The request this plan serves, for a note at its decision (SB-18): the
+        // turn's prompt. `arm` was given this step's intent instead.
+        state.request = run.input || undefined;
         this.declineWithoutDeliveryTool(state);
         if (!state.plan) {
             // A declined intent hit reports nothing: the turn's cost is not a
@@ -4541,6 +4728,41 @@ export class ControlServer {
             state.reported = true;
             return undefined;
         }
+        // HOW THE DIRECTIVE REACHES THE MODEL. Mid-task, the call that matched is
+        // usually the model's own ordinary work — a `git status`, a file read —
+        // and denying it, or swapping its output for a directive, shows the user a
+        // blocked call and reads to the model like prompt injection. So the call
+        // runs untouched and the directive rides on its PostToolUse, the channel a
+        // hand-over note already uses; the plan starts at its first step after.
+        //
+        // The exception is a call that IS the plan's first step: letting it run
+        // would have the plan run it a second time — a duplicated write. That one
+        // is still answered in place. The same tool is not the same call, though:
+        // it is held to the pin guard's rule (control/pin-guard.ts), so a `git
+        // status` is never swapped for a deploy that happens to be a Bash step.
+        const inPlace = this.isFirstStep(state, toolName, modelArgs);
+        // NEVER TWICE (the service's offer1.md O8). A plan that starts after this
+        // call — not in its place — and calls the same tool somewhere would make
+        // that call again: the agent's e-mail, then the plan's own e-mail (issue
+        // fx2). It is not started; the agent goes on. A read the runner knows is
+        // only a read may repeat: reading twice changes nothing.
+        if (!inPlace && this.planCallsTool(state, toolName, modelArgs)) {
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "would_repeat",
+                run: run.runId,
+                scenario: state.scenarioId ?? undefined,
+                kind: match.kind ?? "scenario",
+                tool: toolName,
+                why: "the plan would start after this call and make a call of the same tool again — never twice; the agent goes on",
+            });
+            state.plan = undefined;
+            state.mode = "none";
+            state.retired = true;
+            state.pinned.clear();
+            state.reported = true;
+            return undefined;
+        }
         state.usageMark = markTranscriptUsage(session.transcriptPath);
         // The closure, not the mark: only the control server holds the transcript
         // path, and a completing retire happens in the controller (R-MONEY-3).
@@ -4563,19 +4785,6 @@ export class ControlServer {
         run.replay = state;
         run.intent.armed += 1;
         const directive = this.replay.directiveFor(state) ?? "";
-        // HOW THE DIRECTIVE REACHES THE MODEL. Mid-task, the call that matched is
-        // usually the model's own ordinary work — a `git status`, a file read —
-        // and denying it, or swapping its output for a directive, shows the user a
-        // blocked call and reads to the model like prompt injection. So the call
-        // runs untouched and the directive rides on its PostToolUse, the channel a
-        // hand-over note already uses; the plan starts at its first step after.
-        //
-        // The exception is a call that IS the plan's first step: letting it run
-        // would have the plan run it a second time — a duplicated write. That one
-        // is still answered in place. The same tool is not the same call, though:
-        // it is held to the pin guard's rule (control/pin-guard.ts), so a `git
-        // status` is never swapped for a deploy that happens to be a Bash step.
-        const inPlace = this.isFirstStep(state, toolName, modelArgs);
         logLine("replay.intent_armed", {
             run: run.runId,
             scenario: state.scenarioId ?? undefined,
@@ -4616,6 +4825,433 @@ export class ControlServer {
             return false;
         }
     }
+    /**
+     * The agent's call against `state`'s first step, value for value (the
+     * service's offer1.md O5): `hit` when every argument is the step's own,
+     * `missing` when the only differences are values the plan does not have
+     * (a target the reading left empty, which the agent's call may hold), and
+     * `other` otherwise.
+     */
+    firstStepVerdict(state, toolName, modelArgs) {
+        const plan = state.plan;
+        if (!plan || plan.expectedTool() !== toolName)
+            return "other";
+        let first;
+        try {
+            const entry = plan.currentEntry();
+            if (!entry || entry.depth !== 0)
+                return "other";
+            first = plan.toolInputForCurrentStep();
+        }
+        catch (err) {
+            // A value the request did not give, or one only a step works out: the
+            // agent's call may hold it.
+            if (err instanceof RecordedValueError)
+                return "missing";
+            logDetail("replay.first_step_unknown", { tool: toolName, error: errText(err) });
+            return "other";
+        }
+        return sameArguments(first, modelArgs);
+    }
+    /**
+     * Whether `state`'s plan calls `toolName` in a step it would run: what makes
+     * a plan started after a call of that tool make it a second time (the
+     * service's offer1.md O8). A tool that only reads never counts — reading
+     * twice changes nothing — by the service's own rule ({@link readsOnly}): a
+     * `crm_search_customers` mid-task never keeps a plan that searches later from
+     * starting.
+     */
+    planCallsTool(state, toolName, modelArgs) {
+        const plan = state.plan;
+        if (!plan || readsOnly(toolName))
+            return false;
+        const same = plan
+            .allEntries()
+            .slice(0, plan.stepCount)
+            .filter((e) => e.step.toolName === toolName);
+        if (same.length === 0)
+            return false;
+        if (!COMMAND_TOOLS.has(toolName))
+            return true;
+        // A shell's call is its command: a `git status` is not repeated by a plan
+        // that deploys. Only a step that would run this very command repeats it —
+        // judged on the values the plan has now; a step whose command needs a
+        // result first cannot be told, and does not count.
+        const live = commandOf(modelArgs);
+        if (!live)
+            return false;
+        const params = plan.parameters;
+        return same.some((e) => {
+            try {
+                return commandOf(evalToolInputLogic(e.step.toolInputLogic ?? "return {};", params, e.frame.intent ?? "", {})) === live;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    // ── what can follow a decision (the service's offer1.md) ──────────────────
+    /**
+     * A plan of this turn stopped at its decision: ask the service, once per
+     * plan, which calculated scenarios can follow it, and arm each in the
+     * background while the agent reads the note and decides (offer1.md O3, O4).
+     * Called wherever a hand-over is first seen; a second call for the same plan
+     * does nothing.
+     */
+    noteDecision(session, run) {
+        if (run.finished || otherHost(session))
+            return;
+        if (!this.replay.enabled || !this.intentArming())
+            return;
+        if (!isNextScenarioSource(this.recorder))
+            return;
+        for (const state of run.replays) {
+            const h = state.handover;
+            if (h?.kind !== "decision" || !state.scenarioId)
+                continue;
+            const next = (run.next ??= { asked: new Set(), round: 0, answered: false, entries: [], calls: 0 });
+            if (next.asked.has(state.scenarioId))
+                continue;
+            next.asked.add(state.scenarioId);
+            // A new decision starts a new round: what could follow an earlier one is
+            // no longer checked (its unused plans are dropped), and the agent's next
+            // calls are checked against what can follow this one.
+            for (const e of next.entries)
+                dropNextEntry(e);
+            next.entries = [];
+            next.round += 1;
+            next.answered = false;
+            next.ended = undefined;
+            next.calls = 0;
+            next.asking = this.fetchNext(session, run, state.scenarioId, h.stepIndex, next.round);
+        }
+    }
+    /**
+     * Ask for a decision's next scenarios (offer1.md O3): each is checkable as
+     * soon as the service answers, and armed in the background, each on its own
+     * (O4). Resolves when the service has answered, not when the arms have.
+     * Never rejects.
+     */
+    async fetchNext(session, run, planId, stepIndex, round) {
+        const startedAt = Date.now();
+        let answer = null;
+        try {
+            if (isNextScenarioSource(this.recorder)) {
+                answer = await this.recorder.nextScenarios(planId, { turnId: run.turnId, supportsCalls: true }, { timeoutMs: NEXT_FETCH_MS });
+            }
+        }
+        catch {
+            answer = null;
+        }
+        const next = run.next;
+        // A later decision of the turn has its own round: this answer is no one's.
+        if (!next || next.round !== round || next.ended || run.finished)
+            return;
+        next.answered = true;
+        next.asking = undefined;
+        const offered = (answer?.next ?? []).filter((m) => !!m && typeof m.scenarioId === "string");
+        // A plan already armed this turn is never armed again from here (the
+        // probe's own `exclude`): the plan that just stopped, above all.
+        const taken = new Set(run.replays.map((s) => s.scenarioId).filter((id) => typeof id === "string"));
+        const fresh = [];
+        for (const match of offered) {
+            if (next.entries.length + fresh.length >= NEXT_MAX)
+                break;
+            if (taken.has(match.scenarioId))
+                continue;
+            if ([...next.entries, ...fresh].some((e) => e.match.scenarioId === match.scenarioId))
+                continue;
+            const entry = {
+                planId,
+                stepIndex,
+                // `arm` reads a numeric similarity, and the key says how it was found.
+                match: { ...match, similarity: typeof match.similarity === "number" ? match.similarity : 1, key: "decision" },
+                firstTool: typeof match.firstTool === "string" && match.firstTool ? match.firstTool : null,
+                arming: Promise.resolve(undefined),
+            };
+            entry.arming = this.armNext(session, run, entry);
+            fresh.push(entry);
+        }
+        // Checkable at once: a call waits only for the arm of a scenario that
+        // starts with its own tool, never for the others.
+        next.entries.push(...fresh);
+        if (fresh.length === 0) {
+            logDetail("replay.next_none", {
+                run: run.runId,
+                plan: planId,
+                offered: offered.length,
+                why: answer
+                    ? "no calculated scenario follows this decision yet — what the agent does next is recorded, and becomes one"
+                    : "the service did not say what follows this decision — the agent goes on",
+            });
+            return;
+        }
+        // The audit line once every arm has answered; nobody waits for it.
+        void Promise.all(fresh.map((e) => e.arming)).then(() => {
+            if (run.finished || next.round !== round)
+                return;
+            logLine("replay.next_ready", {
+                run: run.runId,
+                plan: planId,
+                n: fresh.filter((e) => e.state?.plan).length,
+                of: fresh.length,
+                ms: Date.now() - startedAt,
+                scenarios: fresh
+                    .map((e) => `${e.match.scenarioId}:${e.firstTool ?? "?"}:${e.state?.plan ? "ready" : (e.state?.declined ?? "failed")}`)
+                    .join(","),
+                why: "the calculated scenarios that can follow this decision are ready for the agent's next call",
+            });
+        });
+    }
+    /**
+     * Arm one next scenario in the background (offer1.md O4): its values read
+     * from the turn's request and its results so far — or, once more, with the
+     * agent's own call (O5) — and settled, so a call is compared with the first
+     * step as it would really run. Never rejects.
+     */
+    async armNext(session, run, entry, liveCall) {
+        try {
+            const state = await this.replay.arm(entry.match, run.input, this.wrapped, "intent", {
+                ...(liveCall ? { liveCall } : {}),
+                recentResults: this.recentResultsFor(session, "call"),
+                agentDay: this.agentDayFor(session),
+                atDecision: { scenarioId: entry.planId, stepIndex: entry.stepIndex },
+            }, this.hostContext(session, run));
+            if (state.plan)
+                await this.withinBudget(state.plan.ready().catch(() => undefined), NEXT_READY_MS);
+            entry.state = state;
+            return state;
+        }
+        catch (err) {
+            logDetail("replay.next_arm_failed", { scenario: entry.match.scenarioId ?? undefined, error: errText(err) });
+            return undefined;
+        }
+    }
+    /**
+     * The agent's call after a decision, against the scenarios that can follow
+     * it (offer1.md O5, O6). A hit — the call is a scenario's first step, value
+     * for value — is answered in the call's place with that scenario's directive:
+     * the agent calls `run_scenario`, and the scenario runs every step, this one
+     * included, once. Undefined otherwise: the call runs as the agent wrote it.
+     */
+    async tryNextScenarios(session, run, toolName, modelArgs, overran) {
+        const next = run.next;
+        if (!next || next.ended || run.finished || otherHost(session))
+            return undefined;
+        if (this.replay.isDirectTool(toolName))
+            return undefined;
+        const deadline = Date.now() + positiveEnv("BIR_NEXT_HIT_WAIT_MS", NEXT_HIT_WAIT_MS);
+        const left = () => Math.max(0, deadline - Date.now());
+        // The service has not answered yet — the agent decided quickly. Its answer
+        // only is waited for, and briefly: not the arms that follow it.
+        if (!next.answered && next.asking) {
+            await this.withinBudget(next.asking, Math.min(left(), NEXT_ROUTE_WAIT_MS));
+            if (overran() || next.ended || run.finished)
+                return undefined;
+        }
+        next.calls += 1;
+        /** A scenario that starts with this call's tool was compared, value for value, and missed. */
+        let compared = false;
+        /** One that starts with this call's tool was not armed in time: it misses this call only. */
+        let notReady = false;
+        /** Read the scenario's values once more, with the agent's call (O5); undefined when not ready in time. */
+        const readAgain = async (entry, old) => {
+            entry.rearmed = true;
+            dropNextState(old);
+            entry.state = undefined;
+            const toolInput = serializeCapped(redact(modelArgs), { maxPayloadBytes: 2048, maxStringBytes: 256 });
+            entry.arming = this.armNext(session, run, entry, { toolName, toolInput });
+            return (await this.withinBudget(entry.arming, left())) ?? undefined;
+        };
+        for (const entry of next.entries) {
+            if (entry.unhittable)
+                continue;
+            let state = entry.state;
+            if (!state) {
+                // Waited for only when the service named this call's tool as its first
+                // step; any other is compared only once it is armed.
+                if (entry.firstTool !== toolName)
+                    continue;
+                state = (await this.withinBudget(entry.arming, left())) ?? undefined;
+                if (overran() || next.ended)
+                    return undefined;
+                if (!state) {
+                    notReady = true;
+                    continue;
+                }
+            }
+            if (!state.plan || state.retired) {
+                // Declined at the decision for a value the request never names (an
+                // address a look-up returned): the agent's own call may hold it.
+                if (entry.rearmed || state.declined !== "missing_target" || entry.firstTool !== toolName)
+                    continue;
+                const again = await readAgain(entry, state);
+                if (overran() || next.ended)
+                    return undefined;
+                if (!again)
+                    notReady = true;
+                else if (again.plan && !again.retired && this.firstStepVerdict(again, toolName, modelArgs) === "hit") {
+                    return this.nextHit(session, run, entry, again, toolName);
+                }
+                else if (again.plan?.expectedTool() === toolName)
+                    compared = true;
+                continue;
+            }
+            if (state.plan.expectedTool() !== toolName)
+                continue;
+            // A first step inside a sub-task (a call row) is never the agent's call in place.
+            const first = state.plan.currentEntry();
+            if (!first || first.depth !== 0) {
+                entry.unhittable = true;
+                continue;
+            }
+            // Value for value (O5): the pin guard's "plausibly the step" is not
+            // enough here — the scenario would run its own values, and an e-mail to
+            // carlos must never become the recorded e-mail to olga.
+            const verdict = this.firstStepVerdict(state, toolName, modelArgs);
+            if (verdict === "hit")
+                return this.nextHit(session, run, entry, state, toolName);
+            // Only a value the plan lacks is read again, never one it read differently.
+            if (verdict === "missing" && !entry.rearmed) {
+                const again = await readAgain(entry, state);
+                if (overran() || next.ended)
+                    return undefined;
+                if (!again) {
+                    notReady = true;
+                    continue;
+                }
+                if (again.plan && !again.retired && this.firstStepVerdict(again, toolName, modelArgs) === "hit") {
+                    return this.nextHit(session, run, entry, again, toolName);
+                }
+            }
+            compared = true;
+        }
+        // No hit.
+        if (compared) {
+            // The agent took a way a scenario starts with, with other values: its
+            // own way, recorded, and a scenario of its own later (O7).
+            this.endNext(run, "other_values", toolName);
+        }
+        else if (callMayChange(toolName, modelArgs)) {
+            // Its first call that may change something and starts none of them: the
+            // agent is doing a way of its own (O7), and from here a scenario must
+            // never start in the middle of it.
+            this.endNext(run, notReady ? "not_ready" : "own_way", toolName);
+        }
+        else {
+            if (notReady) {
+                logDetail("replay.next_not_ready", {
+                    run: run.runId,
+                    tool: toolName,
+                    why: "a scenario that starts with this tool was not armed in time — it misses this call only",
+                });
+            }
+            // A look leaves them in place, for a while.
+            if (next.calls >= NEXT_CALLS_MAX)
+                this.endNext(run, "calls_limit", toolName);
+        }
+        return undefined;
+    }
+    /** A next scenario's hit: bookkeeping as for any plan armed mid-task, then its directive in the call's place. */
+    nextHit(session, run, entry, state, toolName) {
+        state.sessionId = session.sessionId;
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
+        // The request this plan serves, for a note at a decision of its own (SB-18).
+        state.request = run.input || undefined;
+        if (this.declineWithoutDeliveryTool(state)) {
+            state.reported = true;
+            this.endNext(run, "no_delivery_tool", toolName);
+            return undefined;
+        }
+        state.usageMark = markTranscriptUsage(session.transcriptPath);
+        state.markUsage = () => markTranscriptUsage(session.transcriptPath);
+        if (state.kind === "segment" && state.segment && state.scenarioId) {
+            for (const earlier of run.replays) {
+                if (earlier === state || !earlier.plan || earlier.kind !== "scenario")
+                    continue;
+                if (earlier.matchedRunId !== state.segment.runId)
+                    continue;
+                earlier.sharedWith.push(state.scenarioId);
+            }
+        }
+        run.replays.push(state);
+        run.replay = state;
+        run.intent.armed += 1;
+        // The agent's work from here is this scenario's, never recorded as the
+        // agent's own after the decision: a fragment still due is dropped, and
+        // one the agent's own looks opened ends with them.
+        this.closeDecisionFragment(session, run, state);
+        this.dropDecisionFragment(run, state);
+        this.endNext(run, "hit", toolName, state);
+        const directive = this.replay.directiveFor(state) ?? "";
+        logLine("replay.next_hit", {
+            run: run.runId,
+            scenario: state.scenarioId ?? undefined,
+            plan: entry.planId,
+            kind: state.kind,
+            mode: state.mode,
+            tool: toolName,
+            rearmed: entry.rearmed || undefined,
+            why: "the agent's call is the first step of a calculated scenario that follows the decision — it runs in the call's place",
+        });
+        return this.preToolAnswer(this.replay.deliverInstead(directive, toolName));
+    }
+    /**
+     * A next scenario hit after the agent's own calls — looks — opened the
+     * fragment of its work after the decision: the fragment ends here, with what
+     * the agent did itself, and nothing more of this turn is recorded into it.
+     * The scenario's own calls, pinned in steer mode or run in direct mode, are
+     * not the agent's work, and would make the fragment a copy of that scenario
+     * (offer1.md O7). A fragment still due is dropped instead
+     * ({@link dropDecisionFragment}).
+     */
+    closeDecisionFragment(session, run, by) {
+        const f = run.fragment;
+        if (!f || f.state !== "open" || !f.decision || !run.recording)
+            return;
+        const runId = run.runId;
+        const cost = this.costSince(session, f.usageMark);
+        const durationMs = f.startedAtMs ? Date.now() - f.startedAtMs : 0;
+        // Behind the fragment's own steps in the queue, as every finish is.
+        this.queue.push(() => {
+            this.recorder.finishRun(runId, undefined, {
+                durationMs,
+                costUsd: cost.measured ? cost.usd : undefined,
+            });
+        });
+        run.recording = false;
+        f.state = "closed";
+        logLine("run.fragment_closed", {
+            run: runId,
+            scenario: f.scenarioId,
+            step: f.stepIndex,
+            by: by.scenarioId ?? undefined,
+            why: "a scenario that follows the decision takes over after the agent's own first calls — the fragment ends with what the agent did itself",
+        });
+    }
+    /**
+     * End this turn's next scenarios (offer1.md O6): every one but the hit is
+     * never announced, so never runs and is never reported.
+     */
+    endNext(run, why, toolName, kept) {
+        const next = run.next;
+        if (!next || next.ended)
+            return;
+        next.ended = why;
+        for (const e of next.entries)
+            dropNextEntry(e, kept);
+        if (why !== "hit" && next.entries.length > 0) {
+            logLine("replay.next_miss", {
+                run: run.runId,
+                reason: why,
+                tool: toolName,
+                calls: next.calls,
+                scenarios: next.entries.map((e) => e.match.scenarioId).join(","),
+                why: NEXT_MISS_WHY[why] ?? "none of the scenarios that follow the decision was used",
+            });
+        }
+        next.entries = [];
+    }
     /**
      * Whether an intent probe may arm a plan in its own `PreToolUse` — and so
      * whether that hook waits for it. See {@link ControlServerOptions.intentArm}.
@@ -4699,7 +5335,35 @@ export class ControlServer {
         const h = state?.handover;
         if (!h || !state?.scenarioId)
             return;
-        run.fragment = { scenarioId: state.scenarioId, stepIndex: h.stepIndex, state: "due" };
+        run.fragment = {
+            scenarioId: state.scenarioId,
+            stepIndex: h.stepIndex,
+            state: "due",
+            ...(h.kind === "decision" ? { decision: true } : {}),
+        };
+    }
+    /**
+     * Drop a fragment scheduled at a decision (the service's
+     * segmentsbreakdown.md SB-16) when a plan the intent check armed takes the
+     * agent's next call: what follows is that plan's half, not the other one,
+     * and recorded as the other half it would become a wrong segment C. Cleared
+     * rather than ended, so a later hand-over of that plan schedules its own
+     * fragment, as any plan's does in a turn with none. Any other fragment is
+     * left as it is.
+     */
+    dropDecisionFragment(run, by) {
+        const f = run.fragment;
+        if (!f || f.state !== "due" || !f.decision)
+            return;
+        run.fragment = undefined;
+        logLine("run.fragment_dropped", {
+            run: run.runId,
+            scenario: f.scenarioId,
+            step: f.stepIndex,
+            by: by?.scenarioId ?? undefined,
+            kind: by?.kind,
+            why: "a plan the intent check armed takes the agent's next step after the decision — that work is not the other half",
+        });
     }
     /**
      * Open the fragment run and record from this call on (fallbk.md D7).
@@ -4719,9 +5383,21 @@ export class ControlServer {
             return;
         const input = reasoning.trim() || `${toolName} ${serializeCapped(redact(args))}`.slice(0, 2_000);
         const fallbackOf = { scenarioId: f.scenarioId, stepIndex: f.stepIndex };
+        // The agent's own call after a plan's decision (SB-16): this runner's word
+        // that the work that follows is the agent's choice, not a plan's half.
+        // The service reads it beside its own mark of the fragment (the
+        // service's segmentsbreakdown.md D14).
+        // With the turn's own request (offer1.md O2): the service calculates what
+        // the agent does here with it, so the values the request names are read
+        // from the next request instead of being fixed. Redacted and cut, as the
+        // prompt itself is wherever it leaves this machine.
+        const request = run.input ? redactText(run.input).slice(0, DECISION_REQUEST_MAX) : "";
+        const decisionOf = f.decision
+            ? { scenarioId: f.scenarioId, stepIndex: f.stepIndex, ...(request ? { request } : {}) }
+            : undefined;
         // The fragment is a run of the same host as the turn it continues.
         const framework = frameworkOf(session);
-        const id = this.recorder.startRun(input, { ...this.runMetadata(session), fallbackOf }, framework ? { fallbackOf, framework } : { fallbackOf });
+        const id = this.recorder.startRun(input, { ...this.runMetadata(session), fallbackOf, ...(decisionOf ? { decisionOf } : {}) }, framework ? { fallbackOf, framework } : { fallbackOf });
         for (const c of run.correlations.values()) {
             c.settled = true;
             if (c.fallback)
@@ -4738,6 +5414,7 @@ export class ControlServer {
             run: id,
             scenario: f.scenarioId,
             step: f.stepIndex,
+            decision: f.decision || undefined,
             why: "recording the agent's own work after the scenario handed over",
         });
         if (!isRunCreationAware(this.recorder))
@@ -4977,12 +5654,17 @@ export class ControlServer {
         const stashed = this.claimStashedNote(payload.session_id);
         if (stashed)
             context.push(stashed);
-        const run = this.sessions.get(payload.session_id ?? "unknown-session")?.run;
+        const postSession = this.sessions.get(payload.session_id ?? "unknown-session");
+        const run = postSession?.run;
         if (run && !run.finished) {
             // The answer, if one comes, is written after this call (AC11).
             if (typeof payload.tool_use_id === "string" && payload.tool_use_id)
                 run.lastToolUseId = payload.tool_use_id;
             this.noteHandover(run);
+            // A plan that stopped at its decision on this call: what can follow it is
+            // asked for now, while the agent reads the note and decides (offer1.md O4).
+            if (postSession)
+                this.noteDecision(postSession, run);
             const note = this.replay.takeNote(run.replay);
             if (note)
                 context.push(note);
@@ -5547,6 +6229,11 @@ export class ControlServer {
             const result = await this.replay.runArmed(state, signal);
             if (signal?.aborted)
                 this.stashCancelledNote(call.sessionId, state);
+            // A direct plan that stopped at its decision: what can follow it is asked
+            // for at once, before the agent has even read the results (offer1.md O4).
+            const runSession = this.sessions.get(call.sessionId);
+            if (runSession && runSession.run === call.run && !signal?.aborted)
+                this.noteDecision(runSession, call.run);
             return result;
         }
         finally {