@basein/runner 0.3.18 → 0.3.19

package/dist/record/recorder.d.ts

@@ -335,13 +335,21 @@ export interface IntentMatchRequest {
     stepPosition?: number;
     /** Recordings this turn must not count hits against (R-HIT-7). */
     excludeRuns?: string[];
-    /** Per recording a plan of this turn came from, the largest position (R-OUT-6). */
+    /**
+     * Per plan of this turn: its recording, and how far it got in its own chain
+     * — the step it handed over at (a decision included), or its last step when
+     * it ran to its end (R-OUT-6). One entry per plan; the service maps each onto
+     * the recording and keeps the largest (its segmentsbreakdown.md D18).
+     */
     ranThrough?: Array<{
         runId: string;
         position: number;
         scenarioId?: string;
     }>;
-    /** Present only with `BIR_SEGMENT_ARM` (R-OUT-9, R-OUT-10). */
+    /**
+     * Present only while segment arming is on (R-OUT-9, R-OUT-10): the
+     * recorder's default from 0.3.19, absent with `BIR_SEGMENT_ARM=0`.
+     */
     acceptSegments?: boolean;
     /** Always true from this runner (R-CALL-28). */
     supportsCalls?: boolean;

package/dist/replay/condition-words.d.ts

@@ -0,0 +1,28 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** The longest quote a decision note carries, in characters. */
+export declare const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export declare function mayHoldCondition(text: string): boolean;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export declare function conditionSentences(request: string | null | undefined, max?: number): string | null;
+//# sourceMappingURL=condition-words.d.ts.map

package/dist/replay/condition-words.js

@@ -0,0 +1,59 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** Words that say a part of a task depends on something: English, and the Hebrew the service reads. */
+const CONDITION_WORDS = /\b(if|otherwise|else|unless|only when|only if|in case|whether)\b/i;
+const HEBREW_CONDITION = /(^|[\s,.;:!?"'()\-])(אם|אחרת|אלא אם|במקרה ש|רק אם|רק כאשר)($|[\s,.;:!?"'()\-])/;
+/** The longest quote a decision note carries, in characters. */
+export const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export function mayHoldCondition(text) {
+    return CONDITION_WORDS.test(text) || HEBREW_CONDITION.test(text);
+}
+/**
+ * Where one sentence ends and the next begins: after `.`, `!`, `?` or `…` and
+ * white space, in front of a capital letter, a letter of a script with no
+ * capitals (Hebrew), a quote mark or a bracket. Never in front of a digit or a
+ * small letter, so "Nov. 20" and "e.g. the" stay in one sentence.
+ */
+const SENTENCE_BREAK = /(?<=[.!?…])\s+(?=[\p{Lu}\p{Lo}"'“‘(\[])/u;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export function conditionSentences(request, max = MAX_DECISION_QUOTE) {
+    if (typeof request !== "string" || request.trim() === "")
+        return null;
+    const sentences = request
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .flatMap((line) => line.split(SENTENCE_BREAK))
+        .map((s) => s.replace(/\s+/g, " ").trim())
+        .filter((s) => s !== "" && mayHoldCondition(s));
+    if (sentences.length === 0)
+        return null;
+    const quote = sentences.join(" ");
+    if (quote.length <= max)
+        return quote;
+    let cut = quote.slice(0, Math.max(0, max - 1));
+    // Never half of a character written as two code units (an emoji).
+    if (/[\uD800-\uDBFF]$/.test(cut))
+        cut = cut.slice(0, -1);
+    return `${cut.trimEnd()}…`;
+}
+//# sourceMappingURL=condition-words.js.map

package/dist/replay/controller.d.ts

@@ -240,8 +240,11 @@ export interface ReplayOptions {
     /** On unless `BIR_REPLAY=0`. Everything here is inert when false. */
     enabled: boolean;
     /**
-     * `BIR_SEGMENT_ARM`. Off means observe-only: the runner asks for no segment
-     * and arms none, and only logs what would have armed (R-OUT-10).
+     * Whether a handed-out segment may run mid-task. The recorder sets it from
+     * `BIR_SEGMENT_ARM`: on unless that is `0`, from runner 0.3.19 (the
+     * service's segmentsbreakdown.md SB-21). Omitted, as by a test or an
+     * embedder, it is off: observe-only, where the runner asks for no segment,
+     * arms none, and only logs what would have armed (R-OUT-10).
      */
     segmentArm?: boolean;
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
@@ -398,6 +401,14 @@ export interface ReplayState {
     retired: boolean;
     /** What armed it: the prompt, or a ReAct iteration's intent (fallbk.md). */
     armedBy: "prompt" | "intent";
+    /**
+     * The user's request this plan serves, in their own words: the prompt for a
+     * plan the prompt armed (set in `arm`), the turn's prompt for one an intent
+     * match armed (set by the control server). Read only for the note of a plan
+     * stopped at its decision, which quotes the request's condition sentences
+     * (the service's segmentsbreakdown.md SB-18). Never sent anywhere.
+     */
+    request?: string;
     /**
      * The Claude Code session this plan serves, set by the control server. Its
      * steps run on that session's own proxies (executor.ts). Absent for `bir
@@ -485,7 +496,10 @@ export interface ReplayState {
      * A plan that finished its work stops costing at that moment: the agent's
      * later work in the same turn is the agent's, not this plan's. A plan that
      * handed over or diverged takes no mark, because the follow-on work is the
-     * direct consequence of its stopping (R-MONEY-3, R-FALL-5).
+     * direct consequence of its stopping (R-MONEY-3, R-FALL-5) — except a plan
+     * stopped at its decision after a step ran: it did all it was for, and the
+     * agent's decision and the half it chose are the agent's own (the service's
+     * segmentsbreakdown.md SB-26).
      */
     retiredMark?: unknown;
     retiredAt?: number;
@@ -687,9 +701,11 @@ export declare 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(): boolean;
     /** The plan's own delivery vehicle is never a scenario step. */
@@ -732,6 +748,13 @@ export declare class ReplayController {
      * the field. Built from the same entries the directive lists.
      */
     planData(state: ReplayState): PlanData | undefined;
+    /**
+     * 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: ReplayState): boolean;
     /**
      * Take back a plan that armed and has run nothing, as a decline.
      *
@@ -1021,6 +1044,10 @@ export declare 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`.
      */
     runAdHoc(scenario: SerializedScenario, prompt: string, wrapped: ReadonlySet<string>): Promise<{
         ok: boolean;
@@ -1096,6 +1123,12 @@ export declare class ReplayController {
      * step.
      */
     private stopKindOf;
+    /**
+     * 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).
+     */
+    private decidedInDivergence;
     /**
      * 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
@@ -1209,6 +1242,12 @@ export declare class ReplayController {
     /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
     private upgrade;
     private retire;
+    /**
+     * 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).
+     */
+    private markRetired;
 }
 /** The subset of `RunMatch` replay consumes. Structural, so tests need no recorder. */
 export interface RunMatchLike {

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
@@ -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,
@@ -2436,7 +2484,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 +2530,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 +2592,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 +2661,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 +2693,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 +2719,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 +2785,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 +2834,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 +3351,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 +3366,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/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. */