@basein/runner 0.3.18 → 0.3.19

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) {

package/dist/replay/plan.d.ts

@@ -469,6 +469,12 @@ export declare class ScenarioReplayPlan {
     stopStep(): SerializedScenarioStep | undefined;
     /** The entry the plan stops in front of, with the frame that owns it. */
     stopEntry(): FlatEntry | undefined;
+    /**
+     * The flat position of the chain's decision stop (the service's
+     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
+     * on are the half the recording took, whatever stops the plan first.
+     */
+    decisionIndex(): number;
     /** Every entry in order — for the report, and for the owning scenario ids. */
     allEntries(): readonly FlatEntry[];
     /** The entry awaiting execution, or undefined when the plan is done. */
@@ -539,11 +545,12 @@ export declare class ScenarioReplayPlan {
         text: string | null;
     } | undefined;
     /**
-     * The tool names of the steps from flat position `from` to the end, each
-     * that runs only under a test marked so — for a hand-over note's "remaining
-     * planned steps", which must not read as steps this request needs.
+     * The tool names of the steps from flat position `from` to the end (or to
+     * `until`, not included), each that runs only under a test marked so — for a
+     * hand-over note's "remaining planned steps", which must not read as steps
+     * this request needs.
      */
-    remainingFrom(from: number): string[];
+    remainingFrom(from: number, until?: number): string[];
     /** The steps the plan's own cursor has left out so far, in order (AC5). */
     leftOut(): readonly LeftOut[];
     /** Whether any planned step runs only under a test. */

package/dist/replay/plan.js

@@ -700,6 +700,14 @@ export class ScenarioReplayPlan {
     stopEntry() {
         return this.stopsEarly() ? this.entries[this.stopAt] : undefined;
     }
+    /**
+     * The flat position of the chain's decision stop (the service's
+     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
+     * on are the half the recording took, whatever stops the plan first.
+     */
+    decisionIndex() {
+        return this.entries.findIndex((e) => e.step.stop?.kind === "decision");
+    }
     /** Every entry in order — for the report, and for the owning scenario ids. */
     allEntries() {
         return this.entries;
@@ -853,12 +861,13 @@ export class ScenarioReplayPlan {
         return undefined;
     }
     /**
-     * The tool names of the steps from flat position `from` to the end, each
-     * that runs only under a test marked so — for a hand-over note's "remaining
-     * planned steps", which must not read as steps this request needs.
+     * The tool names of the steps from flat position `from` to the end (or to
+     * `until`, not included), each that runs only under a test marked so — for a
+     * hand-over note's "remaining planned steps", which must not read as steps
+     * this request needs.
      */
-    remainingFrom(from) {
-        return this.entries.slice(Math.max(0, from)).map((e) => {
+    remainingFrom(from, until) {
+        return this.entries.slice(Math.max(0, from), until).map((e) => {
             const name = e.step.toolName ?? "";
             const t = this.onlyWhen(e);
             return t ? `${name} (only when ${t.text ?? "a request needs it"})` : name;
@@ -1279,10 +1288,21 @@ export class ScenarioReplayPlan {
             break;
         }
         const anyArgs = args.slice(0, argsShown).some((a) => a !== undefined);
+        // A plan whose chain holds a decision (the service's segmentsbreakdown.md
+        // SB-18) never shows its intent, even when it stops earlier for another
+        // reason: the intent names the recorded task, the half the recording took
+        // included, and which way applies is the agent's choice.
+        const atDecision = this.stopStep()?.stop?.kind === "decision";
+        const shownIntent = this.decisionIndex() >= 0 ? "" : intent;
         // A parked step (fallbk.md D3): the model is told up front that the plan is
         // partial, so the hand-over that follows is expected rather than a surprise.
         const tail = this.stopsEarly()
-            ? ["", "The system will then hand the rest of the task back to you."]
+            ? [
+                "",
+                atDecision
+                    ? "The system will then hand the task back to you at a decision."
+                    : "The system will then hand the rest of the task back to you.",
+            ]
             : [];
         if (this.mode === "direct") {
             // The sequence is listed even though the model does not call it itself:
@@ -1291,7 +1311,7 @@ export class ScenarioReplayPlan {
             // place an operator watching the session can see what a replay is doing.
             return [
                 "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
-                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
+                `for this request${shownIntent ? ` (intent: ${shownIntent})` : ""}.`,
                 "",
                 anyTest
                     ? 'It runs these tools, in order, and returns their results. A step marked "only when" runs only when this request needs it, and the results say which ones did not:'
@@ -1313,7 +1333,7 @@ export class ScenarioReplayPlan {
             "recorded for this request. Call exactly these tools, in order, one at a time:",
             "",
             ...lines,
-            ...(intent ? ["", `Context: ${intent}`] : []),
+            ...(shownIntent ? ["", `Context: ${shownIntent}`] : []),
             ...(anyTest
                 ? [
                     "",

package/dist/replay/types.d.ts

@@ -47,9 +47,18 @@ export interface StepStop {
      * `parked`: the step has failed too often and its retry is not due, or its
      * grace has ended. `nondeterministic`: the calculation could not write code
      * that computes this step's input — a judgement — so the agent makes it.
+     * `decision`: the task has an "if … otherwise" here (the service's
+     * segmentsbreakdown.md SB-6). The plan runs only the steps before it and
+     * hands the task back, and the agent decides which way applies. Not a
+     * failure: it counts nothing against the step. Runners up to 0.3.18 read it
+     * as an unknown kind and stop here too, as `known_bad_step`.
+     */
+    kind: "parked" | "nondeterministic" | "decision";
+    /**
+     * For `nondeterministic`: which check the step failed at calculation. For
+     * `decision`: the condition in words. It holds the recorded run's values,
+     * so it is never shown to the agent (it would hint at the recorded half).
      */
-    kind: "parked" | "nondeterministic";
-    /** For `nondeterministic`: which check the step failed at calculation. */
     why?: string;
     /** For `parked` inside its grace: when the step may be tried again. */
     retryAt?: string;
@@ -252,7 +261,14 @@ export type FallbackKind =
  * (autocorrect.md AC5): this request is the other half of an "if …
  * otherwise", and the agent does it. No fault of the plan; counts nothing.
  */
- | "other_branch";
+ | "other_branch"
+/**
+ * The plan ran the steps before its decision and stopped in front of it
+ * (the service's segmentsbreakdown.md SB-17): the agent decides which way
+ * applies and does the rest. No fault of the plan; it counts nothing, and
+ * the plan is billed only up to the stop (SB-26).
+ */
+ | "decision";
 /**
  * Upgrade order. `not_steered` is the floor — the control group, and the safe
  * answer if a turn dies mid-flight — and each later decision point can only move

package/docs/calculatedReplay.md

@@ -748,6 +748,30 @@ about it:
 It ends with the remaining planned steps and the parameters derived for this request, within 4 000
 characters.
 
+**A plan's decision (0.3.19)** has a note of its own. The service serves a step with
+`stop: {kind: "decision"}` where the task has an "if … otherwise" (its segmentsbreakdown.md). The
+plan runs only the steps before it, in steer and direct mode and when a divergence's bundle runs up
+to it, and hands the task back. The note opens *"[BaseInstRunner calculated replay] The calculated
+scenario for this request ran the steps before a decision, and stopped there."*, says which steps
+ran as above, and ends *"This request asks for a decision: “…”. Decide from the results above
+which way applies, then continue the task, calling tools as needed."* (*below* in a direct run's
+answer, *above and below* after a divergence; *"This task has a decision to make here."* when the
+request has no such sentence). The quote is the live request's own sentences with a word for a
+condition, found with the service's word list (`if`, `otherwise`, `else`, `unless`, `only when`,
+`only if`, `in case`, `whether`, and the Hebrew ones), at most 600 characters
+([`condition-words.ts`](../src/replay/condition-words.ts)). The note has no intent line, no
+remaining planned steps and no parameters, and never the condition the service keeps (`stop.why`):
+each names, or hints at, the half the recording took. The directive at the prompt leaves the intent
+out for the same reason, and says the task comes back *"at a decision"*. The report is `fell_back`
+(`failed` when no step ran) with `fallbackKind: "decision"`; the decision step has no verdict, so
+nothing counts against it. A runner up to 0.3.18 reads the unknown kind as `known_bad_step`.
+
+A plan whose chain has a decision keeps these protections when it stops *earlier* for another
+reason — a parked or failed step, a judgement, the budget. Its note is the ordinary one above, but
+with no intent line and no parameters, and its remaining planned steps end before the decision. Its
+directive leaves the intent out too. An agent sent on to the recorded half's steps would start that
+half's segment, and the plan would have decided after all.
+
 With `BIR_REPLAY_RECORDED_OUTPUTS=1`, a step that could not be *sent* (a built-in, no proxy, off the
 allowlist) is served its **recorded output** instead (§8.1), marked `(recorded)` in the bundle so the
 model is never told a stale result is fresh. A timeout or an upstream error never is.
@@ -1010,10 +1034,16 @@ note replaces the call, in direct mode `run_scenario` answers with it). The deri
 itself times out after max(`BIR_SERVICE_TIMEOUT_MS`, `BIR_DERIVE_BUDGET_MS`). None of these waits
 happens while the service is cooling down after a failure: the turn simply runs normally.
 
-**Intent arming mid-turn is opt-in.** An intent probe is sent from `PreToolUse` for hit counting and
-is never waited on, unless `BIR_INTENT_ARM=1` or `BIR_SEGMENT_ARM=1` lets it arm a plan in that
-call's place; then it waits at most `BIR_INTENT_ARM_BUDGET_MS` (**500**) for the probe and 1.5 s for
-arming. `BIR_INTENT_ARM=0` never waits.
+**Intent arming mid-turn is on by default from 0.3.19.** An intent probe is sent from `PreToolUse`
+for hit counting. While arming is on — `BIR_SEGMENT_ARM` unset or `1`, the recorder's default from
+0.3.19, or `BIR_INTENT_ARM=1` — the probe may arm a plan in that call's place, and the hook waits at
+most `BIR_INTENT_ARM_BUDGET_MS` (**500**) for it and 1.5 s more for arming. With `BIR_SEGMENT_ARM=0`
+(and no `BIR_INTENT_ARM=1`), or `BIR_INTENT_ARM=0`, it is never waited on. Up to 0.3.18 arming was
+opt-in: a segment runs only mid-task, and a plan that stops at its decision hands the rest of the
+task to segments of its halves, so 0.3.19 turns it on. A probe asks the service to hand segments out
+(`acceptSegments`) only where one can arm: segment and intent arming on, in Claude Code. Any other
+probe — `BIR_INTENT_ARM=0`, or a session of another host — gets what would have armed instead, and
+it is logged (`replay.segment_would_arm`).
 
 `UserPromptSubmit` must stay non-`async`: an async hook is fire-and-forget and cannot return
 `additionalContext` at all.
@@ -1045,7 +1075,8 @@ stopped at a step that broke (a logic failure, a tool error, a call sent and nev
 recorded stand-in (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is never work done: it counts toward neither
 `stepsPinned` nor the upgrade, and a direct run that used one is `diverged` at best. A call that ran
 beside a pinned one hands over as `fell_back` or `failed` (§7), and so does a divergence whose
-bundle stops in front of the other half of an "if … otherwise" (§9.2). A direct run cancelled by its caller
+bundle stops in front of the other half of an "if … otherwise" (§9.2), or in front of the plan's
+decision (§8). A direct run cancelled by its caller
 (Esc, or `bir-scenario`'s own timeout) books `fell_back` or `failed` with `measured: false`, never
 `diverged`: that turn's cost says nothing about what the task costs.
 
@@ -1256,6 +1287,15 @@ tokens and every model in the list has a price; with no usage at all, the line s
 `why="the host sent no usage"`. Such a host hands over one number for the whole run, so with more
 than one plan in one run none of them is measured.
 
+**A plan stopped at its decision is billed up to the stop (0.3.19).** When a step of it ran, its
+hand-over takes a usage mark, and its report's window ends there: the agent's decision and the half
+it took are the agent's own, not the plan's (the service's segmentsbreakdown.md SB-26). This holds
+for a plan the prompt started, which gets a way to take a mark only when its stop is a decision, and
+for one an intent match started, whose window already ended at its own retire. Every other plan
+keeps its window — a plan of the prompt is billed for the whole turn up to the next plan, so the
+answer it was asked for stays on its bill — and every other hand-over still takes no mark. A
+decision reached before any step ran takes no mark either: its report is a sample of the whole turn.
+
 ---
 
 ## 12. What the replayed turn records

package/docs/calculatedReplayGuide.md

@@ -327,7 +327,7 @@ Recording         : yes
   · the recorder runs in the background (pid 41820); its audit log is ~/.baseinstrunner/logs/<key>.log
   · the BaseIn service last answered the recorder 12 s ago
   · wrapped MCP calls are not approved by the runner: Claude Code asks as it would without it. For headless runs (`claude -p`) allow them in permissions.allow or --allowedTools, or set BIR_CORRELATION_DECISION=allow where the recorder starts
-  · recurring sub-tasks are observed only — nothing is replaced (BIR_SEGMENT_ARM unset)
+  · segments run mid-task — recurring sub-tasks, and the halves after a plan's decision — and so may whole plans (the default; BIR_SEGMENT_ARM=0 turns this off)
 
 No problems found.
 ```
@@ -370,7 +370,8 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in off `BIR_BUILTIN_TOOLS`, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
 | `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's own project directory and confined to it. A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
 | `BIR_BASH_ALLOW` | *(unset: any command)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered in the session. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's. A call with `run_in_background`, or with its own `timeout` longer than the step's clock (`BIR_STEP_TIMEOUT_MS`), is never started on the runner: the plan hands over in front of it |
-| `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits; unset follows `BIR_SEGMENT_ARM` |
+| `BIR_SEGMENT_ARM` | *(unset: on, from 0.3.19)* | A segment the service hands out runs mid-task: a recurring sub-task, or a half of a task after a plan's decision. `0` is observe-only: what would have armed is logged (`replay.segment_would_arm`) and nothing is replaced. Up to 0.3.18 observe-only was the default. A recorder started before an update keeps its old default until `bir up --restart` |
+| `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits, and then nothing starts mid-task, segments included: what would have armed is logged; unset follows `BIR_SEGMENT_ARM`, so from 0.3.19 it is on unless `BIR_SEGMENT_ARM=0` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 
 The `bir` server reads its own, from the environment Claude Code starts it with:
@@ -493,7 +494,8 @@ Everything replay decides is one line. `grep` for these:
 | `replay.step` | One direct step executed |
 | `replay.step_not_taken` | A step's test said this request does not need it, and nothing was sent for it ([calculatedReplay.md](calculatedReplay.md) §9.2). `plan.armed … tests=` lists the tested steps by their place in the plan: `4:hand_over,11:skip` |
 | `replay.diverge` / `replay.compose` | Off-script, and the recovery |
-| `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where |
+| `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where. `kind=decision` (0.3.19) is a plan that ran the steps before its decision and stopped there, as planned (`via=divergence` when a divergence's bundle ran up to it) |
+| `run.fragment … decision=true` / `run.fragment_dropped` | After a plan's decision: the agent's own work from its next call is recorded as a fragment, from which the service makes the other half / a plan the intent check armed took that call instead, so nothing is recorded as the other half |
 | `replay.vetoed` | A direct plan retired without running anything: `run_scenario` was not the first call, or never arrived |
 | `replay.run_ambiguous` | Two sessions had `run_scenario` pending and the request named neither; nothing ran |
 | `replay.cancelled` / `replay.note_kept` | A direct run's caller went away (Esc); no further step started, and the note is kept for the model's next call |
@@ -578,6 +580,11 @@ A recorded output that stood in for a step (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is
 work done. A direct run you cancel (Esc) is booked `fell_back` or `failed` with `measured: false`:
 a turn cut short says nothing about what the task costs.
 
+A plan that stops at its decision (runner 0.3.19 or newer) is booked `fell_back` with
+`fallbackKind: decision`, or `failed` when no step ran. Nothing is counted against its steps, and
+when a step ran its cost ends at the stop: the agent's decision and the half it took are not on the
+plan's bill.
+
 A turn's cost is **measured** only when its tokens were found and every model of the turn has a
 price in the runner's table. A model with no price used to count as $0, and that zero was called
 measured. Now such a turn is not measured, in Claude Code as in any host, and a `run.unmeasured`
@@ -656,6 +663,8 @@ Code's pool, as before.
 | `run_scenario` answers "The prepared results are not available for this request. Do the task normally with your tools." | The plan could not be delivered — a recorder that does not answer, a timeout, an HTTP error — and the model does the task itself | The `scenario.answered` line on the `bir` server's stderr has the real reason. `BIR_SCENARIO_DEBUG=1` in that server's environment hands the raw reason to the model as an error, for debugging |
 | A hand-over note says a step "was sent but did not answer … may or may not have completed" | The step timed out, or its upstream went away mid-call; nothing after it ran | Check whether its work happened before running it again — the model is told the same. Repeats: look at that upstream, or raise `BIR_STEP_TIMEOUT_MS` |
 | A hand-over note says "a step never runs on another session's upstream" | Two Claude Code sessions are open in the project, and this one has not yet made a call of its own to that server, so bir cannot tell its proxy from the other session's. A direct plan is told apart by the process that started both the `bir` server and the session's proxies, so for one this means an older proxy or `bir` server (restart the session after an update), or a server started through a wrapper such as a shell or `npx` | Expected: the model calls the tool itself. Once the session's own call to the server has gone through, later replays use its proxy |
+| A hand-over note says the plan "ran the steps before a decision, and stopped there" | The service split the plan at its "if … otherwise" (runner 0.3.19 or newer): the plan runs the steps both ways need, then the agent decides which way applies. The note quotes the request's own sentences with the condition | Expected. The agent's next step may start a segment of the way it chose (`replay.intent_armed … kind=segment`); with `BIR_SEGMENT_ARM=0` it does that part itself. `bir investigate` shows the run as `fell_back · decision` |
+| A hand-over note says a step "did not run: it has failed before", and the step never failed | A runner up to 0.3.18 met a plan's decision, a stop it does not know. It stops there too, but its note names a failure and lists the remaining steps | Update the runner (`bir update`, then `bir up --restart`) |
 | A hand-over note says a step "was not run by the host", or "ran with arguments a person chose, not the scenario's" | A LangChain application (§6.5). A person said no to the step, or answered in the tool's place, or a call limit blocked the call (`host_rejected`); or a person changed the call before it ran (`host_edited`) | Expected, and no fault of the plan: the step is booked `skipped`, the plan stops there and the model takes over. It is told not to run the step again — after a refusal, unless the user asks. §7 has what the report says |
 | `recorder.send_failed … error="HTTP 409 … invalid_ticket"` | The execution report's ticket was already redeemed, or belongs to another scenario. Or the report came more than an hour after its plan was handed out | Harmless if the body says `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once. A report that came too late is not booked; the service as built (not deployed yet) takes a report for 24 hours |
 | `recorder.send_failed … error="HTTP 429 …"` | The account is over one of the service's limits, and the answer is `429` with `Retry-After`. The limits are built on the service and not deployed yet; each is a setting there. By default: 120 runs a minute · 3,000 steps a minute (a tool call is two steps) · 10 title requests a minute · 20 requests in any one hour for Calculate, Prefer and Recalculate together (`bir scenario calc` then prints a line that begins `Could not start calculation (HTTP 429`) | What it costs: a create, a step or a report is sent once more, at most 2 s later, then dropped. A dropped step is a hole in its recording. A run whose create got the 429 runs without its plan. A 429 that the second try did not cure counts as the service being unwell: for 5 to 60 seconds no prompt of that recorder waits for a match. An intent probe over its own limit (1,500 a minute) is answered with no match, never with `429` |
@@ -1337,7 +1346,7 @@ Parameter database: target → setting (revision 4). Undo: bir scenario undo scn
 | `revision_changed` | The plan changed since you read it: another edit, or a recalculation | `show` it again, check again, save again |
 | `not_ready` or `scenario_calculating` | The scenario is not `ready`, or a recalculation is running | Wait for it to finish |
 | `undo_refused` | The undo would stop a later step from giving its recorded call, or leave the final answer without its values | Fix that later step first. Or undo it on purpose: `--force --note "why"` |
-| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it. For a correction: the plan has changed since it | `bir` prints two commands: undo the newer one first, then yours |
+| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it. For a correction: the plan has changed since it. When the newer entry is an `ssplit_…` id, the plan was split at its decision after the correction, and a correction cannot be taken back while the split is in use | `bir` prints two commands: undo the newer one first, then yours. For a split, `bir` says to press Undo on the Split card of the plan's recording page first, and prints the command for yours |
 | `already_undone` | That edit was undone already | To redo it, undo the undo. `bir` prints the command |
 | `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
 | `logic_sandbox_unavailable` | The service could not run step code just now (HTTP 503). Nothing was checked, saved or undone | Try again in a minute |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",

package/production.md

@@ -594,6 +594,18 @@ Truncation is always marked with the original size.
 - An Esc-interrupted turn is never booked as a saving (`measured:false`).
 - A step that a host other than Claude Code (§3.2) stopped itself has two stop reasons of its own. `host_rejected`: a person said no, or answered in the tool's place, or a call limit blocked the call. The note says "Step N of M (tool) was not run by the host. The result above was written by the host, not by the tool. Do not run the step again unless the user asks." `host_edited`: a person changed the call. The note says "Step N of M (tool) ran with arguments a person chose, not the scenario's. Its result above is real and its side effects are in place. Do not run it again." The report's `fallbackKind` stays `step_failed`.
 
+**The decision stop (0.3.19).** The service may serve a step with `stop: {kind: "decision"}`: the task has an "if … otherwise" there (the service's segmentsbreakdown.md). The plan never decides:
+
+- It runs only the steps before the decision, then hands the task back, in steer and direct mode and after a divergence.
+- The note says the plan "ran the steps before a decision, and stopped there", says which steps ran, and quotes the request's own sentences with a condition word (`if`, `otherwise`, `unless` and the others the service uses, Hebrew too; at most 600 characters). It ends "Decide from the results above which way applies, then continue the task". It has no intent line, no remaining steps and no parameters, and never the condition the service keeps (`stop.why`): each would hint at the half the recording took. The directive at the prompt leaves the intent out too, and says the task comes back "at a decision".
+- A plan whose chain has a decision keeps these protections when it stops earlier for another reason (a parked or failed step, a judgement, the budget). Its note has no intent line and no parameters, and lists the remaining steps only up to the decision. Its directive leaves the intent out. An agent sent on to the recorded half's steps would start that half's segment, and the plan would have decided after all.
+- The report is `fell_back` (or `failed` when no step ran) with `fallbackKind: "decision"` and `fallbackStepIndex` the decision step. The decision step gets no verdict, so nothing is counted against it.
+- When a step ran, the hand-over takes the plan's usage mark: the plan is billed up to the stop, and the agent's decision and the half it took are not on its bill. This holds for a plan the prompt started and for one an intent match started. Every other hand-over still takes no mark.
+- The agent's own next call opens the fragment, marked `metadata.decisionOf = {scenarioId, stepIndex}`: the service makes the other half of the task from it. When a plan the intent check armed takes that call instead (a segment of one half), the fragment is dropped (`run.fragment_dropped`): what follows is not the other half.
+- `ranThrough` sends one entry per plan, with the plan's own position (the decision step itself for a decision). The service maps it onto the recording.
+- `bir replay` stops in front of a decision and says so (`stopped     before step N …: the plan's decision`).
+- A runner up to 0.3.18 reads the unknown kind as `known_bad_step`: it stops there too, but its note and report name a failure.
+
 **Measured cost.**
 
 - A turn's cost is measured only when tokens were found and every model of the turn has a price in the runner's table. This holds for every host, Claude Code too. A model outside the table used to cost $0, and that zero was called measured.
@@ -710,7 +722,7 @@ Truncation is always marked with the original size.
 | Remote servers without a literal credential header (OAuth, headersHelper, `${VAR}`) are left unwrapped. Earlier unasked wraps are undone. | The proxy has none of Claude Code's OAuth credentials; wrapped, these servers answered 401 to every call. | `--server <name>` (remembered). |
 | A flag-less install from an installed package writes absolute-path entries and the self-starting SessionStart hook, for `bir wrap` too. | No npx registry round trip per server start (about 1 s), and it works offline. npx installs had nothing to start the recorder. | `--npx`. A checkout, or `bir` run through npx, still writes npx. |
 | Hook timeouts: SessionStart command 15 s (was 30), HTTP 5 (10), UserPromptSubmit 10 (15), PreToolUse 15 (30), PostToolUse and PostToolUseFailure 5 (30), Subagent 3 (5), Stop 5 (10), SessionEnd 3 (30). | The timeout is the user's worst case during an incident. The server's deadlines sit inside it. | Not configurable; `bir setup` rewrites them. |
-| Mid-turn intent arming is opt-in, and the intent probe is never waited on by default. | 0.2.12 held every PreToolUse up to 4 s for the probe. | `BIR_INTENT_ARM=1` (or `BIR_SEGMENT_ARM=1`) with `BIR_INTENT_ARM_BUDGET_MS=4000`. |
+| From 0.3.19 segments run mid-task by default (`BIR_SEGMENT_ARM` unset means on), and so may whole plans by intent. An unsteered PreToolUse waits for the intent probe: at most `BIR_INTENT_ARM_BUDGET_MS` (500 ms), and up to 1.5 s more while an armed plan's values are read. From 0.3.0 to 0.3.18 arming was opt-in and the probe was never waited on. | A plan that stops at its decision hands the rest of the task to segments of its halves, and a segment runs only mid-task (the service's segmentsbreakdown.md SB-21). 0.2.12 held every PreToolUse up to 4 s for the probe. | `BIR_SEGMENT_ARM=0` (observe only: what would have armed is logged). `BIR_INTENT_ARM=0` arms nothing mid-task and never waits; its probes then ask for no segment, as in a session of another host, so what would have armed is logged too. |
 | The prompt match budget is 3 s (was 2.5 s), and there is a match gate: over 2 s, prompts stop waiting for 5 min, doubling to 30 min. | A healthy service answers in 300-450 ms. A slower one would otherwise cost every prompt. A false trip costs one hold of replay, never latency. | `BIR_MATCH_BUDGET_MS=2500`. Raising `BIR_MATCH_SLOW_MS` above the budget effectively disables the gate. |
 | Recorded outputs no longer stand in for a step that produced no result; the plan hands over at that step. | Last week's output presented as this turn's result is wrong data. | `BIR_REPLAY_RECORDED_OUTPUTS=1`, only for steps that could not be sent. `bir replay` keeps the stand-ins. |
 | The direct plan budget is 100 s (was 120 s), and direct runs are clamped to 270 s. | Keeps a direct run under Claude Code's 2-minute auto-background of an MCP call, and inside `run_scenario`'s client timeout. | `BIR_REPLAY_PLAN_BUDGET_MS=120000` (or `BIR_REPLAY_BUDGET_MS`). |
@@ -845,7 +857,7 @@ Truncation is always marked with the original size.
   - where recording goes, and as whom;
   - when the service last answered;
   - who approves wrapped MCP calls (the recorder's correlation mode);
-  - whether sub-tasks are observe-only;
+  - whether segments run mid-task (the default from 0.3.19) or are observed only, and whether whole plans may start mid-task too; a recorder older than this `bir` is named, since it keeps its old default until `bir up --restart`;
   - superseded recorders;
   - an npx-started scenario server;
   - other installed projects.
@@ -894,8 +906,9 @@ In a folder that is set up for another host (§3.2), doctor prints `Host
 | `registeredProxies[]`, `wrappedServers` | proxies that registered (`serverName`, `pid`, `cwd`, `version`) and the wrapped server names |
 | `hooksVersion`, `pid`, `cwd`, `url` | the recorder's version and identity |
 | `hostFields` | `2`: how much of another host's protocol (§3.2) this recorder understands. An adapter reads it before it relies on a field: with 1 it records, and from 2 it may also ask for a plan and step through it. A recorder that does not know another host answers no `hostFields`. |
-| `segmentArm` | whether service-found sub-tasks may run mid-task (default: observe only) |
-| `sessionCount`, `sessions[]` | at most 50, active ones first: `{sessionId, runId, active, idleMs, ended, steps, recording, replay, intent, fragment}`. `replay` includes `armed`, `unannounced`, `running`, `outcome` and `handover`. |
+| `segmentArm` | whether segments the service hands out may run mid-task (default from 0.3.19: yes; `BIR_SEGMENT_ARM=0`: observed only) |
+| `intentArm` | whether a step's intent may start a plan in its own PreToolUse, which then waits for the probe. It follows `segmentArm` unless `BIR_INTENT_ARM` is set. Absent from a recorder older than 0.3.19. |
+| `sessionCount`, `sessions[]` | at most 50, active ones first: `{sessionId, runId, active, idleMs, ended, steps, recording, replay, intent, fragment}`. `replay` includes `armed`, `unannounced`, `running`, `outcome` and `handover` (`{kind, stepIndex}`; `kind` may be `decision`). `fragment` is `{state}`, with `decision: true` for one scheduled at a plan's decision. |
 
 ### 8.4 Logs and audit lines
 
@@ -917,7 +930,7 @@ Lines read `[bir] <ISO time> <event> key=value …`, with each field clipped at
 | Hooks | `control.listening` (port, `recorder=<state>`, `correlation=`). `control.correlation_allow` (auto-approval opted in). `control.hook_deadline`, `control.hook_unauthorized` (a token from another install), `control.hook_unknown`, `control.hook_oversize`, `control.hook_event_mismatch`, `control.route_failed`, `control.drain_abandoned`. |
 | Recorder lifecycle | `daemon.restart` (replaced an older recorder), `daemon.restart_deferred` (mid-run: next start), `daemon.start_alongside`, `daemon.newer_kept`, `daemon.revived`. `control.port_busy` (holder and fix), `control.already_running`, `control.superseded`, `control.discovery_reclaimed`, `control.log_reopened`, `control.fatal`. `overrides.stale` (a local copy no longer matches its source: run `bir setup`). |
 | Proxy (MCP log) | `proxy.upstream_gone` (exiting with the server), `proxy.recorder_revive`, `tier.downgrade`, `tier.rebound`, `relay.undeliverable`. `upstream.auth_required` (the remote refused the handshake: credentials), `upstream.needs_sign_in`, `upstream.headers_invalid`, `upstream.proxy_env_ignored` (this Node cannot use HTTPS_PROXY), `upstream.proxy_env_invalid`, `upstream.standing_stream_failed` (at most hourly). Verbose only: `proxy.started`, `tier.bound`, `tier.passthrough`, `run.start` / `run.finish`, `upstream.stream_*`. |
-| Replay | `replay.enabled` (at start: servers, threshold, who derives). `plan.armed`. `replay.decision` (also `arm_timeout`, `arm_unannounced`, `no_directive`, `no_delivery_tool`, `missing_target`, `host_records_only`, `host_tool_missing`). `replay.pin`, `replay.pin_declined`, `replay.pin_abandoned`, `replay.pin_overran`, `replay.diverge`, `replay.diverge_overran`, `replay.handover`, `replay.vetoed`, `replay.unsafe_param`, `replay.derive_timeout`, `replay.budget_clamped`, `replay.concurrent_call`, `replay.no_session_proxy`, `replay.run_ambiguous`, `replay.run_abandoned`. |
+| Replay | `replay.enabled` (at start: servers, threshold, who derives). `plan.armed`. `replay.decision` (also `arm_timeout`, `arm_unannounced`, `no_directive`, `no_delivery_tool`, `missing_target`, `host_records_only`, `host_tool_missing`). `replay.pin`, `replay.pin_declined`, `replay.pin_abandoned`, `replay.pin_overran`, `replay.diverge`, `replay.diverge_overran`, `replay.handover`, `replay.vetoed`, `replay.unsafe_param`, `replay.derive_timeout`, `replay.budget_clamped`, `replay.concurrent_call`, `replay.no_session_proxy`, `replay.run_ambiguous`, `replay.run_abandoned`. A plan's decision (0.3.19): `replay.handover kind=decision` (`via=divergence` when a divergence's bundle ran up to it), `run.fragment … decision=true` (the agent's own work after it is recorded), `run.fragment_dropped` (a plan the intent check armed took the agent's next call, so nothing is recorded as the other half), `replay.adhoc_decision` (`bir replay` stopped in front of it). `replay.enabled` also says `segments=run mid-task`, or `observed only` with `BIR_SEGMENT_ARM=0` or `BIR_INTENT_ARM=0`. |
 | Run cost | `run.unmeasured` (the turn's cost is not measured: `why` gives the reason, and `models` the models that have no price in the runner's table). |
 | A host other than Claude Code (§3.2) | `run.start … host=langchain` (`bir investigate` reads the host from it, and raises no `steer_mode` finding for such a turn: steer is the full mode there), `plan.armed … mode=steer host=langchain`. `run.finish … ended=<reason>` (the run did not end with an ordinary stop). `run.unmeasured` (`why="the host sent no usage"`, a model with no price, or a run that made no model call). `run.incomplete` (the host says the recording is not the whole run: its finish carries the `incomplete` mark). `run.host_failed` (the host says the run failed: its recording is closed with that error). The service's new build never picks a run with an `error` or that mark for automatic calculation, and such a run no longer catches its prompt, unless its owner preferred it or it already has a plan (built, not deployed yet). `replay.decision verdict=no-steer code=host_records_only` (the adapter asked for no plan with its prompt) and `code=host_tool_missing` (the plan names a tool that the agent which asked does not have). `replay.own_call` (the model made a call of its own while the plan was live: the plan is handed over). `replay.step_host_stopped` (`stop=rejected` or `stop=edited`). `session.host_refused` (a scope that is empty, longer than 64 characters or not a text: nothing of that session is recorded or replayed). |
 | `bir-scenario` (MCP log) | `scenario.answered` (`ok` means results were delivered; also `partial`, `bound`), `scenario.recorder_revive`, `scenario.switched`, `scenario.hello_failed`, `scenario.tool_timeout`, `scenario.tool_truncated`. |
@@ -1053,9 +1066,9 @@ Defaults were checked in `src/`.
 | `BIR_INTENT_MATCHES_PER_TURN` | recorder | 3 | Plans intent may arm per turn. |
 | `BIR_INTENT_REQUESTS_PER_TURN` | recorder | 40 | Probes per turn. |
 | `BIR_INTENT_SOURCES` | recorder | `text,thinking,tool` | Which text an intent may be read from. |
-| `BIR_INTENT_ARM` | recorder | unset (follows `BIR_SEGMENT_ARM`) | `1`: a probe may arm a plan in its own PreToolUse, and that hook waits for it. `0`: never. Never in a session of another host (§3.2), where a probe only counts. |
+| `BIR_INTENT_ARM` | recorder | unset (follows `BIR_SEGMENT_ARM`, so on from 0.3.19) | `1`: a probe may arm a plan in its own PreToolUse, and that hook waits for it. `0`: never. Never in a session of another host (§3.2), where a probe only counts. |
 | `BIR_INTENT_ARM_BUDGET_MS` | recorder | 500 | How long that PreToolUse waits for the probe. |
-| `BIR_SEGMENT_ARM` | recorder | unset (observe only) | `1`: recurring sub-tasks the service found may run mid-task. Not in a session of another host. |
+| `BIR_SEGMENT_ARM` | recorder | on (from 0.3.19; unset or `1`) | A segment the service hands out runs mid-task: one found by repeated work, or a half after a plan's decision. `0`: observe only, where what would have armed is logged (`replay.segment_would_arm`) and nothing is replaced. Up to 0.3.18 the default was observe only. Not in a session of another host. |
 | `BIR_CONTROL_URL` | proxy, scenario | written into wrapped entries | The project's control server. Together with `BIR_CONTROL_TOKEN` it is the SDK channel and wins over discovery. |
 | `BIR_CONTROL_TOKEN` | proxy, scenario | unset | Bearer token for the SDK channel. |
 | `BIR_PROXY_STAY_UP` | proxy | unset | `1`: keep answering errors after the upstream dies (0.2.12). |
@@ -1113,6 +1126,7 @@ Defaults were checked in `src/`.
    - `langChainGuide.md`, which is in the repository's root and not in the npm package: its "Where it stands" table and its part 5 describe the time before the release.
 
    The install scripts cannot set a folder up for such a host, so there is no one-line install for it.
+8. **A plan's decision (0.3.19): the service first.** Deploy the service build that accepts `fallbackKind: "decision"` before 0.3.19 is published (the service's segmentsbreakdown.md section 8, step 1). An older service answers such a report 400, and the run's cost and saving are lost. Then test 0.3.18 against a plan with a decision (it stops there, reported as `known_bad_step`). The deployed service makes no split while its `SCENARIO_SPLIT` is false, so run this check on a sandbox or local service started with `SCENARIO_SPLIT=true`, with bir 0.3.18 pointed at it: set `BIR_AUTH_URL` to its address, run `bir login` (with an account on that service), then `bir up --restart` in the folder you test in. bir keeps one session, for the service that issued it: without that sign-in nothing is recorded on the local service, and while bir is signed in there, nothing on this PC is recorded on the deployed one. The service's segmentsbreakdown.md section 8, step 2, has the steps. Then point bir back: set `BIR_AUTH_URL` to the deployed service's address (removing it is not enough, since the local sign-in stored the local address), run `bir login` again, then `bir up --restart` in that folder. Then publish 0.3.19, and only then turn the deployed service's `SCENARIO_SPLIT` on.
 
 **Manual end-to-end checks with the real Claude Code.** These are behaviours of Claude Code itself, which the automated tests simulate but cannot prove. Use the Claude Code version you will support; the approval rules and hook schema were read from 2.1.280.