@basein/runner 0.3.19 → 0.3.21

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. */
@@ -949,6 +1064,17 @@ export class ControlServer {
             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,
@@ -2086,8 +2212,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (replay/builtins.ts). The
+        // session's own cwd from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         // The service offered to record this turn as the recording's newest run:
         // should the agent redo the task after the plan, the plan's own calls go
@@ -2246,8 +2372,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (replay/builtins.ts). The
+        // session's own cwd from the hook payloads, never the daemon's.
         state.sessionCwd = session.cwd ?? this.opts.cwd;
         run.replay = state;
         run.replays.push(state);
@@ -2824,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;
@@ -3638,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
@@ -3700,27 +3830,38 @@ 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) {
                     // The plan answers in this call's place: the agent's work from here
@@ -3741,7 +3882,7 @@ 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
@@ -4574,8 +4715,8 @@ export class ControlServer {
         }
         state.sessionId = session.sessionId;
         // The project directory an allow-listed built-in step executes in, and
-        // the jail it may not leave (replay/builtins.ts). The session's own cwd
-        // from the hook payloads, never the daemon's.
+        // what its relative paths resolve against (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.
@@ -4587,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).
@@ -4609,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,
@@ -4662,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}.
@@ -4797,7 +5387,14 @@ export class ControlServer {
         // 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).
-        const decisionOf = f.decision ? { scenarioId: f.scenarioId, stepIndex: f.stepIndex } : undefined;
+        // 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, ...(decisionOf ? { decisionOf } : {}) }, framework ? { fallbackOf, framework } : { fallbackOf });
@@ -5057,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);
@@ -5627,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 {