@basein/runner 0.2.7 → 0.2.8

package/dist/bin/investigate.js

@@ -179,7 +179,11 @@ export const DECLINES = {
     },
     known_bad_first_step: {
         cause: "the chain's first step is parked after repeated failures.",
-        fix: "recalculate the scenario (`bir scenario calc <runId> --force`).",
+        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt. To repair now: `bir scenario calc <runId> --force`.",
+    },
+    nondeterministic_first_step: {
+        cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",
+        fix: "the agent does this task itself; a model step for such judgements is planned (plan-services.md W3.1).",
     },
     unusable_first_step: {
         cause: "the first step calls a sub-task that is gone, switched off or stale.",

package/dist/control/server.js

@@ -944,11 +944,14 @@ export class ControlServer {
                 continue;
             let position;
             if (!state.plan) {
-                // Only a known-bad first step means the turn is committed to doing this
-                // recording's work itself from position 0 (R-HIT-14); every other
-                // decline leaves the recording untouched.
-                if (state.declined === "known_bad_first_step")
+                // Only a first step the plan cannot start on — parked, or a judgement
+                // — means the turn is committed to doing this recording's work itself
+                // from position 0 (R-HIT-14); every other decline leaves the recording
+                // untouched.
+                if (state.declined === "known_bad_first_step" ||
+                    state.declined === "nondeterministic_first_step") {
                     position = 0;
+                }
             }
             else if (state.handover) {
                 position = state.handover.stepIndex;

package/dist/replay/controller.d.ts

@@ -219,7 +219,7 @@ export interface ReplayState {
  * Why a match did not arm. One code per gate of the ladder, so the caller can
  * act on a decline without parsing the sentence that explains it.
  */
-export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "similarity" | "known_bad_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key";
+export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "similarity" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key";
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -417,6 +417,13 @@ export declare class ReplayController {
      * scenario that did nothing has nothing to book, and is a baseline sample.
      */
     private handOver;
+    /**
+     * Which kind of stop a plan's end is (plan-services.md D8). The stopping
+     * step's own served reason wins — the calculation's verdict is more exact
+     * than a counter — then a call the service could not answer, then a parked
+     * step.
+     */
+    private stopKindOf;
     private noteFor;
     /**
      * The executor handed to a plan: dispatch a step to the proxy that owns its
@@ -476,6 +483,22 @@ export interface RunMatchLike {
     /** The frozen name, beside the runtime intent the plan runs on (R-INTENT-12). */
     intentName?: string;
 }
+/**
+ * The old rule, for a service that sends no `stop`: the position of the first
+ * step whose failure count is above `maxStepFailures` (fallbk.md D3), or
+ * undefined when none is — including when the service sent no policy, which an
+ * older service never does.
+ */
 export declare function knownBadStepIndex(steps: readonly SerializedScenarioStep[], maxStepFailures: number | undefined): number | undefined;
+/**
+ * Position of the first step the plan must stop in front of (plan-services.md
+ * D8), or undefined when there is none.
+ *
+ * A step that carries `stop` was decided by the service — `null` means run it,
+ * even when its count is past the limit: its retry is due. A step without the
+ * field came from an older service, and the old counter rule decides it. Both
+ * can sit in one chain, since a called segment is served on its own terms.
+ */
+export declare function stopIndex(steps: readonly SerializedScenarioStep[], maxStepFailures: number | undefined): number | undefined;
 export {};
 //# sourceMappingURL=controller.d.ts.map

package/dist/replay/controller.js

@@ -204,20 +204,31 @@ export class ReplayController {
         const entries = flat.entries;
         if (entries.length === 0)
             return decline("the chain has no runnable step", "not_ready");
-        // Gate 5 — known-bad steps (fallbk.md D3). The plan ends in front of the
-        // first step the service has seen fail more than its limit — the counter on
-        // whichever scenario owns that step (R-CALL-30). A call the service could
-        // not answer stops the plan the same way, and the earlier of the two wins.
-        const badAt = knownBadStepIndex(entries.map((e) => e.step), match.fallback?.maxStepFailures);
+        // Gate 5 — steps the plan must stop in front of (fallbk.md D3,
+        // plan-services.md D8): a step the service parked — failed more than its
+        // limit, retry not due — or one the calculation marked non-deterministic,
+        // on whichever scenario owns it (R-CALL-30). A call the service could not
+        // answer stops the plan the same way, and the earliest of them wins.
+        const badAt = stopIndex(entries.map((e) => e.step), match.fallback?.maxStepFailures);
         const rawStop = [flat.stopAt, badAt].filter((n) => typeof n === "number");
         // Clamped to the start of the outermost called frame it falls in: a plan
         // never runs half a sub-task and leaves its result mapping unevaluated.
         const stopAt = rawStop.length > 0 ? clampToFrameStart(entries, Math.min(...rawStop)) : undefined;
         if (stopAt === 0) {
-            const why = flat.stopAt === 0 && flat.stopReason
-                ? `its first step is a call that cannot run: ${flat.stopReason.reason}`
-                : `its first step has failed ${entries[0].step.failureCount ?? 0} times — the agent does this task`;
-            return decline(why, flat.stopAt === 0 && flat.stopReason ? "unusable_first_step" : "known_bad_first_step");
+            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";
+            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`;
+            return decline(why, unusable
+                ? "unusable_first_step"
+                : judgement
+                    ? "nondeterministic_first_step"
+                    : "known_bad_first_step");
         }
         const planned = stopAt === undefined ? entries : entries.slice(0, stopAt);
         // Gate 6 — tool coverage, over the steps that will actually run.
@@ -333,6 +344,8 @@ export class ReplayController {
             // What this chain calls, and what answers each call right now (R-CALL-32).
             calls: callLines(scenario),
             unusable: flat.stopReason?.reason,
+            // Which steps the service told this plan to stop in front of, and why.
+            stops: stopLines(entries),
             coverage: coverageOf(entries.map((e) => e.step), wrapped, this.opts.allowServers).join(","),
             tools: entries.map((e) => e.step.toolName ?? "").join(","),
         });
@@ -562,7 +575,7 @@ export class ReplayController {
             // is a call the service could not answer (segmented.md R-CALL-29).
             const parked = plan.stopStep();
             this.handOver(state, {
-                kind: state.flatStop ? "unusable_call" : "known_bad_step",
+                kind: this.stopKindOf(state, plan.stopEntry()),
                 step: parked,
                 entry: plan.stopEntry(),
                 position: plan.stepCount,
@@ -639,7 +652,10 @@ export class ReplayController {
             const position = stop.flatIndex ?? plan.stepCount;
             const step = plan.allSteps()[position];
             this.handOver(state, {
-                kind: stop.kind,
+                // The plan only knows it stopped in front of its end; which kind of
+                // stop that is — parked, a judgement, a call that cannot run — is
+                // decided here, where the served reasons are.
+                kind: stop.kind === "known_bad_step" ? this.stopKindOf(state, plan.stopEntry()) : stop.kind,
                 step,
                 entry: plan.allEntries()[position],
                 position,
@@ -1070,7 +1086,7 @@ export class ReplayController {
         let text = composed.text;
         if (plan.stopsEarly()) {
             const parked = plan.stopStep();
-            const stopKind = state.flatStop ? "unusable_call" : "known_bad_step";
+            const stopKind = this.stopKindOf(state, plan.stopEntry());
             state.handover = {
                 kind: stopKind,
                 stepIndex: parked.stepIndex,
@@ -1132,9 +1148,22 @@ export class ReplayController {
                 ? "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"
-                    : "a step broke — the agent continues from here",
+                    : h.kind === "nondeterministic_step"
+                        ? "the next step needs a judgement the plan cannot compute — the agent makes it"
+                        : "a step broke — the agent continues from here",
         });
     }
+    /**
+     * Which kind of stop a plan's end is (plan-services.md D8). The stopping
+     * step's own served reason wins — the calculation's verdict is more exact
+     * than a counter — then a call the service could not answer, then a parked
+     * step.
+     */
+    stopKindOf(state, entry) {
+        if (entry?.step.stop?.kind === "nondeterministic")
+            return "nondeterministic_step";
+        return state.flatStop ? "unusable_call" : "known_bad_step";
+    }
     noteFor(state, h) {
         const plan = state.plan;
         const executed = h.ranThisStep ? h.position + 1 : h.position;
@@ -1243,6 +1272,9 @@ export class ReplayController {
             stage: info.stage ?? (status === "skipped" ? "tool_call" : undefined),
             error,
             durationMs: info.ms,
+            // The tool is gone from its server: the service repairs the plan without
+            // waiting out the grace (plan-services.md D8, kind 2).
+            toolMissing: info.toolMissing || undefined,
             // A verdict about a called segment's step is counted on that segment, at
             // the revision it was served (R-CALL-13).
             scenarioId: info.entry && info.entry.depth > 0 ? info.entry.scenarioId : undefined,
@@ -1340,11 +1372,6 @@ function targetKeys(schema) {
         return [];
     return Object.keys(schema).filter((k) => schema[k]?.kind !== "setting");
 }
-/**
- * Position of the first step whose failure count is above `maxStepFailures`
- * (fallbk.md D3), or undefined when none is — including when the service sent
- * no policy, which an older service never does.
- */
 /**
  * The index a hand-over reports, in the *caller's* chain (R-CALL-32).
  *
@@ -1369,10 +1396,39 @@ function callLines(scenario) {
         .map((s) => `${s.segmentId ?? "-"}:${s.unusable ?? s.resolution?.state ?? "resolved"}`)
         .join(",");
 }
+/** The served stops in a flat chain, for the `plan.armed` line (plan-services.md D8). */
+function stopLines(entries) {
+    const lines = entries
+        .map((e, i) => e.step.stop ? `${i}:${e.step.stop.kind}${e.step.stop.repairDue ? "/repair" : ""}` : undefined)
+        .filter((s) => s !== undefined);
+    return lines.length > 0 ? lines.join(",") : undefined;
+}
+/**
+ * The old rule, for a service that sends no `stop`: the position of the first
+ * step whose failure count is above `maxStepFailures` (fallbk.md D3), or
+ * undefined when none is — including when the service sent no policy, which an
+ * older service never does.
+ */
 export function knownBadStepIndex(steps, maxStepFailures) {
+    const i = steps.findIndex((s) => isKnownBad(s, maxStepFailures));
+    return i < 0 ? undefined : i;
+}
+function isKnownBad(step, maxStepFailures) {
     if (typeof maxStepFailures !== "number" || !Number.isFinite(maxStepFailures))
-        return undefined;
-    const i = steps.findIndex((s) => (s.failureCount ?? 0) > maxStepFailures);
+        return false;
+    return (step.failureCount ?? 0) > maxStepFailures;
+}
+/**
+ * Position of the first step the plan must stop in front of (plan-services.md
+ * D8), or undefined when there is none.
+ *
+ * A step that carries `stop` was decided by the service — `null` means run it,
+ * even when its count is past the limit: its retry is due. A step without the
+ * field came from an older service, and the old counter rule decides it. Both
+ * can sit in one chain, since a called segment is served on its own terms.
+ */
+export function stopIndex(steps, maxStepFailures) {
+    const i = steps.findIndex((s) => s.stop !== undefined ? s.stop !== null : isKnownBad(s, maxStepFailures));
     return i < 0 ? undefined : i;
 }
 //# sourceMappingURL=controller.js.map

package/dist/replay/handover.js

@@ -60,6 +60,11 @@ export function buildHandoverNote(n) {
             : "";
         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 {
         const error = n.error ? `: ${truncate(n.error, MAX_ERROR_CHARS)}` : "";
         lines.push(`Step ${human} of ${n.totalSteps}${tool} failed${error}`);

package/dist/replay/plan.d.ts

@@ -65,6 +65,8 @@ export interface StepInfo {
     error?: string;
     derivedKeys?: string[];
     ms: number;
+    /** The tool is gone from its server, read from the error (plan-services.md D8). */
+    toolMissing?: boolean;
 }
 export type StepObserver = (info: StepInfo) => void;
 export interface ComposeResult {

package/dist/replay/plan.js

@@ -23,7 +23,7 @@
 import { evalParamMapLogic, evalParamsLogic, evalResponseParamsLogic, evalResultMapLogic, evalToolInputLogic, evalToolOutputLogic, } from "./logic.js";
 import { flatEntriesOf } from "./flatten.js";
 import { assembleBundle, bundleInput, MAX_REPLAY_REASON } from "./bundle.js";
-import { toolResultError } from "./tool-error.js";
+import { isMissingToolError, toolResultError } from "./tool-error.js";
 /**
  * The recorded values for the *settings* a mapping did not name (R-CALL-21).
  *
@@ -433,13 +433,29 @@ export class ScenarioReplayPlan {
                     : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
                 if (!fallback) {
                     skipped += 1;
-                    onStep?.({ step, entry, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
+                    onStep?.({
+                        step,
+                        entry,
+                        input: computed,
+                        outcome: "skipped",
+                        error,
+                        toolMissing: isMissingToolError(error) || undefined,
+                        ms: Date.now() - startedAt,
+                    });
                     continue;
                 }
                 response = fallback;
                 recorded = true;
                 recordedCount += 1;
-                onStep?.({ step, entry, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
+                onStep?.({
+                    step,
+                    entry,
+                    input: computed,
+                    outcome: "recorded",
+                    error,
+                    toolMissing: isMissingToolError(error) || undefined,
+                    ms: Date.now() - startedAt,
+                });
             }
             // Thread the output for later steps' inputs. A recorded output threads
             // too: `toolOutputLogic` was authored against exactly this shape, and a
@@ -465,6 +481,7 @@ export class ScenarioReplayPlan {
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
                     error,
+                    toolMissing: isMissingToolError(error) || undefined,
                     derivedKeys,
                     ms: Date.now() - startedAt,
                 });
@@ -518,6 +535,9 @@ export class ScenarioReplayPlan {
             }
             const entry = this.entries[this.stepIndex];
             const step = entry.step;
+            // Where this step sits in the flat list — what a stop reports. Taken now,
+            // because the cursor has moved on by the time some stops are written.
+            const flatIndex = this.stepIndex;
             const startedAt = Date.now();
             let computed;
             try {
@@ -529,6 +549,7 @@ export class ScenarioReplayPlan {
                 stopped = {
                     kind: "step_failed",
                     stepIndex: step.stepIndex,
+                    flatIndex,
                     stage: "tool_input_logic",
                     error: errText(err),
                 };
@@ -547,7 +568,15 @@ export class ScenarioReplayPlan {
                     : undefined) ?? (await recordedOutputFor?.(entry).catch(() => undefined));
                 if (!fallback) {
                     skipped += 1;
-                    onStep?.({ step, entry, input: computed, outcome: "skipped", error, ms: Date.now() - startedAt });
+                    onStep?.({
+                        step,
+                        entry,
+                        input: computed,
+                        outcome: "skipped",
+                        error,
+                        toolMissing: isMissingToolError(error) || undefined,
+                        ms: Date.now() - startedAt,
+                    });
                     // Advance past a step that cannot run, without threading anything.
                     // The frame is still left behind it: a sub-task whose last step could
                     // not run here still hands back whatever its earlier steps emitted.
@@ -558,7 +587,15 @@ export class ScenarioReplayPlan {
                 response = fallback;
                 recorded = true;
                 recordedCount += 1;
-                onStep?.({ step, entry, input: computed, outcome: "recorded", error, ms: Date.now() - startedAt });
+                onStep?.({
+                    step,
+                    entry,
+                    input: computed,
+                    outcome: "recorded",
+                    error,
+                    toolMissing: isMissingToolError(error) || undefined,
+                    ms: Date.now() - startedAt,
+                });
             }
             if (stopOnFailure && !recorded) {
                 // Judged before the output logic, which was written against a success
@@ -573,6 +610,7 @@ export class ScenarioReplayPlan {
                         outcome: "failed",
                         stage: "tool_call",
                         error: toolError,
+                        toolMissing: isMissingToolError(toolError) || undefined,
                         ms: Date.now() - startedAt,
                     });
                     entries.push({
@@ -585,6 +623,7 @@ export class ScenarioReplayPlan {
                     stopped = {
                         kind: "step_failed",
                         stepIndex: step.stepIndex,
+                        flatIndex,
                         stage: "tool_call",
                         error: toolError,
                     };
@@ -608,6 +647,7 @@ export class ScenarioReplayPlan {
                 stopped = {
                     kind: "step_failed",
                     stepIndex: step.stepIndex,
+                    flatIndex,
                     stage: "tool_output_logic",
                     error: errText(err),
                 };
@@ -627,6 +667,7 @@ export class ScenarioReplayPlan {
                     outcome: error ? "failed" : "executed",
                     stage: error ? "tool_call" : undefined,
                     error,
+                    toolMissing: isMissingToolError(error) || undefined,
                     derivedKeys,
                     ms: Date.now() - startedAt,
                 });
@@ -640,7 +681,13 @@ export class ScenarioReplayPlan {
         }
         // Every planned step ran and the plan ends in front of a parked one.
         if (!stopped && !partial && this.stopsEarly() && this.isDone()) {
-            stopped = { kind: "known_bad_step", stepIndex: this.entries[this.stopAt].stepIndex };
+            // `known_bad_step` here means "in front of the plan's end": the
+            // controller reads the served reason and names the kind (D8).
+            stopped = {
+                kind: "known_bad_step",
+                stepIndex: this.entries[this.stopAt].stepIndex,
+                flatIndex: this.stopAt,
+            };
         }
         return {
             text: assembleBundle(entries, maxChars, {

package/dist/replay/pricing.d.ts

@@ -17,7 +17,7 @@
  * Bump the version — on **every** side — whenever a row changes.
  */
 /** Identifies {@link MODEL_PRICING}. Must equal the service's constant. */
-export declare const PRICING_VERSION = "2026-08-30";
+export declare const PRICING_VERSION = "2026-09-24";
 /**
  * Tolerate provider prefixes (`anthropic/`, `us.anthropic.`), date snapshots and
  * unseen version bumps by falling back to the longest matching family, so a new

package/dist/replay/pricing.js

@@ -17,24 +17,32 @@
  * Bump the version — on **every** side — whenever a row changes.
  */
 /** Identifies {@link MODEL_PRICING}. Must equal the service's constant. */
-export const PRICING_VERSION = "2026-08-30";
-/** Cache reads bill at 0.1x input; a 5-minute cache write at 1.25x. */
-const priced = (input, output) => ({
+export const PRICING_VERSION = "2026-09-24";
+/**
+ * A 5-minute cache write bills at 1.25x input. Cache reads bill at 0.1x input,
+ * except on models whose list price says otherwise (Opus 5.5, Fable 5.1), which
+ * pass their read price in dollars.
+ */
+const priced = (input, output, cacheRead = input * 0.1) => ({
     input,
     output,
-    cacheRead: input * 0.1,
+    cacheRead,
     cacheWrite: input * 1.25,
 });
 const MODEL_PRICING = {
     "claude-haiku-4-5": priced(1.0, 5.0),
     "claude-haiku-4-5-20251001": priced(1.0, 5.0),
+    "claude-sonnet-4-5": priced(3.0, 15.0),
     "claude-sonnet-4-6": priced(3.0, 15.0),
     "claude-sonnet-5": priced(2.0, 10.0),
+    "claude-opus-4-5": priced(5.0, 25.0),
     "claude-opus-4-6": priced(5.0, 25.0),
     "claude-opus-4-7": priced(5.0, 25.0),
     "claude-opus-4-8": priced(5.0, 25.0),
     "claude-opus-5": priced(5.0, 25.0),
+    "claude-opus-5-5": priced(4.0, 20.0, 0.2),
     "claude-fable-5": priced(10.0, 50.0),
+    "claude-fable-5-1": priced(10.0, 50.0, 0.25),
 };
 /**
  * Tolerate provider prefixes (`anthropic/`, `us.anthropic.`), date snapshots and

package/dist/replay/tool-error.d.ts

@@ -20,4 +20,19 @@
  * not. `serialized` is the proxy's own serialization — the whole result, as JSON.
  */
 export declare function toolResultError(serialized: string): string | undefined;
+/**
+ * What a server says when a tool no longer exists — the one failure a grace
+ * period cannot cure (plan-services.md D8, kind 2).
+ *
+ * Read from the text, because the proxy keeps only a JSON-RPC error's message
+ * and servers word it differently: the TypeScript SDK answers `Tool X not
+ * found`, the Python SDK `Unknown tool: X`, a hand-rolled server whatever it
+ * likes. Kept narrow on purpose — `not available` is what a server says during
+ * an outage, and a repair in the middle of one is the wrong answer. A miss here
+ * costs only the wait; a false hit costs one recording and one calculation,
+ * which the service caps.
+ */
+export declare const MISSING_TOOL_PATTERN: RegExp;
+/** Whether an error text says the step's tool is gone from its server. */
+export declare function isMissingToolError(text: string | undefined): boolean;
 //# sourceMappingURL=tool-error.d.ts.map

package/dist/replay/tool-error.js

@@ -35,6 +35,23 @@ export function toolResultError(serialized) {
         return undefined;
     return clip(firstText(result.content) ?? "the tool reported an error");
 }
+/**
+ * What a server says when a tool no longer exists — the one failure a grace
+ * period cannot cure (plan-services.md D8, kind 2).
+ *
+ * Read from the text, because the proxy keeps only a JSON-RPC error's message
+ * and servers word it differently: the TypeScript SDK answers `Tool X not
+ * found`, the Python SDK `Unknown tool: X`, a hand-rolled server whatever it
+ * likes. Kept narrow on purpose — `not available` is what a server says during
+ * an outage, and a repair in the middle of one is the wrong answer. A miss here
+ * costs only the wait; a false hit costs one recording and one calculation,
+ * which the service caps.
+ */
+export const MISSING_TOOL_PATTERN = /\b(unknown|no such|unsupported|unrecognized) tool\b|\btool\s+['"`]?[\w.:-]+['"`]?\s+(was\s+)?(not found|does not exist|is not registered)\b/i;
+/** Whether an error text says the step's tool is gone from its server. */
+export function isMissingToolError(text) {
+    return typeof text === "string" && MISSING_TOOL_PATTERN.test(text);
+}
 function firstText(content) {
     if (!Array.isArray(content))
         return undefined;

package/dist/replay/types.d.ts

@@ -37,6 +37,25 @@ export interface InlinedSegment {
 }
 /** Why a call cannot run right now (segmented.md 9.9). */
 export type CallUnusable = "switched_off" | "not_ready" | "missing" | "stale" | "unresolved" | "depth" | "unsupported";
+/**
+ * A reason the plan stops in front of a step, as the service decided it
+ * (plan-services.md D8). The service knows the grace period, the retry clock
+ * and the calculation's own verdict on the step; the runner only reads it.
+ */
+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.
+     */
+    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;
+    /** For `parked` past its grace, or whose tool is gone: a repair is due. */
+    repairDue?: boolean;
+}
 export interface SerializedScenarioStep {
     stepIndex: number;
     /**
@@ -60,6 +79,15 @@ export interface SerializedScenarioStep {
      * model in front of it. Absent from an older service, which means never park.
      */
     failureCount?: number;
+    /**
+     * Why the plan must stop in front of this step, decided by the service
+     * (plan-services.md D8). Present on every step — `null` when there is no
+     * reason — from a service that decides stops itself. A parked step whose
+     * retry is due arrives with `stop: null` and is tried. Absent altogether
+     * from an older service, where `failureCount` against
+     * `fallback.maxStepFailures` is the only rule.
+     */
+    stop?: StepStop | null;
     /**
      * The literal output recorded for this step.
      *
@@ -117,6 +145,13 @@ export declare function hasTargets(schema: ParamsSchema | null | undefined): boo
 export interface SerializedScenario {
     id: string;
     runId: string;
+    /**
+     * The run the current chain was calculated from, when it is not `runId`: a
+     * plan repaired from a fresh recording (plan-services.md W2.4). A recorded
+     * output that stands in for a step comes from this run. Absent from an older
+     * service, and from a plan that was never repaired.
+     */
+    sourceRunId?: string;
     state: string;
     intent: string;
     parameters: unknown;
@@ -159,7 +194,13 @@ export type FallbackKind =
  * gone, switched off, out of date, or nested too deep (segmented.md
  * R-CALL-29). Like a known-bad step it counts nothing against any step.
  */
- | "unusable_call";
+ | "unusable_call"
+/**
+ * The plan stopped in front of a step the calculation marked
+ * non-deterministic: its input needs a judgement no code computes
+ * (plan-services.md D8, kind 3). Never tried, counts nothing.
+ */
+ | "nondeterministic_step";
 /**
  * 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
@@ -205,6 +246,12 @@ export interface ExecutionStepResult {
     /** Message only — never a tool payload; this is rendered in a web page. */
     error?: string;
     durationMs?: number;
+    /**
+     * The step's tool no longer exists on its server, read from the error text
+     * (plan-services.md D8, kind 2). The service then repairs the plan without
+     * waiting out the grace period.
+     */
+    toolMissing?: boolean;
     /**
      * The scenario this step belongs to, when it ran inside a called segment: a
      * failure is counted where a repair would happen (segmented.md R-CALL-13).

package/docs/calculatedReplayGuide.md

@@ -390,6 +390,8 @@ first prompt that states the task plainly.
 | `run_scenario` returns "no scenario is armed" | The model called it on a turn with no plan | Harmless. It happens when the model remembers the tool from an earlier turn |
 | `execution.reported … 409 invalid_ticket` | The ticket was already redeemed, or belongs to another scenario | Harmless if `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
 | `savedUsd` looks impossible | Pricing drift between the runner's table and the server's | Compare `PRICING_VERSION` on both sides. Design §11.3 documents a known live drift between two existing copies |
+| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (plan-services.md D8, kind 3) | Nothing on the runner. The agent makes that choice and finishes the task; a model step for such judgements is planned (W3.1). The journal's `plan.armed` line lists it under `stops=` |
+| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` names the kind (`step_retrying`, `step_parked … repair due`, `scenario_repairing`). To repair now by hand: `bir scenario calc <runId> --force` |
 | `sessionCostUsd` grows every prompt in a session | The per-run usage watermark is missing or not taken | Design §11.4. Reports without a mark must carry `measured: false` |
 | Everything works, nothing is saved | A replayed turn is deliberately not recorded (design §12) | Correct. The matched run stays canonical and its `iterations` is bumped |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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",