@basein/runner 0.3.18 → 0.3.20

package/dist/replay/controller.js

@@ -288,9 +288,11 @@ export class ReplayController {
     /**
      * Whether a handed-out segment may actually arm (segmented.md R-OUT-10).
      *
-     * Off by default: until an operator has read the observe-only logs and turned
-     * `BIR_SEGMENT_ARM=1` on, the runner asks for no segment and arms none. The
-     * server enforces the same thing from its side (R-OUT-9).
+     * Only when the option says so. The recorder passes it on unless
+     * `BIR_SEGMENT_ARM=0` (from 0.3.19; the service's segmentsbreakdown.md
+     * SB-21); a controller built without it stays observe-only, asks for no
+     * segment and arms none. The server enforces the same thing from its side
+     * (R-OUT-9).
      */
     get segmentArm() {
         return this.opts.segmentArm === true;
@@ -389,6 +391,10 @@ export class ReplayController {
      */
     async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}, host) {
         const state = this.blankState(match, wrapped, armedBy, host);
+        // A decision note quotes the request (SB-18); a plan armed by intent was
+        // given the step's intent here, and its control server sets the request.
+        if (armedBy === "prompt")
+            state.request = prompt;
         const isSegment = state.kind === "segment";
         const decline = (why, code) => {
             state.declined = code;
@@ -480,12 +486,18 @@ export class ReplayController {
             const unusable = flat.stopAt === 0 && flat.stopReason ? flat.stopReason : undefined;
             // The step that stops the plan, before the clamp: the reason is its own.
             const stopping = entries[Math.min(...rawStop)]?.step ?? entries[0].step;
-            const judgement = stopping.stop?.kind === "nondeterministic";
+            // The service never serves a decision at step 0 (segmentsbreakdown.md
+            // SB-5): should one come, the agent decides from the start, as it makes
+            // a judgement there. No new code reaches a service that may not know it.
+            const decisionFirst = stopping.stop?.kind === "decision";
+            const judgement = stopping.stop?.kind === "nondeterministic" || decisionFirst;
             const why = unusable
                 ? `its first step is a call that cannot run: ${unusable.reason}`
-                : judgement
-                    ? "its first step needs a judgement the plan cannot compute — the agent does this task"
-                    : `its first step has failed ${stopping.failureCount ?? 0} times — the agent does this task`;
+                : decisionFirst
+                    ? "its first step is a decision the agent makes — the agent does this task"
+                    : judgement
+                        ? "its first step needs a judgement the plan cannot compute — the agent does this task"
+                        : `its first step has failed ${stopping.failureCount ?? 0} times — the agent does this task`;
             return decline(why, unusable
                 ? "unusable_first_step"
                 : judgement
@@ -526,7 +538,7 @@ export class ReplayController {
         // command nobody asked for.
         let deriveCtx = ctx;
         if (ctx.recentResults?.length && sinkOfPlan(planned, host?.sinks) === "command") {
-            deriveCtx = { liveCall: ctx.liveCall, agentDay: ctx.agentDay };
+            deriveCtx = { liveCall: ctx.liveCall, agentDay: ctx.agentDay, atDecision: ctx.atDecision };
             logLine("replay.derive_context", {
                 scenario: scenario.id,
                 shell: hasShellStep(planned, host?.sinks) || undefined,
@@ -747,6 +759,15 @@ export class ReplayController {
             ...(plan.stopsEarly() ? { stopAt: plan.stepCount } : {}),
         };
     }
+    /**
+     * Whether the plan's steps end in front of a decision (the service's
+     * segmentsbreakdown.md SB-6): it runs the steps before it, then hands the
+     * task back there. The control server gives such a plan a usage mark, so
+     * that it is billed only up to the stop (SB-26).
+     */
+    stopsAtDecision(state) {
+        return state.plan?.stopEntry()?.step.stop?.kind === "decision";
+    }
     /**
      * Take back a plan that armed and has run nothing, as a decline.
      *
@@ -2002,16 +2023,20 @@ export class ReplayController {
         const total = state.deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
         const steps = this.stepResultsOf(state);
         const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
+        // The plan handed the task back by design, not by a fault: in front of the
+        // other half of an "if … otherwise" (AC5), or at its decision (the
+        // service's segmentsbreakdown.md SB-19). Such a stop is named whatever the
+        // outcome, and the agent's work after it is the service's evidence.
+        const handedBack = state.handover?.kind === "other_branch" || state.handover?.kind === "decision";
         // A costless decline is noise on both sides — *unless* it says something the
         // recording page cannot learn any other way: a step that actually broke, the
-        // gate that declined, or a plan that stood in front of the other half of
-        // its task (AC5), which the service takes the agent's work after as its
-        // evidence of that half. The service accepts a costless report that carries
-        // any of them (its errorshandling.md).
+        // gate that declined, or a plan that handed the task back by design. The
+        // service accepts a costless report that carries any of them (its
+        // errorshandling.md).
         if (isBaseline &&
             total <= 0 &&
             !state.declined &&
-            state.handover?.kind !== "other_branch" &&
+            !handedBack &&
             !steps?.some((s) => s.status === "failed")) {
             return undefined;
         }
@@ -2052,14 +2077,15 @@ export class ReplayController {
             declined: state.declined,
             // Where the plan handed the task to the model (fallbk.md). Only on
             // `fell_back`: a hand-over before any step ran is `failed`, and a parked
-            // step found after a divergence is still a divergence. Except the other
-            // half of an "if … otherwise" (AC5), named whatever the outcome: the
-            // agent's work after it is the service's evidence of that half, whether
+            // step found after a divergence is still a divergence. Except a plan
+            // that handed the task back by design — the other half of an "if …
+            // otherwise" (AC5), or its decision (SB-19) — named whatever the
+            // outcome: the agent's work after it is the service's evidence, whether
             // or not a step ran first.
-            fallbackStepIndex: state.outcome === "fell_back" || state.handover?.kind === "other_branch"
+            fallbackStepIndex: state.outcome === "fell_back" || handedBack
                 ? state.handover?.stepIndex
                 : undefined,
-            fallbackKind: state.outcome === "fell_back" || state.handover?.kind === "other_branch"
+            fallbackKind: state.outcome === "fell_back" || handedBack
                 ? state.handover?.kind
                 : undefined,
             // The agent did not take the plan's result and redid the task (AC1).
@@ -2110,6 +2136,10 @@ export class ReplayController {
      * there is nothing to be similar *to* and nothing to decline. It books no
      * execution either — there is no ticket, and inventing a saving for a manual
      * invocation is exactly the kind of number a ledger must never contain.
+     *
+     * One served stop is kept: a plan's decision (the service's
+     * segmentsbreakdown.md SB-6). The run stops in front of it, and `stopped`
+     * says so with the reason `decision`.
      */
     async runAdHoc(scenario, prompt, wrapped) {
         if (!isReadyScenario(scenario))
@@ -2174,16 +2204,25 @@ export class ReplayController {
             }
             return out;
         });
+        // The one served stop an operator's run keeps: a decision (the service's
+        // segmentsbreakdown.md SB-6). The steps after it are one half of an "if …
+        // otherwise", the half the recording took, and running them by id would
+        // do that half's writes whatever the request. Every other served stop is
+        // the plan's health, which an operator's run is there to try.
+        const decisionAt = flat.entries.findIndex((e) => e.step.stop?.kind === "decision");
+        const stopAt = decisionAt >= 0 && (flat.stopAt === undefined || decisionAt < flat.stopAt)
+            ? clampToFrameStart(flat.entries, decisionAt)
+            : flat.stopAt;
         const plan = new ScenarioReplayPlan({
             scenario,
             params,
             mode,
             entries: flat.entries,
-            stopAt: flat.stopAt,
+            stopAt,
             fallbackTargets: "samples",
         });
         state.plan = plan;
-        state.flatStop = flat.stopReason;
+        state.flatStop = stopAt === flat.stopAt ? flat.stopReason : undefined;
         if (this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
@@ -2230,6 +2269,15 @@ export class ReplayController {
             }
             const stop = result.stopped;
             const stoppedStep = stop ? plan.allSteps()[stop.flatIndex ?? plan.stepCount] : undefined;
+            // The plan's end in front of its decision: said so, by its own word.
+            const atDecision = stop?.kind === "known_bad_step" && stoppedStep?.stop?.kind === "decision";
+            if (atDecision) {
+                logLine("replay.adhoc_decision", {
+                    scenario: scenario.id,
+                    step: stop.stepIndex,
+                    why: "bir replay stops in front of the plan's decision: the steps after it are the half the recording took",
+                });
+            }
             return {
                 ok: true,
                 text: result.text,
@@ -2241,7 +2289,7 @@ export class ReplayController {
                     ? {
                         step: stop.stepIndex,
                         tool: stoppedStep?.toolName ?? "",
-                        reason: stop.reason ?? stop.stage ?? stop.kind,
+                        reason: atDecision ? "decision" : (stop.reason ?? stop.stage ?? stop.kind),
                         error: stop.error,
                     }
                     : undefined,
@@ -2304,6 +2352,8 @@ export class ReplayController {
             fetchImpl: this.opts.fetchImpl,
             liveCall: ctx.liveCall,
             recentResults: ctx.recentResults,
+            // A reading for a scenario that follows a plan's decision (offer1.md O4).
+            ...(ctx.atDecision ? { atDecision: ctx.atDecision } : {}),
             // The request itself ends too. Without this a hung service or model held
             // the socket for up to 300 s after every wait on it had given up. Long
             // enough to cover both waits that can use its answer (the arm and the
@@ -2436,7 +2486,16 @@ export class ReplayController {
         // when a step did its work — so the service takes the agent's work after
         // it as that half's evidence. Booked `diverged`, it never did.
         const otherHalf = stop?.kind === "other_branch";
-        this.upgrade(state, broke || !didWork ? "failed" : otherHalf ? "fell_back" : "diverged");
+        // A bundle that ran up to the plan's decision and stopped there (the
+        // service's segmentsbreakdown.md SB-17) is a hand-over too: the plan did
+        // all it was for, and the agent decides. Not one of recorded outputs
+        // only, which is no step done here — that stays a plain divergence.
+        const atDecision = !stop &&
+            plan.stopsEarly() &&
+            composed.endedAt === plan.stepCount &&
+            (composed.executed > 0 || composed.recorded === 0) &&
+            this.stopKindOf(state, plan.stopEntry()) === "decision";
+        this.upgrade(state, broke || !didWork ? "failed" : otherHalf || atDecision ? "fell_back" : "diverged");
         state.stepsPinned += composed.executed;
         // The headline number of this whole design: recovering from a divergence
         // costs nothing, because the proxies were already connected.
@@ -2473,6 +2532,30 @@ export class ReplayController {
                 const note = this.stopNote(state, plan, stop, "none", composed.left);
                 return this.deliverInstead(note, toolName, state.host !== undefined);
             }
+            // Every step left before the decision was one this request does not
+            // need: the plan has done its part, and the agent decides. Told in
+            // place of its call, like the other half. The steps that ran are the
+            // model's own calls above; the ones left out are named.
+            if (atDecision) {
+                const parked = plan.stopStep();
+                state.handover = {
+                    kind: "decision",
+                    stepIndex: callerStepIndexOf(plan.stopEntry()) ?? parked.stepIndex,
+                    toolName: parked.toolName ?? undefined,
+                    note: this.noteFor(state, {
+                        kind: "decision",
+                        step: parked,
+                        entry: plan.stopEntry(),
+                        position: plan.stepCount,
+                        delivery: "above",
+                        executedAbove: plan.currentStepIndex,
+                        leftOut: composed.left,
+                    }),
+                    delivered: true,
+                };
+                this.decidedInDivergence(state, plan);
+                return this.deliverInstead(state.handover.note, toolName, state.host !== undefined);
+            }
             // Every remaining step was left out by its test: the steps the session
             // ran were the whole of the plan this request needs, and it ran to its
             // end (newestRun.md N7 reads that).
@@ -2511,6 +2594,8 @@ export class ReplayController {
                 delivered: true,
             };
             text = `${state.handover.note}\n\n${composed.text}`;
+            if (atDecision)
+                this.decidedInDivergence(state, plan);
         }
         else if (!stop) {
             // The bundle carries the rest of the chain, and its header tells the
@@ -2578,6 +2663,12 @@ export class ReplayController {
             return;
         const ran = state.stepsPinned;
         this.retire(state, ran > 0 ? "fell_back" : "failed");
+        // A plan stopped at its decision did all it was for: its bill ends here,
+        // and the agent's decision and the half it takes are the agent's own
+        // (the service's segmentsbreakdown.md SB-26). Only once a step ran: a
+        // plan that did nothing is a baseline sample of the whole turn.
+        if (h.kind === "decision" && ran > 0)
+            this.markRetired(state);
         state.handover = {
             kind: h.kind,
             // The *caller's* index: a fragment opens at the call row, not at a step
@@ -2604,21 +2695,23 @@ export class ReplayController {
                 ? h.noneNeeded
                     ? "no step of the plan was needed for this request — the agent does the task"
                     : `this request is the other half: the steps from here are only for when ${h.whenText ?? "their test says so"} — the agent continues`
-                : h.kind === "unusable_call"
-                    ? "a sub-task of this chain cannot run — the agent does that part itself"
-                    : h.kind === "known_bad_step"
-                        ? "the next step has failed too often — the agent continues from here"
-                        : h.kind === "nondeterministic_step"
-                            ? "the next step needs a judgement the plan cannot compute — the agent makes it"
-                            : h.stopReason === "concurrent"
-                                ? "a second call arrived while the pinned step was still running — the agent continues from here"
-                                : h.stopReason === "budget" || h.stopReason === "cancelled"
-                                    ? "the run was cut short before this step — the agent continues from here"
-                                    : h.stopReason === "host_rejected" || h.stopReason === "host_edited"
-                                        ? "the host stopped this step itself — no fault of the plan; the agent continues from here"
-                                        : h.stopReason === "not_run" || h.stopReason === "uncertain"
-                                            ? "a step produced no result here — the agent continues from here"
-                                            : "a step broke — the agent continues from here",
+                : h.kind === "decision"
+                    ? "the plan ran the steps before its decision — the agent decides which way applies and continues"
+                    : h.kind === "unusable_call"
+                        ? "a sub-task of this chain cannot run — the agent does that part itself"
+                        : h.kind === "known_bad_step"
+                            ? "the next step has failed too often — the agent continues from here"
+                            : h.kind === "nondeterministic_step"
+                                ? "the next step needs a judgement the plan cannot compute — the agent makes it"
+                                : h.stopReason === "concurrent"
+                                    ? "a second call arrived while the pinned step was still running — the agent continues from here"
+                                    : h.stopReason === "budget" || h.stopReason === "cancelled"
+                                        ? "the run was cut short before this step — the agent continues from here"
+                                        : h.stopReason === "host_rejected" || h.stopReason === "host_edited"
+                                            ? "the host stopped this step itself — no fault of the plan; the agent continues from here"
+                                            : h.stopReason === "not_run" || h.stopReason === "uncertain"
+                                                ? "a step produced no result here — the agent continues from here"
+                                                : "a step broke — the agent continues from here",
         });
     }
     /**
@@ -2628,10 +2721,32 @@ export class ReplayController {
      * step.
      */
     stopKindOf(state, entry) {
+        // The service serves a decision ahead of any other stop of its step
+        // (the service's segmentsbreakdown.md SB-6), and so it is read first.
+        if (entry?.step.stop?.kind === "decision")
+            return "decision";
         if (entry?.step.stop?.kind === "nondeterministic")
             return "nondeterministic_step";
         return state.flatStop ? "unusable_call" : "known_bad_step";
     }
+    /**
+     * A divergence's bundle that ended at the plan's decision (SB-17): logged
+     * as `handOver` logs every other hand-over, and its usage mark taken there
+     * when a step of the plan ran (SB-26).
+     */
+    decidedInDivergence(state, plan) {
+        if (state.stepsPinned > 0)
+            this.markRetired(state);
+        logLine("replay.handover", {
+            scenario: state.scenarioId ?? undefined,
+            kind: "decision",
+            step: `${plan.stepCount}/${plan.totalSteps}`,
+            via: "divergence",
+            ran: state.stepsPinned,
+            outcome: state.outcome,
+            why: "the plan ran the steps before its decision — the agent decides which way applies and continues",
+        });
+    }
     /**
      * The steps before flat position `bound` that ran, 1-based, and the ones
      * their tests left out (AC5) — the plan cursor's own, and a divergence
@@ -2672,15 +2787,21 @@ export class ReplayController {
             h.stopReason === "host_rejected" ||
             h.stopReason === "host_edited" ||
             h.stopReason === "result_map";
+        // A chain that holds a decision (the service's segmentsbreakdown.md SB-18)
+        // keeps the decision note's protections in every note, even when the plan
+        // stops earlier for another reason: no intent, no parameters, and no step
+        // from the decision on. Each points at the half the recording took, and an
+        // agent that follows it there runs that half's segment: the plan decided.
+        const decisionAt = plan ? plan.decisionIndex() : -1;
         let params;
         try {
-            params = plan?.parameters;
+            params = decisionAt >= 0 ? undefined : plan?.parameters;
         }
         catch {
             params = undefined;
         }
         return buildHandoverNote({
-            intent: plan?.intent ?? "",
+            intent: decisionAt >= 0 ? "" : (plan?.intent ?? ""),
             kind: h.kind,
             stepIndex: h.position,
             stepToolName: h.step?.toolName ?? undefined,
@@ -2715,13 +2836,17 @@ export class ReplayController {
             totalSteps: plan?.totalSteps ?? state.stepsPlanned,
             // A step that runs only under a test is marked so: the list must not
             // read as steps this request needs (AC5).
-            remainingTools: plan ? plan.remainingFrom(handled ? h.position + 1 : h.position) : [],
+            remainingTools: plan
+                ? plan.remainingFrom(handled ? h.position + 1 : h.position, decisionAt >= 0 ? decisionAt : undefined)
+                : [],
             params,
             delivery: h.delivery,
             whenText: h.whenText ?? null,
             subTask: h.subTask ?? null,
             // "None was needed" is the note's own wording for the end of the plan.
             ...(h.noneNeeded ? { stepIndex: plan?.totalSteps ?? state.stepsPlanned } : {}),
+            // The request's own words for the choice (SB-18); never the service's.
+            ...(h.kind === "decision" ? { request: state.request ?? null } : {}),
         });
     }
     /**
@@ -3228,17 +3353,10 @@ export class ReplayController {
             this.upgrade(state, outcome);
         // Only a plan that *finished* stops the clock (segmented.md R-MONEY-3). A
         // hand-over or a divergence takes no mark: the agent's next tokens are the
-        // consequence of this plan stopping, and belong to its bill.
-        if (completing) {
-            state.retiredAt = Date.now();
-            try {
-                state.retiredMark = state.markUsage?.();
-            }
-            catch {
-                // An unreadable transcript leaves the mark undefined, and the window
-                // falls back to the next arm or the end of the turn.
-            }
-        }
+        // consequence of this plan stopping, and belong to its bill. (A decision
+        // hand-over takes one of its own: `markRetired`.)
+        if (completing)
+            this.markRetired(state);
         state.retired = true;
         state.pinned.clear();
         // A note naming a step to call next is void once the plan is: after a
@@ -3250,6 +3368,21 @@ export class ReplayController {
         // A call waiting for a pin to thread has nothing left to wait for.
         this.notifyPins(state);
     }
+    /**
+     * Where the plan's work ended, for its bill: now, and the transcript's
+     * watermark now. Taken at a completing retire, and at a decision hand-over
+     * after a step ran (the service's segmentsbreakdown.md SB-26).
+     */
+    markRetired(state) {
+        state.retiredAt = Date.now();
+        try {
+            state.retiredMark = state.markUsage?.();
+        }
+        catch {
+            // An unreadable transcript leaves the mark undefined, and the window
+            // falls back to the next arm or the end of the turn.
+        }
+    }
 }
 /** Every target of a schema. A parameter with no kind is one (R-PARAM-3). */
 function targetKeys(schema) {

package/dist/replay/derive.d.ts

@@ -53,6 +53,16 @@ export interface DeriveContext {
      * into the session only after the prompt hook (issue 1212).
      */
     agentDay?: () => AgentDay | undefined;
+    /**
+     * A reading for a scenario that can follow a plan's decision, made while the
+     * agent decides (the service's offer1.md O4): the plan, and its decision
+     * step. With it the service reads this turn's results without a live call,
+     * and the prompt as the user's request. Only the service reads it.
+     */
+    atDecision?: {
+        scenarioId: string;
+        stepIndex: number;
+    };
 }
 /**
  * The service, which derives when this runner has no key of its own

package/dist/replay/derive.js

@@ -347,6 +347,9 @@ async function deriveViaService(opts, service, schema, keys) {
                 // 2023-11-30 …"), which the service turns into the day it reads from
                 // (issue 1212). Older services ignore it.
                 ...(opts.todaySaid ? { todaySaid: opts.todaySaid } : {}),
+                // A reading made at a plan's decision (offer1.md O4): the service then
+                // takes this turn's results with no live call. Older services ignore it.
+                ...(opts.atDecision ? { atDecision: opts.atDecision } : {}),
             }),
             signal: opts.signal ?? timeoutSignal(),
         });

package/dist/replay/handover.d.ts

@@ -156,6 +156,13 @@ export interface HandoverNoteInput {
      * from there on are for, which this request is not (autocorrect.md AC5).
      */
     whenText?: string | null;
+    /**
+     * For `decision`: the live request the plan serves, the user's own words.
+     * Its sentences with a condition word are quoted, so the agent sees the
+     * choice that is its to make (the service's segmentsbreakdown.md SB-18).
+     * Read for no other kind.
+     */
+    request?: string | null;
 }
 export declare function buildHandoverNote(n: HandoverNoteInput): string;
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */

package/dist/replay/handover.js

@@ -11,6 +11,7 @@
  * and a tool's own payload is already in front of it where it ran.
  */
 import { truncate } from "./bundle.js";
+import { conditionSentences } from "./condition-words.js";
 /** Hard ceiling on a note. Long enough to carry derived params, short enough to read. */
 export const MAX_HANDOVER_NOTE = 4_000;
 const MAX_ERROR_CHARS = 500;
@@ -26,6 +27,8 @@ const UNUSABLE_LINE = {
     unsupported: "this runner cannot run",
 };
 export function buildHandoverNote(n) {
+    if (n.kind === "decision")
+        return decisionNote(n);
     const intent = n.intent.length > 240 ? `${n.intent.slice(0, 240)}…` : n.intent;
     const human = n.stepIndex + 1;
     const tool = n.stepToolName ? ` (${n.stepToolName})` : "";
@@ -35,6 +38,91 @@ export function buildHandoverNote(n) {
     ];
     if (intent)
         lines.push(`Intent: ${intent}`);
+    lines.push(...ranLines(n));
+    if (n.kind === "unusable_call") {
+        // A call is a stretch of work, not a tool: the agent is told what the
+        // sub-task was, not which tool did not run.
+        const what = n.unusable?.callIntent ? ` ("${truncate(n.unusable.callIntent, 200)}")` : "";
+        const why = UNUSABLE_LINE[n.unusable?.reason ?? ""] ?? "that cannot run here";
+        lines.push(`Step ${human} of ${n.totalSteps} is a sub-task${what} ${why}.`);
+    }
+    else if (n.kind === "known_bad_step") {
+        const times = n.failureCount ? ` ${n.failureCount} times` : "";
+        // A parked step inside a called segment names the scenario that owns it:
+        // that is where the repair happens, and the agent's own step numbering has
+        // no row for it (R-CALL-30).
+        const owner = n.inSubTask
+            ? `, in sub-task "${truncate(n.inSubTask, 120)}"${n.ownerScenarioId ? `, scenario ${n.ownerScenarioId}` : ""}`
+            : "";
+        lines.push(`Step ${human} of ${n.totalSteps}${tool.replace(/\)$/, `${owner})`)} did not run: it has failed${times} before, so the scenario stops in front of it.`);
+    }
+    else if (n.kind === "nondeterministic_step") {
+        // The calculation could not write code for this step's input: it is a
+        // judgement, and the agent is the one to make it (plan-services.md D8).
+        lines.push(`Step ${human} of ${n.totalSteps}${tool} did not run: its input needs a judgement the scenario cannot compute. Make that choice yourself and carry on.`);
+    }
+    else if (n.kind === "other_branch") {
+        // The plan holds one half of an "if … otherwise" and this request is the
+        // other (autocorrect.md AC5). The steps from here are not wrong, they are
+        // not this request's: the model is told what they are for, never to run
+        // them, and the list of their tools is left out below for that reason.
+        const why = n.whenText ? `they are only for when ${n.whenText}, and that is not so for this request` : "this request is the other case of the task, which they are not for";
+        lines.push(n.stepIndex >= n.totalSteps
+            ? "None of the scenario's steps was needed for this request. Do the task as this request needs it."
+            : `Step ${human} of ${n.totalSteps}${tool} and the steps after it did not run: ${why}. Do the rest of the task yourself, as this request needs it.`);
+    }
+    else {
+        lines.push(stepFailedLine(n, human, tool));
+    }
+    // Not for the other half: those tools are the ones this request must not
+    // run, and naming them invites exactly that.
+    if (n.remainingTools.length > 0 && n.kind !== "other_branch") {
+        lines.push(`The remaining planned steps were: ${n.remainingTools.join(", ")}.`);
+    }
+    if (n.params && Object.keys(n.params).length > 0) {
+        let json;
+        try {
+            json = JSON.stringify(n.params);
+        }
+        catch {
+            json = "[unserializable]";
+        }
+        lines.push(`Parameters derived for this request: ${truncate(json, MAX_PARAMS_CHARS)}`);
+    }
+    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+}
+/**
+ * The note of a plan stopped at its decision (the service's
+ * segmentsbreakdown.md SB-18): what ran, and the request's own words for the
+ * choice the agent now makes. Nothing that names the recorded half: no
+ * intent, no remaining steps, no parameters, and never the condition the
+ * service keeps (`stop.why`). Each would hint which way the recording went.
+ */
+function decisionNote(n) {
+    // Where the results of the steps that ran are, as the ran-steps line says.
+    const above = Math.max(0, Math.min(n.executedAbove ?? 0, n.executed));
+    const delivery = above >= n.executed ? "above" : n.delivery;
+    const from = n.executed === 0
+        ? ""
+        : delivery === "above"
+            ? " from the results above"
+            : delivery === "below"
+                ? above > 0
+                    ? " from the results above and below"
+                    : " from the results below"
+                : "";
+    const quote = conditionSentences(n.request);
+    const ask = quote ? `This request asks for a decision: “${quote}”.` : "This task has a decision to make here.";
+    const lines = [
+        "[BaseInstRunner calculated replay] The calculated scenario for this request ran the steps before a decision, and stopped there.",
+        ...ranLines(n),
+        `${ask} Decide${from} which way applies, then continue the task, calling tools as needed.`,
+    ];
+    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+}
+/** What ran before the stop, and what of it the model may assume: the lines every note carries. */
+function ranLines(n) {
+    const lines = [];
     // Steps left out by their tests sit among those before the stop (AC5): the
     // ones that ran are then named, never "steps 1–N", which would say a step
     // ran that did not.
@@ -100,57 +188,7 @@ export function buildHandoverNote(n) {
         lines.push(`Step ${n.inFlight.stepIndex + 1} of ${n.totalSteps}${inTool} was started and has not reported back: ` +
             "it may not have run, or may still complete. Check whether its work happened before you repeat it.");
     }
-    if (n.kind === "unusable_call") {
-        // A call is a stretch of work, not a tool: the agent is told what the
-        // sub-task was, not which tool did not run.
-        const what = n.unusable?.callIntent ? ` ("${truncate(n.unusable.callIntent, 200)}")` : "";
-        const why = UNUSABLE_LINE[n.unusable?.reason ?? ""] ?? "that cannot run here";
-        lines.push(`Step ${human} of ${n.totalSteps} is a sub-task${what} ${why}.`);
-    }
-    else if (n.kind === "known_bad_step") {
-        const times = n.failureCount ? ` ${n.failureCount} times` : "";
-        // A parked step inside a called segment names the scenario that owns it:
-        // that is where the repair happens, and the agent's own step numbering has
-        // no row for it (R-CALL-30).
-        const owner = n.inSubTask
-            ? `, in sub-task "${truncate(n.inSubTask, 120)}"${n.ownerScenarioId ? `, scenario ${n.ownerScenarioId}` : ""}`
-            : "";
-        lines.push(`Step ${human} of ${n.totalSteps}${tool.replace(/\)$/, `${owner})`)} did not run: it has failed${times} before, so the scenario stops in front of it.`);
-    }
-    else if (n.kind === "nondeterministic_step") {
-        // The calculation could not write code for this step's input: it is a
-        // judgement, and the agent is the one to make it (plan-services.md D8).
-        lines.push(`Step ${human} of ${n.totalSteps}${tool} did not run: its input needs a judgement the scenario cannot compute. Make that choice yourself and carry on.`);
-    }
-    else if (n.kind === "other_branch") {
-        // The plan holds one half of an "if … otherwise" and this request is the
-        // other (autocorrect.md AC5). The steps from here are not wrong, they are
-        // not this request's: the model is told what they are for, never to run
-        // them, and the list of their tools is left out below for that reason.
-        const why = n.whenText ? `they are only for when ${n.whenText}, and that is not so for this request` : "this request is the other case of the task, which they are not for";
-        lines.push(n.stepIndex >= n.totalSteps
-            ? "None of the scenario's steps was needed for this request. Do the task as this request needs it."
-            : `Step ${human} of ${n.totalSteps}${tool} and the steps after it did not run: ${why}. Do the rest of the task yourself, as this request needs it.`);
-    }
-    else {
-        lines.push(stepFailedLine(n, human, tool));
-    }
-    // Not for the other half: those tools are the ones this request must not
-    // run, and naming them invites exactly that.
-    if (n.remainingTools.length > 0 && n.kind !== "other_branch") {
-        lines.push(`The remaining planned steps were: ${n.remainingTools.join(", ")}.`);
-    }
-    if (n.params && Object.keys(n.params).length > 0) {
-        let json;
-        try {
-            json = JSON.stringify(n.params);
-        }
-        catch {
-            json = "[unserializable]";
-        }
-        lines.push(`Parameters derived for this request: ${truncate(json, MAX_PARAMS_CHARS)}`);
-    }
-    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+    return lines;
 }
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */
 export function stepsPhrase(numbers) {