@basein/runner 0.2.0 → 0.2.2

package/dist/replay/controller.js

@@ -18,13 +18,15 @@ import { serializeCapped } from "../record/truncate.js";
 import { logDetail, logLine, errText } from "../util/log.js";
 import { MAX_REPLAY_REASON } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
-import { deriveParameters } from "./derive.js";
+import { deriveParameters, } from "./derive.js";
+import { buildHandoverNote } from "./handover.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { PRICING_VERSION } from "./pricing.js";
 import { SourceRunOutputs } from "./source-run.js";
+import { clampToFrameStart, flattenChain, } from "./flatten.js";
 import { toolResultError } from "./tool-error.js";
-import { OUTCOME_RANK, isReadyScenario, } from "./types.js";
+import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
 export const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
 /** How long a `/proxy/poll` is held open before it answers empty. */
@@ -35,6 +37,12 @@ export const DEFAULT_BUDGETS = {
     planMs: 120_000,
     stepMs: 60_000,
 };
+export const DEFAULT_INTENT_MATCH = {
+    enabled: true,
+    budgetMs: 4_000,
+    maxPerTurn: 3,
+    maxRequestsPerTurn: 40,
+};
 /** How many step verdicts one report carries. A chain longer than this is not
  *  a chain anybody is reading step by step, and the report has to stay small. */
 const MAX_STEP_RESULTS = 200;
@@ -44,11 +52,23 @@ export class ReplayController {
     enabled;
     work = new ProxyWorkQueue();
     budgets;
+    intentMatch;
     opts;
     constructor(opts) {
         this.opts = opts;
         this.enabled = opts.enabled;
         this.budgets = { ...DEFAULT_BUDGETS, ...(opts.budgets ?? {}) };
+        this.intentMatch = { ...DEFAULT_INTENT_MATCH, ...(opts.intentMatch ?? {}) };
+    }
+    /**
+     * 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).
+     */
+    get segmentArm() {
+        return this.opts.segmentArm === true;
     }
     /** The plan's own delivery vehicle is never a scenario step. */
     isDirectTool(toolName) {
@@ -86,7 +106,7 @@ export class ReplayController {
      * baseline sample to contribute, and losing that is how a savings ledger ends
      * up with a denominator nobody measured.
      */
-    arm(match, prompt, wrapped) {
+    async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}) {
         const state = {
             scenarioId: match.scenarioId,
             ticket: match.executionTicket,
@@ -104,40 +124,159 @@ export class ReplayController {
             armedAt: Date.now(),
             reported: false,
             retired: false,
+            armedBy,
+            // An older server sends no `kind`, and a whole-run scenario is the safe
+            // reading: it is what every hand-out was before segments existed.
+            kind: match.kind ?? "scenario",
+            segment: match.segment,
+            key: match.key,
+            verified: match.verified,
+            sharedWith: [],
         };
-        const decline = (why) => {
+        // A segment is judged against its own gate, and a `same` verdict stands in
+        // for the score (segmented.md R-OUT-11): the question was asked *because*
+        // the score sat below the threshold, so a numeric gate would decline every
+        // verified hand-out.
+        const isSegment = state.kind === "segment";
+        const threshold = isSegment
+            ? (this.opts.minSegmentSimilarity ?? 0.95)
+            : this.opts.minSimilarity;
+        const decline = (why, code) => {
+            state.declined = code;
             logLine("replay.decision", {
                 verdict: "no-steer",
                 run: match.runId,
                 scenario: match.scenarioId ?? undefined,
                 similarity: match.similarity.toFixed(3),
-                threshold: this.opts.minSimilarity,
+                threshold,
+                kind: state.kind,
+                key: state.key,
+                verified: state.verified?.verdict,
                 why,
             });
             return state;
         };
+        // The server never sends a segment to a runner that did not ask for one
+        // (R-OUT-9). One arriving anyway is declined here rather than run: an
+        // observe-only period that quietly armed something would be worthless.
+        if (isSegment && !this.segmentArm) {
+            return decline("segment hand-out while BIR_SEGMENT_ARM is off", "replay_disabled");
+        }
         // Gate 2 — replay enabled.
         if (!this.enabled)
-            return decline("BIR_REPLAY is not set");
+            return decline("BIR_REPLAY is not set", "replay_disabled");
         // Gate 3 — a ready scenario with steps.
         const scenario = match.scenario;
         if (!match.scenarioId || !isReadyScenario(scenario)) {
-            return decline(match.scenarioId ? "scenario is not ready" : "no scenario for the matched run");
+            return decline(match.scenarioId ? "scenario is not ready" : "no scenario for the matched run", "not_ready");
         }
         // Gate 4 — similarity. Detection decides "don't record this again"; steering
         // decides "don't think about this again", which is a much stronger claim and
         // deserves a stronger threshold.
-        if (match.similarity < this.opts.minSimilarity) {
-            return decline("similarity below threshold");
+        //
+        // For a segment, a `same` verdict from the live question stands in for the
+        // score (R-OUT-11). Only `same` ever reaches a runner with a ticket, so it
+        // is the only verdict this sees.
+        const scoreOk = match.similarity >= threshold;
+        const verifiedOk = isSegment && match.verified?.verdict === "same";
+        if (!scoreOk && !verifiedOk) {
+            return decline("similarity below threshold", "similarity");
         }
-        // Gate 5 — tool coverage.
-        const mode = modeFor(scenario.steps, wrapped, this.opts.allowServers);
+        // Flatten the chain before the remaining gates, so every one of them judges
+        // the steps that will *really* run — the caller's own and, in order, those
+        // of every segment it calls (segmented.md R-CALL-29, R-CALL-30).
+        let flat;
+        try {
+            flat = flattenChain(scenario, {
+                range: match.segment
+                    ? { stepFrom: match.segment.stepFrom, stepTo: match.segment.stepTo }
+                    : null,
+            });
+        }
+        catch (err) {
+            // A payload we cannot lay out is a payload we cannot run. It costs the
+            // turn nothing: the agent does the task (R-FALL-12).
+            logLine("replay.flatten_failed", { scenario: scenario.id, error: errText(err) });
+            return decline("the chain could not be flattened", "flatten_failed");
+        }
+        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);
+        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 planned = stopAt === undefined ? entries : entries.slice(0, stopAt);
+        // Gate 6 — tool coverage, over the steps that will actually run.
+        const mode = modeFor(planned.map((e) => e.step), wrapped, this.opts.allowServers);
         if (mode === "none")
-            return decline("no step is executable");
-        const params = this.startDerivation(scenario, prompt, state);
-        state.plan = new ScenarioReplayPlan({ scenario, params, mode });
+            return decline("no step is executable", "coverage");
+        const derivation = this.startDerivation(scenario, prompt, state, ctx);
+        const params = derivation.then((r) => r.params);
+        // `params` is awaited by the plan, and by gate 7 below when there is a
+        // target. Without this, the losing race in gate 7 leaves `derivation`
+        // rejected and unhandled, which takes the process down on an unhandled
+        // rejection rather than declining one plan.
+        params.catch(() => undefined);
+        // Gate 7 — targets (segmented.md R-PARAM-3, R-PARAM-4). The last gate,
+        // because it is the only one that spends a model call and waits. A scenario
+        // whose parameters are all settings arms at once, as before: there is
+        // nothing the turn has to supply.
+        if (hasTargets(scenario.paramsObject)) {
+            let result;
+            try {
+                result = await this.withBudget(derivation, this.budgets.deriveMs, "derivation");
+            }
+            catch (err) {
+                // Out of budget, or the call threw. Either way the turn has not said
+                // what this task is to act on, and running it would act on something
+                // else (R-PARAM-3).
+                const first = firstTargetKey(scenario.paramsObject);
+                return decline(`target ${first ?? "(unknown)"} not found — ${errText(err)}`, "missing_target");
+            }
+            if (!result.derived) {
+                // Nobody read the turn — no key here and no service to ask, or the
+                // service declined. Settings can still take their recorded values, but a
+                // target is a guess nobody is allowed to make (R-PARAM-5). The reason
+                // travels into the line, because "it did not run" without one is how
+                // this stayed invisible before.
+                const first = firstTargetKey(scenario.paramsObject);
+                return decline(`${result.reason ?? "no_derive_key"}: target ${first ?? "(unknown)"}`, "no_derive_key");
+            }
+            if (result.missing.length > 0) {
+                return decline(`target ${result.missing[0]} not found`, "missing_target");
+            }
+        }
+        // A plan armed by intent runs inside a task the agent is already doing, so
+        // its directive and its bundles say "continue", never "answer the user"
+        // (segmented.md R-OUT-13).
+        state.plan = new ScenarioReplayPlan({
+            scenario,
+            params,
+            mode,
+            stopAt,
+            entries,
+            subTask: armedBy === "intent",
+        });
         state.mode = mode;
-        state.stepsPlanned = scenario.steps.length;
+        state.stepsPlanned = entries.length;
+        // Why the plan stops, when a call is what stops it: the note names the
+        // sub-task rather than a tool (R-CALL-36).
+        state.flatStop =
+            typeof stopAt === "number" && flat.stopAt !== undefined && stopAt <= flat.stopAt
+                ? flat.stopReason
+                : undefined;
         if (this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
@@ -151,16 +290,54 @@ export class ReplayController {
             run: match.runId,
             scenario: scenario.id,
             mode,
-            steps: scenario.steps.length,
+            steps: entries.length,
+            stopsAt: stopAt,
+            by: armedBy === "intent" ? "intent" : undefined,
+            kind: state.kind,
+            key: state.key,
+            verified: state.verified?.verdict,
             similarity: match.similarity.toFixed(3),
-            coverage: coverageOf(scenario.steps, wrapped, this.opts.allowServers).join(","),
-            tools: scenario.steps.map((s) => s.toolName).join(","),
+            // What this chain calls, and what answers each call right now (R-CALL-32).
+            calls: callLines(scenario),
+            unusable: flat.stopReason?.reason,
+            coverage: coverageOf(entries.map((e) => e.step), wrapped, this.opts.allowServers).join(","),
+            tools: entries.map((e) => e.step.toolName ?? "").join(","),
         });
         return state;
     }
     /** The directive to inject via `additionalContext`, or undefined when declined. */
     directiveFor(state) {
-        return state.plan?.steeringDirective(DIRECT_TOOL_NAME);
+        return state.plan?.steeringDirective(DIRECT_TOOL_NAME, {
+            subTask: state.armedBy === "intent",
+        });
+    }
+    /**
+     * A hand-over note not yet delivered, claimed for delivery (fallbk.md D4).
+     * Returns it once and marks it delivered; undefined when there is none.
+     */
+    takeNote(state) {
+        const h = state?.handover;
+        if (!h || h.delivered)
+            return undefined;
+        h.delivered = true;
+        logDetail("replay.handover_delivered", {
+            scenario: state.scenarioId ?? undefined,
+            bytes: h.note.length,
+        });
+        return h.note;
+    }
+    /**
+     * Deliver text to the model in place of the tool call it was about to make:
+     * as genuine command output for `Bash`, as the denial reason otherwise — the
+     * two channels a divergence bundle already uses.
+     */
+    deliverInstead(text, toolName) {
+        if (toolName === "Bash") {
+            const delimiter = "BIR_EOF";
+            const safe = text.split(delimiter).join("BIR_EOF_");
+            return { kind: "bash", command: `cat <<'${delimiter}'\n${safe}\n${delimiter}` };
+        }
+        return { kind: "deny", reason: text };
     }
     /**
      * `PreToolUse`, while a plan is active.
@@ -210,6 +387,11 @@ export class ReplayController {
                 // step and will throw on the same logic — and its own report would then
                 // be the only trace, attributed to a re-execution rather than to the
                 // steered call that actually hit it first.
+                //
+                // Not a divergence any more (fallbk.md): recovering by executing the
+                // rest would start at this very step and throw on the same logic. The
+                // step is recorded as failed, and the task is handed to the model with
+                // a note, delivered in place of this call.
                 const step = plan.currentStep();
                 if (step) {
                     this.recordStep(state, {
@@ -218,8 +400,18 @@ export class ReplayController {
                         stage: "tool_input_logic",
                         error: errText(err),
                     });
+                    this.handOver(state, {
+                        kind: "step_failed",
+                        step,
+                        position: plan.currentStepIndex,
+                        error: errText(err),
+                        delivery: "above",
+                    });
+                    const note = this.takeNote(state);
+                    if (note)
+                        return this.deliverInstead(note, toolName);
                 }
-                return await this.diverge(state, toolName, `toolInputLogic threw: ${errText(err)}`);
+                return { kind: "abort" };
             }
         }
         // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`.
@@ -270,8 +462,22 @@ export class ReplayController {
                     error: errText(err),
                     ms: Date.now() - pin.pinnedAt,
                 });
+                // The tool ran, so the step's call and result are in front of the model;
+                // what failed is threading its output into the plan. The rest is the
+                // model's (fallbk.md). `stepsPinned` counts it: its work happened.
+                state.stepsPinned += 1;
+                this.handOver(state, {
+                    kind: "step_failed",
+                    step,
+                    position: pin.stepIndex,
+                    error: errText(err),
+                    delivery: "above",
+                    ranThisStep: true,
+                });
+            }
+            else {
+                this.retire(state, "failed");
             }
-            this.retire(state, "failed");
             return false;
         }
         // One more step ran under the plan. Counted here, as each pin threads, and
@@ -293,7 +499,15 @@ export class ReplayController {
             };
             this.logStep(info);
             this.recordStep(state, info);
-            this.retire(state, "failed");
+            // Uncount it: it was counted above as threaded, but its work did not happen.
+            state.stepsPinned -= 1;
+            this.handOver(state, {
+                kind: "step_failed",
+                step,
+                position: pin.stepIndex,
+                error: toolError,
+                delivery: "above",
+            });
             return false;
         }
         if (step) {
@@ -310,9 +524,25 @@ export class ReplayController {
             emitted: derivedKeys.join(",") || undefined,
             done,
         });
+        if (done && plan.stopsEarly()) {
+            // Every planned step ran, and the next one is parked (fallbk.md D3) — or
+            // 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",
+                step: parked,
+                entry: plan.stopEntry(),
+                position: plan.stepCount,
+                delivery: "above",
+            });
+            return true;
+        }
         if (done) {
             this.upgrade(state, "steered_full");
-            this.retire(state, undefined);
+            // A completing retire: the last step threaded and the plan's work is over
+            // (segmented.md R-MONEY-3). Everything the agent spends after this is the
+            // agent's own, not this plan's.
+            this.retire(state, undefined, true);
             logLine("replay.done", {
                 scenario: state.scenarioId ?? undefined,
                 mode: state.mode,
@@ -354,7 +584,7 @@ export class ReplayController {
         const deadline = Date.now() + this.budgets.planMs;
         let result;
         try {
-            result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), deadline);
+            result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true });
         }
         catch (err) {
             // The scenario's own logic failed. Retire and let the model do the work.
@@ -366,6 +596,37 @@ export class ReplayController {
             this.retire(state, "failed");
             return { ok: false, why: "not_ready" };
         }
+        // The plan stopped part-way (fallbk.md §Runner 3): a step broke, or the
+        // next one is parked. The steps that ran are real, so their bundle goes to
+        // the model — behind a note saying the rest of the task is its own.
+        if (result.stopped) {
+            const stop = result.stopped;
+            const ranOk = result.executed + result.recorded - result.errored;
+            state.stepsPinned += Math.max(0, ranOk);
+            const position = stop.flatIndex ?? plan.stepCount;
+            const step = plan.allSteps()[position];
+            this.handOver(state, {
+                kind: stop.kind,
+                step,
+                entry: plan.allEntries()[position],
+                position,
+                error: stop.error,
+                delivery: "below",
+            });
+            const note = this.takeNote(state) ?? state.handover?.note ?? "";
+            if (result.executed + result.recorded === 0) {
+                // Nothing ran: there is no bundle, only the task. The tool answers with
+                // an error that says so, which is what a model reacts to best.
+                return { ok: false, why: note };
+            }
+            return {
+                ok: true,
+                text: `${note}\n\n${result.text}`,
+                responseModel: {},
+                steps: result.executed + result.recorded,
+                partial: result.partial,
+            };
+        }
         state.stepsPinned += result.executed + result.recorded;
         let responseModel = {};
         try {
@@ -382,7 +643,10 @@ export class ReplayController {
             : result.partial || result.skipped > 0
                 ? "diverged"
                 : "steered_full");
-        this.retire(state, undefined);
+        // `runToCompletion` returned without a stop: the plan ran to its end, so
+        // this is a completing retire (R-MONEY-3). The stopped path handed over
+        // above and took no mark.
+        this.retire(state, undefined, true);
         logLine("replay.done", {
             scenario: state.scenarioId ?? undefined,
             mode: state.mode,
@@ -445,6 +709,23 @@ export class ReplayController {
             errorStage: blame?.stage,
             errorStepIndex: blame?.stepIndex,
             errorToolName: blame?.toolName,
+            // 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.
+            fallbackStepIndex: state.outcome === "fell_back" ? state.handover?.stepIndex : undefined,
+            fallbackKind: state.outcome === "fell_back" ? state.handover?.kind : undefined,
+            // Segments of this plan's recording that armed later in the turn
+            // (segmented.md R-MONEY-4): their share comes off this plan's baseline.
+            sharedWith: state.sharedWith.length > 0 ? [...state.sharedWith] : undefined,
+            // A turn in which another plan ran is not a measurement of what this task
+            // costs unaided, so it is no baseline sample (segmented.md R-MONEY-5).
+            // This covers two plans that both armed, and — the case that was silently
+            // wrong before — a declined prompt scenario followed by an intent-armed
+            // plan, whose "baseline" was really the turn cut short at the second arm.
+            // A lone plan, armed or declined, sends nothing: the default is eligible.
+            baselineEligible: d.siblings?.some((s) => s !== state && s.plan !== undefined)
+                ? false
+                : undefined,
         };
     }
     /**
@@ -476,7 +757,18 @@ export class ReplayController {
     async runAdHoc(scenario, prompt, wrapped) {
         if (!isReadyScenario(scenario))
             return { ok: false, why: "scenario is not ready" };
-        const mode = modeFor(scenario.steps, wrapped, this.opts.allowServers);
+        // A chain with calls is run by hand the same way it is run by a match: one
+        // flat list, one frame per call (segmented.md R-CALL-37).
+        let flat;
+        try {
+            flat = flattenChain(scenario);
+        }
+        catch (err) {
+            return { ok: false, why: `the chain could not be flattened: ${errText(err)}` };
+        }
+        if (flat.entries.length === 0)
+            return { ok: false, why: "the chain has no runnable step" };
+        const mode = modeFor(flat.entries.map((e) => e.step), wrapped, this.opts.allowServers);
         if (mode === "none")
             return { ok: false, why: "no step is executable" };
         const state = {
@@ -497,10 +789,43 @@ export class ReplayController {
             // an ad-hoc run anyway.
             reported: true,
             retired: false,
+            armedBy: "prompt",
+            // `bir replay` runs a scenario an operator named by id: never a segment
+            // hand-out, and nothing to share a baseline with.
+            kind: "scenario",
+            sharedWith: [],
         };
-        const params = this.startDerivation(scenario, prompt, state);
-        const plan = new ScenarioReplayPlan({ scenario, params, mode });
+        // `bir replay` keeps its own contract on a missing target (segmented.md
+        // R-CALL-37): an operator asked for this run by id, so a sample stands in
+        // and it never declines. It says which, as the console's dry replay does
+        // (R-PARAM-7), so nobody reads the output as proof the values were derived.
+        const schema = scenario.paramsObject ?? {};
+        const params = this.startDerivation(scenario, prompt, state).then((r) => {
+            const out = { ...r.params };
+            const fromSamples = [];
+            for (const key of Object.keys(schema)) {
+                if (out[key] !== null && out[key] !== undefined)
+                    continue;
+                out[key] = schema[key].sampleValue;
+                fromSamples.push(key);
+            }
+            if (fromSamples.length > 0) {
+                logLine("replay.derived", {
+                    scenario: scenario.id,
+                    why: `targets from samples: ${fromSamples.join(", ")}`,
+                });
+            }
+            return out;
+        });
+        const plan = new ScenarioReplayPlan({
+            scenario,
+            params,
+            mode,
+            entries: flat.entries,
+            stopAt: flat.stopAt,
+        });
         state.plan = plan;
+        state.flatStop = flat.stopReason;
         if (this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
@@ -524,11 +849,11 @@ export class ReplayController {
         }
         const trace = [];
         try {
-            const result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, (info) => {
+            const result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, (info) => {
                 this.observeStep(state)(info);
                 trace.push({
                     step: info.step.stepIndex,
-                    tool: info.step.toolName,
+                    tool: info.step.toolName ?? "",
                     input: info.input,
                     outcome: info.outcome,
                     ms: info.ms,
@@ -564,14 +889,35 @@ export class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
-    startDerivation(scenario, prompt, state) {
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    deriveService(scenarioId) {
+        const token = this.opts.authToken?.();
+        if (!this.opts.authUrl || !token)
+            return undefined;
+        return { baseUrl: this.opts.authUrl, token, scenarioId };
+    }
+    startDerivation(scenario, prompt, state, ctx = {}) {
         const derive = this.opts.deriveImpl ?? deriveParameters;
         return derive({
             prompt,
             intent: scenario.intent ?? "",
             paramsObject: scenario.paramsObject,
             apiKey: this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+            // Where to ask when there is no key here, which is the ordinary case
+            // (segmented.md R-PARAM-5).
+            service: this.deriveService(scenario.id),
             fetchImpl: this.opts.fetchImpl,
+            liveCall: ctx.liveCall,
+            recentResults: ctx.recentResults,
         })
             .then((r) => {
             state.deriveCostUsd += r.costUsd;
@@ -579,21 +925,42 @@ export class ReplayController {
                 scenario: scenario.id,
                 params: Object.keys(r.params).length,
                 costUsd: r.costUsd.toFixed(4),
-                source: r.derived ? "prompt" : "recorded samples",
+                source: r.derived
+                    ? r.via === "service"
+                        ? "the service"
+                        : "prompt"
+                    : "recorded samples",
+                why: r.derived ? undefined : r.reason,
+                missing: r.missing.length > 0 ? r.missing.join(",") : undefined,
+                sampled: r.sampled.length > 0 ? r.sampled.join(",") : undefined,
             });
-            return r.params;
+            return r;
         })
             .catch((err) => {
             logLine("replay.derive_failed", {
                 scenario: scenario.id,
-                why: "falling back to the scenario's recorded sample values",
+                why: "settings fall back to their recorded samples; a target does not",
                 error: errText(err),
             });
+            // A throw is a missing target when the scenario has one: gate 7 rethrows
+            // on `missing`, and this shape says so without the caller having to know
+            // whether the failure was a timeout or a 500. Settings still take their
+            // samples, so an all-settings scenario is unaffected by a broken key.
+            const schema = scenario.paramsObject ?? {};
             const fallback = {};
-            for (const [key, entry] of Object.entries(scenario.paramsObject ?? {})) {
-                fallback[key] = entry.sampleValue;
+            const missing = [];
+            const sampled = [];
+            for (const [key, entry] of Object.entries(schema)) {
+                if (entry?.kind === "setting") {
+                    fallback[key] = entry.sampleValue;
+                    sampled.push(key);
+                }
+                else {
+                    fallback[key] = null;
+                    missing.push(key);
+                }
             }
-            return fallback;
+            return { params: fallback, costUsd: 0, derived: true, missing, sampled };
         });
     }
     /**
@@ -616,7 +983,9 @@ export class ReplayController {
         this.retire(state, undefined);
         let composed;
         try {
-            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state));
+            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), 
+            // A parked step ends the bundle short of the task (fallbk.md D3).
+            { handover: plan.stopsEarly() });
         }
         catch (err) {
             this.upgrade(state, "failed");
@@ -653,17 +1022,110 @@ export class ReplayController {
             // Nothing survived; a bundle of nothing is worse than no bundle.
             return { kind: "abort" };
         }
+        // The bundle stops in front of a parked step: say so ahead of it, and the
+        // model carries on from there. The outcome stays `diverged` — the model
+        // went off-script first — so the report carries no fallback fields.
+        let text = composed.text;
+        if (plan.stopsEarly()) {
+            const parked = plan.stopStep();
+            const stopKind = state.flatStop ? "unusable_call" : "known_bad_step";
+            state.handover = {
+                kind: stopKind,
+                stepIndex: parked.stepIndex,
+                toolName: parked.toolName ?? undefined,
+                note: this.noteFor(state, {
+                    kind: stopKind,
+                    step: parked,
+                    entry: plan.stopEntry(),
+                    position: plan.stepCount,
+                    delivery: "below",
+                }),
+                delivered: true,
+            };
+            text = `${state.handover.note}\n\n${composed.text}`;
+        }
         // Bash-clean delivery: the model reaches for `Bash` when it cannot call a
         // scripted tool, and a genuine command output is trusted where a `deny`
         // reason is read as adversarial interception. Neutralise the delimiter first.
-        if (toolName === "Bash") {
-            const delimiter = "BIR_EOF";
-            const safe = composed.text.split(delimiter).join("BIR_EOF_");
-            logDetail("replay.inject", { channel: "bash", bytes: composed.text.length });
-            return { kind: "bash", command: `cat <<'${delimiter}'\n${safe}\n${delimiter}` };
+        const action = this.deliverInstead(text, toolName);
+        logDetail("replay.inject", { channel: action.kind, bytes: text.length });
+        return action;
+    }
+    /**
+     * Hand the rest of the task to the model (fallbk.md D4/D5).
+     *
+     * Retires the plan and builds the note; delivery is the caller's, because the
+     * channel depends on the hook that noticed. The outcome is `fell_back` when at
+     * least one step did its work under the plan, and `failed` when none did — a
+     * scenario that did nothing has nothing to book, and is a baseline sample.
+     */
+    handOver(state, h) {
+        if (state.handover)
+            return;
+        const ran = state.stepsPinned;
+        this.retire(state, ran > 0 ? "fell_back" : "failed");
+        state.handover = {
+            kind: h.kind,
+            // The *caller's* index: a fragment opens at the call row, not at a step
+            // number the caller's own chain does not have (R-CALL-32, R-FALL-7).
+            stepIndex: callerStepIndexOf(h.entry) ?? h.step?.stepIndex ?? h.position,
+            toolName: h.step?.toolName ?? undefined,
+            error: h.error,
+            note: this.noteFor(state, h),
+            delivered: false,
+        };
+        logLine("replay.handover", {
+            scenario: state.scenarioId ?? undefined,
+            kind: h.kind,
+            step: `${h.position}/${state.plan?.totalSteps ?? state.stepsPlanned}`,
+            tool: h.step?.toolName ?? undefined,
+            // The scenario that owns the stopped step, when it is not the matched one.
+            owner: h.entry && h.entry.depth > 0 ? h.entry.scenarioId : undefined,
+            unusable: state.flatStop?.reason,
+            callIntent: state.flatStop?.callIntent ?? undefined,
+            segment: state.flatStop?.segmentId ?? undefined,
+            ran,
+            outcome: state.outcome,
+            why: 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"
+                    : "a step broke — the agent continues from here",
+        });
+    }
+    noteFor(state, h) {
+        const plan = state.plan;
+        const executed = h.ranThisStep ? h.position + 1 : h.position;
+        let params;
+        try {
+            params = plan?.parameters;
+        }
+        catch {
+            params = undefined;
         }
-        logDetail("replay.inject", { channel: "deny", bytes: composed.text.length });
-        return { kind: "deny", reason: composed.text };
+        return buildHandoverNote({
+            intent: plan?.intent ?? "",
+            kind: h.kind,
+            stepIndex: h.position,
+            stepToolName: h.step?.toolName ?? undefined,
+            failureCount: h.step?.failureCount,
+            error: h.error,
+            unusable: state.flatStop
+                ? {
+                    reason: state.flatStop.reason,
+                    callIntent: state.flatStop.callIntent,
+                    segmentId: state.flatStop.segmentId,
+                    ownerScenarioId: state.flatStop.scenarioId,
+                }
+                : undefined,
+            ownerScenarioId: h.entry && h.entry.depth > 0 ? h.entry.scenarioId : undefined,
+            inSubTask: h.entry && h.entry.depth > 0 ? (h.entry.frame.callIntent ?? null) : null,
+            executed: Math.max(0, Math.min(executed, plan?.totalSteps ?? executed)),
+            totalSteps: plan?.totalSteps ?? state.stepsPlanned,
+            remainingTools: plan ? plan.toolsFrom(h.ranThisStep ? h.position + 1 : h.position) : [],
+            params,
+            delivery: h.delivery,
+        });
     }
     /**
      * The executor handed to a plan: dispatch a step to the proxy that owns its
@@ -675,9 +1137,10 @@ export class ReplayController {
      */
     executeStep() {
         return async (step, input) => {
-            const mcp = parseQualifiedName(step.toolName);
-            if (!mcp)
+            const mcp = parseQualifiedName(step.toolName ?? "");
+            if (!mcp) {
                 throw new Error(`${step.toolName} is not an MCP tool — it can only run in the session`);
+            }
             const result = await this.work.call(mcp.serverName, mcp.toolName, input, this.budgets.stepMs);
             // Serialize exactly as the proxy records it, or `toolOutputLogic` — which
             // was authored against that shape — silently derives nothing (§7.2).
@@ -697,7 +1160,7 @@ export class ReplayController {
      * hook's differently-shaped view would derive nothing at all.
      */
     reachFor(state, step) {
-        return reachOf(step.toolName, state.wrapped);
+        return reachOf(step.toolName ?? "", state.wrapped);
     }
     /**
      * Log a step and remember its verdict, in that order.
@@ -715,7 +1178,13 @@ export class ReplayController {
     /** Upsert one step's verdict. Later news about a step replaces earlier news. */
     recordStep(state, info) {
         const status = info.outcome === "executed" ? "ok" : info.outcome;
-        if (state.stepResults.size >= MAX_STEP_RESULTS && !state.stepResults.has(info.step.stepIndex)) {
+        // Keyed by the *flat* position, not by the step's own index: two scenarios
+        // in one plan both have a step 0, and one would otherwise overwrite the
+        // other's verdict (segmented.md R-CALL-13).
+        const key = info.entry
+            ? `${info.entry.scenarioId}#${info.entry.stepIndex}`
+            : `#${info.step.stepIndex}`;
+        if (state.stepResults.size >= MAX_STEP_RESULTS && !state.stepResults.has(key)) {
             return;
         }
         const error = info.error
@@ -723,29 +1192,35 @@ export class ReplayController {
                 ? `${info.error.slice(0, MAX_STEP_ERROR_CHARS)}…`
                 : info.error
             : undefined;
-        state.stepResults.set(info.step.stepIndex, {
+        state.stepResults.set(key, {
             stepIndex: info.step.stepIndex,
-            toolName: info.step.toolName,
+            toolName: info.step.toolName ?? "",
             status,
             // A stage is only meaningful when something went wrong. `skipped` broke at
             // the call itself — its tool could not run here.
             stage: info.stage ?? (status === "skipped" ? "tool_call" : undefined),
             error,
             durationMs: info.ms,
+            // 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,
+            chainRevision: info.entry && info.entry.depth > 0 ? info.entry.frame.chainRevision : undefined,
         });
     }
     /** The step verdicts, in chain order, for the execution report. */
     stepResultsOf(state) {
         if (state.stepResults.size === 0)
             return undefined;
-        return [...state.stepResults.values()].sort((a, b) => a.stepIndex - b.stepIndex);
+        return [...state.stepResults.values()];
     }
     logStep(info) {
-        const mcp = parseQualifiedName(info.step.toolName);
+        const mcp = parseQualifiedName(info.step.toolName ?? "");
         if (info.outcome === "failed") {
             logLine("replay.step_failed", {
                 n: info.step.stepIndex,
-                tool: info.step.toolName,
+                scenario: info.entry && info.entry.depth > 0 ? info.entry.scenarioId : undefined,
+                frame: info.entry?.frame.id,
+                tool: info.step.toolName ?? undefined,
                 stage: info.stage,
                 why: info.stage === "tool_call"
                     ? "its tool ran and reported an error — the step's work did not happen"
@@ -786,9 +1261,22 @@ export class ReplayController {
         if (OUTCOME_RANK[outcome] > OUTCOME_RANK[state.outcome])
             state.outcome = outcome;
     }
-    retire(state, outcome) {
+    retire(state, outcome, completing = false) {
         if (outcome)
             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.
+            }
+        }
         state.retired = true;
         state.pinned.clear();
     }
@@ -804,4 +1292,45 @@ export class ReplayController {
         });
     }
 }
+/** The first target of a schema, for the sentence a decline logs. */
+function firstTargetKey(schema) {
+    if (!schema)
+        return undefined;
+    return Object.keys(schema).find((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).
+ *
+ * A step inside a called segment has no position in the caller's own chain; the
+ * call row that opened its frame does. Reporting the segment's own index would
+ * line the execution up against a step the caller's card does not have.
+ */
+function callerStepIndexOf(entry) {
+    if (!entry || entry.depth === 0)
+        return entry?.stepIndex;
+    let frame = entry.frame;
+    while (frame.parent && frame.depth > 1)
+        frame = frame.parent;
+    return frame.callerStepIndex;
+}
+/** The calls in a served chain, for the `plan.armed` line (R-CALL-32). */
+function callLines(scenario) {
+    const calls = (scenario.steps ?? []).filter((s) => s.kind === "segment");
+    if (calls.length === 0)
+        return undefined;
+    return calls
+        .map((s) => `${s.segmentId ?? "-"}:${s.unusable ?? s.resolution?.state ?? "resolved"}`)
+        .join(",");
+}
+export function knownBadStepIndex(steps, maxStepFailures) {
+    if (typeof maxStepFailures !== "number" || !Number.isFinite(maxStepFailures))
+        return undefined;
+    const i = steps.findIndex((s) => (s.failureCount ?? 0) > maxStepFailures);
+    return i < 0 ? undefined : i;
+}
 //# sourceMappingURL=controller.js.map