@basein/runner 0.3.22 → 0.3.23

package/dist/bin/bir-hooks.d.ts

@@ -109,6 +109,11 @@
  *                             call. Unset (or 0) is off: no probe is sent and
  *                             nothing arms mid-turn
  *   BIR_INTENT_ARM_BUDGET_MS  how long a call waits for that probe (default 500)
+ *   BIR_CONTINUATIONS         0 stops asking, after a plan handed over, for the
+ *                             plan of the work recorded after an earlier
+ *                             hand-over at that step (default on: one request
+ *                             per hand-over; it runs only when the agent's next
+ *                             call is its first step)
  *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40)
  *   BIR_INTENT_MATCH_BUDGET_MS  one intent probe's own ceiling (default 1500)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (unset: the

package/dist/bin/bir-hooks.js

@@ -109,6 +109,11 @@
  *                             call. Unset (or 0) is off: no probe is sent and
  *                             nothing arms mid-turn
  *   BIR_INTENT_ARM_BUDGET_MS  how long a call waits for that probe (default 500)
+ *   BIR_CONTINUATIONS         0 stops asking, after a plan handed over, for the
+ *                             plan of the work recorded after an earlier
+ *                             hand-over at that step (default on: one request
+ *                             per hand-over; it runs only when the agent's next
+ *                             call is its first step)
  *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40)
  *   BIR_INTENT_MATCH_BUDGET_MS  one intent probe's own ceiling (default 1500)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (unset: the

package/dist/control/pin-guard.d.ts

@@ -85,4 +85,20 @@ export declare function commandShape(command: string, depth?: number, escape?: s
  * only the general rule is applied there.
  */
 export declare function pinCompatible(toolName: string, modelArgs: unknown, pinnedArgs: unknown, otherHost?: boolean): PinVerdict;
+/**
+ * Whether the model's own call is a continuation's first step: the same call,
+ * not only the same kind of call (the service's fallbk.md Part 3).
+ *
+ * Stricter than {@link pinCompatible}, on purpose. A pin takes a call the
+ * model was told to make — the directive named the step — and one argument in
+ * common is enough to know it is that call. A continuation starts on a call
+ * nobody told the model to make: after a hand-over, the call is the model's
+ * own choice of what to do next, and the plan may run only when that choice
+ * is the one the recording made. Looking up another person, restarting
+ * another worker, reading another file is another choice. So the call must
+ * pass the pin guard, share at least one argument with the step, and hold
+ * the same value in every argument they share — text compared without
+ * surrounding space or letter case, anything else exactly.
+ */
+export declare function sameFirstCall(toolName: string, modelArgs: unknown, stepArgs: unknown): PinVerdict;
 //# sourceMappingURL=pin-guard.d.ts.map

package/dist/control/pin-guard.js

@@ -545,4 +545,40 @@ export function pinCompatible(toolName, modelArgs, pinnedArgs, otherHost = false
         ? { ok: true }
         : { ok: false, why: "it shares no argument with the step" };
 }
+/**
+ * Whether the model's own call is a continuation's first step: the same call,
+ * not only the same kind of call (the service's fallbk.md Part 3).
+ *
+ * Stricter than {@link pinCompatible}, on purpose. A pin takes a call the
+ * model was told to make — the directive named the step — and one argument in
+ * common is enough to know it is that call. A continuation starts on a call
+ * nobody told the model to make: after a hand-over, the call is the model's
+ * own choice of what to do next, and the plan may run only when that choice
+ * is the one the recording made. Looking up another person, restarting
+ * another worker, reading another file is another choice. So the call must
+ * pass the pin guard, share at least one argument with the step, and hold
+ * the same value in every argument they share — text compared without
+ * surrounding space or letter case, anything else exactly.
+ */
+export function sameFirstCall(toolName, modelArgs, stepArgs) {
+    const verdict = pinCompatible(toolName, modelArgs, stepArgs);
+    if (!verdict.ok)
+        return verdict;
+    const model = record(modelArgs);
+    const step = record(stepArgs);
+    const shared = Object.keys(model).filter((key) => Object.prototype.hasOwnProperty.call(step, key));
+    if (shared.length === 0) {
+        return stableStringify(model) === stableStringify(step)
+            ? { ok: true }
+            : { ok: false, why: "it shares no argument with the step" };
+    }
+    const differs = shared.find((key) => !sameValue(model[key], step[key]));
+    return differs === undefined ? { ok: true } : { ok: false, why: `its ${differs} is not the step's` };
+}
+function sameValue(a, b) {
+    if (typeof a === "string" && typeof b === "string") {
+        return a.trim().toLowerCase() === b.trim().toLowerCase();
+    }
+    return stableStringify(a) === stableStringify(b);
+}
 //# sourceMappingURL=pin-guard.js.map

package/dist/control/server.d.ts

@@ -282,6 +282,15 @@ export interface ControlServerOptions {
      * failing. Unset or `BIR_INTENT_ARM=0` is off.
      */
     intentArm?: boolean;
+    /**
+     * Whether the model's first call after a plan handed over asks the service
+     * for the plan of the work recorded after an earlier hand-over at that step,
+     * and runs it when that call is its first step (the service's fallbk.md
+     * Part 3). On by default: it is one request per hand-over, never per call.
+     * `BIR_CONTINUATIONS=0` turns it off; so does `BIR_INTENT_MATCH=0`, which
+     * turns off every mid-turn request.
+     */
+    continuations?: boolean;
     /**
      * The verdict hot paths consult before they wait on the service. Defaults to
      * the process-wide one every service call reports to; tests pass their own.
@@ -1156,6 +1165,60 @@ export declare class ControlServer {
      * matched call has run by then, and the plan's first step would repeat it.
      */
     private tryIntentMatch;
+    /**
+     * A continuation (the service's fallbk.md Part 3), on the model's first call
+     * after a plan handed over.
+     *
+     * The model's work after an earlier hand-over of the same plan at the same
+     * step was recorded once, as a fragment, and the service may have calculated
+     * it into a plan. Until 0.3.23 nothing asked for that plan: the only way a
+     * plan started mid-task was a match of the model's words against plan
+     * intents ({@link tryIntentMatch}, off by default), and a one-line note
+     * after a hand-over does not read like a plan's intent paragraph. Here the
+     * hand-over itself is the question — the plan and the step — so the service
+     * names one recording and matches no words.
+     *
+     * It arms only when the call the model is making is that plan's first step —
+     * its tool, and arguments the pin guard would pin to the step's input — and
+     * is then answered in that call's place, as an intent plan whose first step
+     * the call is. The plan before it stopped because the next step needed a
+     * judgement. This call is the model's judgement; a plan that starts with
+     * another call is a way the model did not take, and must not run.
+     *
+     * Its values are read from the turn's own request — the rest of the task is
+     * the one the user asked for — with the model's words, the call it was about
+     * to make and this turn's tool results beside it, as for any plan started at
+     * a tool call.
+     *
+     * Asked once per hand-over, waited on {@link CONTINUATION_PROBE_MS} and
+     * {@link CONTINUATION_ARM_MS} at most, and not at all while the service is
+     * failing. Every way it does not arm leaves the turn as it was: the model's
+     * call runs, and its work is recorded as the fragment. A plan handed out and
+     * not armed is reported for its ticket, with the reason.
+     */
+    private tryContinuation;
+    /**
+     * A continuation handed out and not armed: kept, retired, for its ticket's
+     * report at the seal (`not_steered`, with the reason, unmeasured). `code`
+     * says why when no gate did.
+     */
+    private keepDeclinedContinuation;
+    /** A continuation request's answer that came after the call it was for went ahead. */
+    private noteLateContinuation;
+    /**
+     * Every scenario this turn was handed and armed or declined: never handed
+     * out again in it. A plan that handed over is among them, so its own
+     * continuation request can never return it.
+     */
+    private armedScenarioIds;
+    /**
+     * Whether the model's call is a continuation's first step: its tool, and
+     * the step's own input in every argument the two share (pin-guard.ts
+     * `sameFirstCall`). Anything that cannot be computed is "no".
+     */
+    private isContinuationFirstCall;
+    /** Whether continuations are asked for: on unless `BIR_CONTINUATIONS=0`. */
+    private continuationsOn;
     /**
      * Whether the model's call is plausibly `state`'s first step: its tool, and
      * arguments the pin guard would pin to that step's input. Anything that

package/dist/control/server.js

@@ -30,7 +30,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { BIR_CALL_ID, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
 import { StepIndexAllocator } from "./ordering.js";
 import { pidAlive } from "./discovery.js";
-import { pinCompatible } from "./pin-guard.js";
+import { pinCompatible, sameFirstCall } from "./pin-guard.js";
 import { agentDayOf, contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, settledTextAfterToolUse, thinkingForToolUse, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
 import { asSent, userText } from "../record/prompt-text.js";
@@ -106,6 +106,27 @@ const INTENT_ARM_PROBE_MS = 500;
 const INTENT_ARM_DERIVE_MS = 1_500;
 /** How long a fragment's `PreToolUse` waits to learn whether its run was created. */
 const FRAGMENT_CREATE_MS = 300;
+/**
+ * How long the model's first call after a hand-over waits for the service to
+ * say whether the work recorded after an earlier hand-over at that step has a
+ * plan (the service's fallbk.md Part 3). One lookup, no words matched: it
+ * answers in a round trip. Asked once per hand-over, never per call.
+ */
+const CONTINUATION_PROBE_MS = 1_500;
+/**
+ * How long the continuation request itself may take — longer than the call
+ * waits for it, so that an answer too late for the call still lands, and the
+ * ticket it may carry is reported as late instead of never.
+ */
+const CONTINUATION_REQUEST_MS = 6_000;
+/**
+ * What a continuation may spend arming — reading its values — inside that
+ * `PreToolUse`. Longer than an intent arm may: it is asked once per hand-over,
+ * the plan it arms does the rest of the task, and a value the request names
+ * is read by the service, which gives a reading 6 s. With the probe it stays
+ * well inside the route's 12 s.
+ */
+const CONTINUATION_ARM_MS = 7_000;
 /** What `close()` spends draining the last runs to the service before it lets go. */
 const CLOSE_DRAIN_MS = 5_000;
 /** How long a background drain follows one run before it stops waiting for it. */
@@ -471,6 +492,17 @@ function reportedArgs(args) {
 function score(value) {
     return typeof value === "number" && Number.isFinite(value) ? value.toFixed(3) : undefined;
 }
+/**
+ * The tool a served scenario starts with, or undefined when the payload does
+ * not say. Untyped JSON from the service, read without trusting its shape.
+ */
+function firstStepTool(scenario) {
+    const steps = scenario?.steps;
+    if (!Array.isArray(steps) || steps.length === 0)
+        return undefined;
+    const name = steps[0]?.toolName;
+    return typeof name === "string" ? name : undefined;
+}
 function positiveEnv(name, fallback) {
     const n = Number(process.env[name]);
     return Number.isFinite(n) && n > 0 ? n : fallback;
@@ -920,6 +952,14 @@ export class ControlServer {
                     unannounced: s.run.pendingDirective?.state === s.run.replay ? true : undefined,
                     running: this.runningPlans.has(s.run.replay) ? true : undefined,
                     armedBy: s.run.replay.armedBy,
+                    // A continuation (the service's fallbk.md Part 3): the plan it
+                    // continues, and the step that plan stopped in front of.
+                    continues: s.run.replay.continuation
+                        ? {
+                            scenarioId: s.run.replay.continuation.ofScenarioId,
+                            stepIndex: s.run.replay.continuation.stepIndex,
+                        }
+                        : null,
                     handover: s.run.replay.handover
                         ? { kind: s.run.replay.handover.kind, stepIndex: s.run.replay.handover.stepIndex }
                         : null,
@@ -934,7 +974,13 @@ export class ControlServer {
                     armed: s.run.intent.armed,
                 }
                 : null,
-            fragment: s.run?.fragment ? { state: s.run.fragment.state } : null,
+            fragment: s.run?.fragment
+                ? {
+                    state: s.run.fragment.state,
+                    ...(s.run.fragment.asked ? { asked: true } : {}),
+                    ...(s.run.fragment.counted ? { counted: true } : {}),
+                }
+                : null,
             // The service's offer to record the turn as a recording's newest run,
             // and what became of it (newestRun.md).
             repeat: s.run?.repeat ? { state: s.run.repeat.state, of: s.run.repeat.runId } : null,
@@ -2989,12 +3035,36 @@ export class ControlServer {
             ? { runId: r.openedRunId, ownCalls: r.ownCalls ?? 0 }
             : undefined;
         const prompt = states.find((s) => s.armedBy === "prompt");
+        // The plans that continued a plan in this turn (the service's fallbk.md
+        // Part 3), directly or through one another: its hand-over's follow-on
+        // work. Its baseline is the whole task, theirs only the part after the
+        // hand-over, so its report bills the whole turn — its window runs through
+        // theirs, and their readings are booked on it — and theirs book no saving.
+        // Billed apart, the part after the hand-over would be saved twice.
+        const continuedBy = (state, from) => {
+            const chain = [];
+            const ids = new Set(state.scenarioId ? [state.scenarioId] : []);
+            for (const s of states.slice(from + 1)) {
+                if (s.continuation && ids.has(s.continuation.ofScenarioId)) {
+                    chain.push(s);
+                    if (s.scenarioId)
+                        ids.add(s.scenarioId);
+                }
+            }
+            // A continuation declined after its values were read spent that reading
+            // on this turn too, and its own report books nothing.
+            const declined = (run.declinedContinuations ?? []).filter((s) => s.continuation !== undefined && ids.has(s.continuation.ofScenarioId));
+            const deriveUsd = [...chain, ...declined].reduce((usd, s) => usd + s.deriveCostUsd, 0);
+            return { chain, deriveUsd };
+        };
         // One report per plan armed this turn (fallbk.md §Runner 4). Each is billed
         // for its own window of the transcript — from when it armed to when the next
         // one did — so the turn's tokens are split between them, never counted twice.
         // A turn with a single prompt-armed plan is exactly the report it always was.
         states.forEach((state, i) => {
-            const next = states[i + 1];
+            const { chain, deriveUsd: chainDeriveUsd } = continuedBy(state, i);
+            // The plan whose arm ends this one's window: never one that continued it.
+            const next = states.slice(i + 1).find((s) => !chain.includes(s));
             const nextMark = next?.armedBy === "intent" ? next.usageMark : undefined;
             let windowCost = cost;
             let windowMs = durationMs;
@@ -3027,6 +3097,7 @@ export class ControlServer {
                 runId: run.runId,
                 cutShort: cutShort || undefined,
                 redoneBy: state === prompt && state.ranToEnd === true ? redoneBy : undefined,
+                chainDeriveUsd,
             });
             if (!report)
                 return;
@@ -3087,6 +3158,23 @@ export class ControlServer {
             if (report)
                 this.queue.push(() => recorder.reportExecution(report));
         }
+        // Continuations handed out and not armed (the service's fallbk.md Part 3):
+        // a report for each ticket, with the reason, so the console says why and
+        // not "no report". Nothing of theirs ran: unmeasured and costless.
+        for (const declined of run.declinedContinuations ?? []) {
+            if (states.includes(declined))
+                continue;
+            const report = this.replay.buildReport(declined, {
+                sessionCostUsd: 0,
+                measured: false,
+                durationMs: 0,
+                prompt: run.input || undefined,
+                siblings: [...states, declined],
+                runId: run.runId,
+            });
+            if (report)
+                this.queue.push(() => recorder.reportExecution(report));
+        }
     }
     /**
      * The plan's own calls of the turn, whole, as an answered turn's report
@@ -3675,7 +3763,39 @@ export class ControlServer {
                     return {};
                 });
             }
-            const armed = planning
+            // 2a. The model's first call after a plan handed over: the work recorded
+            //     after an earlier hand-over at the same step may have a plan of its
+            //     own (the service's fallbk.md Part 3). Asked with the hand-over, not
+            //     with words, and armed only when this call is its first step.
+            const dueFragment = run.fragment;
+            const before = run.replay;
+            const continued = planning
+                ? undefined
+                : await this.tryContinuation(session, run, toolName, intent, modelArgs);
+            if (continued) {
+                if (!overran)
+                    return continued;
+                // The deadline answered first: the call ran as the model wrote it, and
+                // the plan was never announced. The model's own work from this call is
+                // the fragment, as it would have been with no plan.
+                const late = run.replay;
+                if (late && late !== before && late.continuation) {
+                    logLine("replay.decision", {
+                        verdict: "no-steer",
+                        code: "arm_unannounced",
+                        run: run.runId,
+                        scenario: late.scenarioId ?? undefined,
+                        why: "the call had to go ahead before this continuation's directive could replace it — retired unannounced, so never run",
+                    });
+                    const at = run.replays.indexOf(late);
+                    if (at >= 0)
+                        run.replays.splice(at, 1);
+                    run.replay = before;
+                    this.keepDeclinedContinuation(session, run, late, "arm_unannounced");
+                    run.fragment = dueFragment;
+                }
+            }
+            const armed = planning || continued
                 ? undefined
                 : await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
             if (armed) {
@@ -4327,9 +4447,7 @@ export class ControlServer {
         run.intent.requests += 1;
         // Every scenario armed this turn, so a continuation cannot re-arm the plan
         // that just handed over.
-        const exclude = run.replays
-            .map((s) => s.scenarioId)
-            .filter((id) => typeof id === "string");
+        const exclude = this.armedScenarioIds(run);
         const startedAt = Date.now();
         const framework = frameworkOf(session);
         const probe = this.recorder
@@ -4441,6 +4559,271 @@ export class ControlServer {
         run.pendingDirective = { state, text: directive };
         return undefined;
     }
+    /**
+     * A continuation (the service's fallbk.md Part 3), on the model's first call
+     * after a plan handed over.
+     *
+     * The model's work after an earlier hand-over of the same plan at the same
+     * step was recorded once, as a fragment, and the service may have calculated
+     * it into a plan. Until 0.3.23 nothing asked for that plan: the only way a
+     * plan started mid-task was a match of the model's words against plan
+     * intents ({@link tryIntentMatch}, off by default), and a one-line note
+     * after a hand-over does not read like a plan's intent paragraph. Here the
+     * hand-over itself is the question — the plan and the step — so the service
+     * names one recording and matches no words.
+     *
+     * It arms only when the call the model is making is that plan's first step —
+     * its tool, and arguments the pin guard would pin to the step's input — and
+     * is then answered in that call's place, as an intent plan whose first step
+     * the call is. The plan before it stopped because the next step needed a
+     * judgement. This call is the model's judgement; a plan that starts with
+     * another call is a way the model did not take, and must not run.
+     *
+     * Its values are read from the turn's own request — the rest of the task is
+     * the one the user asked for — with the model's words, the call it was about
+     * to make and this turn's tool results beside it, as for any plan started at
+     * a tool call.
+     *
+     * Asked once per hand-over, waited on {@link CONTINUATION_PROBE_MS} and
+     * {@link CONTINUATION_ARM_MS} at most, and not at all while the service is
+     * failing. Every way it does not arm leaves the turn as it was: the model's
+     * call runs, and its work is recorded as the fragment. A plan handed out and
+     * not armed is reported for its ticket, with the reason.
+     */
+    async tryContinuation(session, run, toolName, intent, modelArgs) {
+        const f = run.fragment;
+        if (!f || f.state !== "due" || f.asked)
+            return undefined;
+        if (!this.replay.enabled || !this.replay.intentMatch.enabled || !this.continuationsOn())
+            return undefined;
+        // Never in a session of another host: a plan is started there by the
+        // prompt, and stepped through by an adapter that was told of it then.
+        if (otherHost(session) || this.recordsOnly(session, run))
+            return undefined;
+        if (!isIntentMatcher(this.recorder))
+            return undefined;
+        // The model calling the delivery tool itself is no step of a plan.
+        if (this.replay.isDirectTool(toolName))
+            return undefined;
+        if (!this.service.canWait()) {
+            logDetail("replay.continuation_skipped", { run: run.runId, tool: toolName, why: "service unhealthy" });
+            return undefined;
+        }
+        f.asked = true;
+        const text = (intent?.text ?? "").trim().slice(0, 4_000);
+        const framework = frameworkOf(session);
+        const handover = { scenarioId: f.scenarioId, stepIndex: f.stepIndex };
+        let landed = false;
+        const probe = this.recorder
+            .matchIntent({
+            text,
+            currentToolName: toolName,
+            exclude: this.armedScenarioIds(run),
+            handover,
+            ...(framework ? { framework } : {}),
+        }, { timeoutMs: CONTINUATION_REQUEST_MS })
+            .catch(() => null)
+            .then((answer) => {
+            landed = true;
+            return answer;
+        });
+        const answer = await this.withinBudget(probe, CONTINUATION_PROBE_MS);
+        if (!answer) {
+            if (!landed) {
+                // Too slow, not failed: the service most likely counted the hand-over
+                // already, so the fragment says so. A plan its late answer hands out
+                // is reported as late, for its ticket.
+                f.counted = true;
+                void probe.then((late) => this.noteLateContinuation(run, handover, late));
+            }
+            logDetail("replay.continuation_miss", {
+                run: run.runId,
+                tool: toolName,
+                why: landed ? "the request failed" : "no answer in time",
+            });
+            return undefined;
+        }
+        // Only a service that knows continuations answers one. An older service
+        // matched the text by words instead, and that is no continuation.
+        if (answer.continuation === undefined)
+            return undefined;
+        f.counted = answer.continuation?.counted === true;
+        const match = answer.matched;
+        if (!answer.continuation || !match) {
+            logDetail("replay.continuation_none", {
+                run: run.runId,
+                continues: `${f.scenarioId}@${f.stepIndex}`,
+                recording: answer.continuation?.runId,
+                why: answer.continuation
+                    ? "the work recorded after an earlier hand-over here has no plan ready"
+                    : "no hand-over at this step was recorded before",
+            });
+            return undefined;
+        }
+        const continuation = {
+            ofScenarioId: f.scenarioId,
+            stepIndex: f.stepIndex,
+            runId: answer.continuation.runId,
+        };
+        // Before anything is read: the plan starts with another tool than the
+        // model's call, so the model chose another way.
+        const first = firstStepTool(match.scenario);
+        if (match.scenario && first !== undefined && first !== toolName) {
+            this.keepDeclinedContinuation(session, run, this.replay.declinedContinuation(match, "not_first_step", continuation));
+            return undefined;
+        }
+        const startedAt = Date.now();
+        // Valid JSON with the serializer's own truncation marker, never a raw
+        // slice: the live call handed to the reading.
+        const toolInput = serializeCapped(redact(modelArgs), {
+            maxPayloadBytes: 2048,
+            maxStringBytes: 256,
+        });
+        // The rest of the task the user asked for: its values are in the turn's
+        // request, and the model's words say what it is doing next.
+        const prompt = [run.input, text].filter((s) => s.trim().length > 0).join("\n\n");
+        const arming = this.armOrLog(run, this.replay.arm(match, prompt, this.wrapped, "intent", {
+            liveCall: { toolName, toolInput },
+            recentResults: this.recentResultsFor(session, "call"),
+            agentDay: this.agentDayFor(session),
+        }, undefined, { continuation }));
+        const state = await this.withinBudget(arming, CONTINUATION_ARM_MS);
+        if (state === undefined)
+            return undefined; // it threw, and said so
+        if (state === null) {
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "arm_timeout",
+                run: run.runId,
+                scenario: match.scenarioId ?? undefined,
+                continues: `${f.scenarioId}@${f.stepIndex}`,
+                ms: CONTINUATION_ARM_MS,
+                why: "the continuation's values were not read before this call had to go ahead — never delivered, so never run",
+            });
+            void arming.then((late) => {
+                if (late)
+                    this.keepDeclinedContinuation(session, run, late, "arm_timeout");
+            });
+            return undefined;
+        }
+        state.sessionId = session.sessionId;
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
+        this.declineWithoutDeliveryTool(state);
+        if (!state.plan) {
+            // A gate declined it, and said why (`state.declined`).
+            this.keepDeclinedContinuation(session, run, state);
+            return undefined;
+        }
+        // Its values are in: the model's call must be its first step, arguments
+        // and all — the same call, not merely one the pin guard would take over
+        // (pin-guard.ts `sameFirstCall`).
+        await this.withinBudget(state.plan.ready().catch(() => undefined), Math.max(0, CONTINUATION_ARM_MS - (Date.now() - startedAt)));
+        if (!this.isContinuationFirstCall(state, toolName, modelArgs)) {
+            this.keepDeclinedContinuation(session, run, state, "not_first_step");
+            return undefined;
+        }
+        state.usageMark = markTranscriptUsage(session.transcriptPath);
+        state.markUsage = () => markTranscriptUsage(session.transcriptPath);
+        run.replays.push(state);
+        run.replay = state;
+        // From here the continuation is this turn's plan. A hand-over of its own,
+        // if it makes one, schedules its own fragment: the one the plan before it
+        // left due is not opened.
+        run.fragment = undefined;
+        const directive = this.replay.directiveFor(state) ?? "";
+        logLine("replay.continuation_armed", {
+            run: run.runId,
+            scenario: state.scenarioId ?? undefined,
+            continues: `${continuation.ofScenarioId}@${continuation.stepIndex}`,
+            recording: continuation.runId,
+            mode: state.mode,
+            instead: toolName,
+            ms: Date.now() - startedAt,
+            why: "the model's call after the hand-over is the first step of the plan calculated from the work recorded after an earlier hand-over at this step",
+        });
+        return this.preToolAnswer(this.replay.deliverInstead(directive, toolName));
+    }
+    /**
+     * A continuation handed out and not armed: kept, retired, for its ticket's
+     * report at the seal (`not_steered`, with the reason, unmeasured). `code`
+     * says why when no gate did.
+     */
+    keepDeclinedContinuation(session, run, state, code) {
+        if (code) {
+            state.declined = code;
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code,
+                run: run.runId,
+                scenario: state.scenarioId ?? undefined,
+                continues: state.continuation
+                    ? `${state.continuation.ofScenarioId}@${state.continuation.stepIndex}`
+                    : undefined,
+                why: code === "not_first_step"
+                    ? "the model's call after the hand-over is not this continuation's first step — the model chose another way"
+                    : "the continuation was not armed in time",
+            });
+        }
+        state.sessionId = session.sessionId;
+        state.plan = undefined;
+        state.mode = "none";
+        state.stepsPlanned = 0;
+        state.retired = true;
+        state.pinned.clear();
+        // A seal has reported already: nothing more can be said for this turn.
+        if (run.finished)
+            return;
+        (run.declinedContinuations ??= []).push(state);
+    }
+    /** A continuation request's answer that came after the call it was for went ahead. */
+    noteLateContinuation(run, handover, late) {
+        const match = late?.matched;
+        if (!late?.continuation || !match?.executionTicket || run.finished)
+            return;
+        const state = this.replay.declinedContinuation(match, "match_late", {
+            ofScenarioId: handover.scenarioId,
+            stepIndex: handover.stepIndex,
+            runId: late.continuation.runId,
+        });
+        (run.declinedContinuations ??= []).push(state);
+    }
+    /**
+     * Every scenario this turn was handed and armed or declined: never handed
+     * out again in it. A plan that handed over is among them, so its own
+     * continuation request can never return it.
+     */
+    armedScenarioIds(run) {
+        return [...run.replays, ...(run.declinedContinuations ?? [])]
+            .map((s) => s.scenarioId)
+            .filter((id) => typeof id === "string");
+    }
+    /**
+     * Whether the model's call is a continuation's first step: its tool, and
+     * the step's own input in every argument the two share (pin-guard.ts
+     * `sameFirstCall`). Anything that cannot be computed is "no".
+     */
+    isContinuationFirstCall(state, toolName, modelArgs) {
+        const plan = state.plan;
+        if (!plan || plan.expectedTool() !== toolName)
+            return false;
+        try {
+            const verdict = sameFirstCall(toolName, modelArgs, plan.toolInputForCurrentStep());
+            if (!verdict.ok) {
+                logDetail("replay.continuation_other_call", { tool: toolName, why: verdict.why });
+            }
+            return verdict.ok;
+        }
+        catch (err) {
+            logDetail("replay.first_step_unknown", { tool: toolName, error: errText(err) });
+            return false;
+        }
+    }
+    /** Whether continuations are asked for: on unless `BIR_CONTINUATIONS=0`. */
+    continuationsOn() {
+        if (this.opts.continuations !== undefined)
+            return this.opts.continuations;
+        return process.env.BIR_CONTINUATIONS !== "0";
+    }
     /**
      * Whether the model's call is plausibly `state`'s first step: its tool, and
      * arguments the pin guard would pin to that step's input. Anything that
@@ -4521,9 +4904,12 @@ export class ControlServer {
             return;
         const input = reasoning.trim() || `${toolName} ${serializeCapped(redact(args))}`.slice(0, 2_000);
         const fallbackOf = { scenarioId: f.scenarioId, stepIndex: f.stepIndex };
+        // The service counted this hand-over already, when it was asked for its
+        // continuation (Part 3): the create says so, and is not counted again.
+        const sent = f.counted ? { ...fallbackOf, counted: true } : fallbackOf;
         // The fragment is a run of the same host as the turn it continues.
         const framework = frameworkOf(session);
-        const id = this.recorder.startRun(input, { ...this.runMetadata(session), fallbackOf }, framework ? { fallbackOf, framework } : { fallbackOf });
+        const id = this.recorder.startRun(input, { ...this.runMetadata(session), fallbackOf }, framework ? { fallbackOf: sent, framework } : { fallbackOf: sent });
         for (const c of run.correlations.values()) {
             c.settled = true;
             if (c.fallback)

package/dist/record/recorder.d.ts

@@ -7,9 +7,15 @@
  */
 import type { ExecutionStage, ExecutionStepResult, FallbackKind } from "../replay/types.js";
 export interface StartRunOptions {
+    /**
+     * Marks a *fragment* (fallbk.md D7). `counted`: the runner asked for this
+     * hand-over's continuation first, and the service counted the hand-over as
+     * a hit then, so this request must not count it again (Part 3).
+     */
     fallbackOf?: {
         scenarioId: string;
         stepIndex: number;
+        counted?: boolean;
     };
     /**
      * Marks a *repeat* (the service's newestRun.md): a matched turn whose plan
@@ -287,7 +293,12 @@ export interface ServiceProber {
 export declare function isServiceProber(r: Recorder): r is Recorder & ServiceProber;
 /** What a ReAct iteration sends to find a scenario by its intent (fallbk.md §Runner 4). */
 export interface IntentMatchRequest {
-    /** What the agent wrote, or was thinking, as it chose the call. Never empty. */
+    /**
+     * What the agent wrote, or was thinking, as it chose the call. Never empty
+     * on an intent probe. A continuation request ({@link handover}) is answered
+     * by the hand-over alone: it sends the text, possibly empty, and the service
+     * does not read it.
+     */
     text: string;
     currentToolName?: string;
     /** Scenario ids already armed this turn. */
@@ -298,12 +309,32 @@ export interface IntentMatchRequest {
      * what a missing value means to the service.
      */
     framework?: string;
+    /**
+     * A continuation request (the service's fallbk.md Part 3): the plan that
+     * just handed the task to the model, and the step it stopped in front of.
+     * The service answers with the plan of the work recorded after an earlier
+     * hand-over at that step, if there is one, and matches no words.
+     */
+    handover?: {
+        scenarioId: string;
+        stepIndex: number;
+    };
 }
 /** The answer to a probe. */
 export interface IntentMatchAnswer {
     matched: RunMatch | null;
     /** The best score the service saw, matched or not — for the log, to tune by. */
     bestSimilarity?: number | null;
+    /**
+     * The answer to a continuation request: the recording of the earlier
+     * hand-over at that step, and whether this hand-over was counted as a hit
+     * on it. Null when there is none; absent from a service that does not know
+     * continuations, which matched the text by words instead.
+     */
+    continuation?: {
+        runId: string;
+        counted?: boolean;
+    } | null;
 }
 /** How long a probe's caller will wait; the request is abandoned past it. */
 export interface IntentMatchOptions {
@@ -374,6 +405,15 @@ export interface ExecutionReport {
      * which is what every report said before this field existed.
      */
     baselineEligible?: boolean;
+    /**
+     * Set on a continuation's report (the service's fallbk.md Part 3): the plan
+     * it continued in this turn, which handed over in front of it. That plan's
+     * report bills the whole turn against its own baseline, which covers this
+     * part of the task too, so the service books this one no saving.
+     */
+    continues?: {
+        scenarioId: string;
+    };
     /**
      * Which gate of the ladder declined, on a `not_steered` report.
      *

package/dist/record/remote-recorder.js

@@ -683,6 +683,9 @@ export class RemoteRecorder {
             return {
                 matched: b.matched ?? null,
                 ...(typeof b.bestSimilarity === "number" ? { bestSimilarity: b.bestSimilarity } : {}),
+                // Null and absent mean different things: no continuation, or a
+                // service that does not know continuations (fallbk.md Part 3).
+                ...(b.continuation !== undefined ? { continuation: b.continuation } : {}),
             };
         }
         catch (err) {
@@ -1040,6 +1043,9 @@ export class RemoteRecorder {
                     fallbackStepIndex: report.fallbackStepIndex,
                     fallbackKind: report.fallbackKind,
                     baselineEligible: report.baselineEligible,
+                    // A continuation's report: the plan it continued, whose report
+                    // books the turn (the service's fallbk.md Part 3). Additive.
+                    continues: report.continues,
                     // Why nothing ran, when nothing ran. Additive: an older service drops
                     // the field and books the cost exactly as it always did.
                     declined: report.declined,
@@ -1070,6 +1076,8 @@ export class RemoteRecorder {
                     stepsFailed: failed || undefined,
                     baselineEligible: report.baselineEligible === false ? false : undefined,
                     declined: report.declined,
+                    // A continuation's report: the plan whose report books the turn.
+                    continues: report.continues?.scenarioId,
                     // `bir investigate` prints it beside the outcome: "redone by run_…".
                     redoneBy: report.redoneBy?.runId,
                     ownCalls: report.redoneBy?.ownCalls,

package/dist/replay/controller.d.ts

@@ -388,6 +388,16 @@ export interface ReplayState {
     retired: boolean;
     /** What armed it: the prompt, or a ReAct iteration's intent (fallbk.md). */
     armedBy: "prompt" | "intent";
+    /**
+     * Set on a continuation (the service's fallbk.md Part 3): a plan armed
+     * mid-turn because the plan before it handed over at a step, and the work
+     * recorded after an earlier hand-over at that step was calculated into this
+     * plan. `armedBy` is `intent` — it arms mid-turn, and is billed for its own
+     * window like any plan armed there — but it finishes the user's request
+     * rather than a part of the agent's own task, and its report books no
+     * saving: the plan it continued books the whole turn.
+     */
+    continuation?: ContinuationOf;
     /**
      * The Claude Code session this plan serves, set by the control server. Its
      * steps run on that session's own proxies (executor.ts). Absent for `bir
@@ -596,7 +606,33 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_ste
  * the prompt had been answered, or while prompts were not waiting on it
  * (the match gate). Set by the control server, like the two above.
  */
- | "match_late";
+ | "match_late"
+/**
+ * A continuation (the service's fallbk.md Part 3) whose first step is not
+ * the call the model is making after the hand-over: another tool, or the
+ * same tool on something else. The model chose what to do next — the
+ * judgement the plan before it stopped for — and chose otherwise. Set by
+ * the control server.
+ */
+ | "not_first_step";
+/**
+ * What a continuation continues (the service's fallbk.md Part 3): the plan
+ * that handed over, the step it stopped in front of, and the recording of the
+ * work done after an earlier hand-over there, which this plan was calculated
+ * from.
+ */
+export interface ContinuationOf {
+    ofScenarioId: string;
+    stepIndex: number;
+    runId: string;
+}
+/**
+ * Whether a plan is a part of the task the agent is already doing — armed
+ * mid-turn by its intent — so its words say "continue" and never "answer the
+ * user". A continuation is armed mid-turn too, and it is the rest of the
+ * user's request: it ends with the answer.
+ */
+export declare function isSubTask(state: Pick<ReplayState, "armedBy" | "continuation">): boolean;
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -674,6 +710,14 @@ export declare class ReplayController {
      * itself as one that never reported.
      */
     lateMatch(match: RunMatchLike, host?: HostContext): ReplayState;
+    /**
+     * The state of a continuation handed out and not armed (the service's
+     * fallbk.md Part 3): declined before any gate ran — its first step is not
+     * the model's call (`not_first_step`), or the service's answer came too
+     * late (`match_late`). Like {@link lateMatch}, it exists only for its
+     * ticket's report, with the reason.
+     */
+    declinedContinuation(match: RunMatchLike, code: DeclineCode, continuation: ContinuationOf): ReplayState;
     /**
      * Run the gate ladder and, if every gate passes, arm a plan.
      *
@@ -682,9 +726,13 @@ export declare class ReplayController {
      * up with a denominator nobody measured.
      *
      * `host` is given for a session whose host is not Claude Code, and is kept
-     * on the state (see {@link HostContext}).
+     * on the state (see {@link HostContext}). `extra.continuation` arms a
+     * continuation (the service's fallbk.md Part 3): see
+     * {@link ReplayState.continuation}.
      */
-    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext): Promise<ReplayState>;
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext, extra?: {
+        continuation?: ContinuationOf;
+    }): Promise<ReplayState>;
     /**
      * The armed plan as data: the steps it will run, in order, and where it
      * stops when that is before its end. For a host that steps through the plan
@@ -960,6 +1008,13 @@ export declare class ReplayController {
             runId: string;
             ownCalls: number;
         };
+        /**
+         * What the continuations of this plan spent reading their values this
+         * turn (the service's fallbk.md Part 3). Booked here, on the plan whose
+         * report bills the whole turn: theirs book no saving, so a cost left on
+         * them would be left out of the turn's saving.
+         */
+        chainDeriveUsd?: number;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic

package/dist/replay/controller.js

@@ -196,6 +196,15 @@ const MAX_STEP_ERROR_CHARS = 500;
  * cannot hold more than a few megabytes in the recorder.
  */
 const TURN_CALLS_MAX_CHARS = 8 * 1024 * 1024;
+/**
+ * Whether a plan is a part of the task the agent is already doing — armed
+ * mid-turn by its intent — so its words say "continue" and never "answer the
+ * user". A continuation is armed mid-turn too, and it is the rest of the
+ * user's request: it ends with the answer.
+ */
+export function isSubTask(state) {
+    return state.armedBy === "intent" && state.continuation === undefined;
+}
 export class ReplayController {
     enabled;
     work = new ProxyWorkQueue();
@@ -365,6 +374,30 @@ export class ReplayController {
         state.retired = true;
         return state;
     }
+    /**
+     * The state of a continuation handed out and not armed (the service's
+     * fallbk.md Part 3): declined before any gate ran — its first step is not
+     * the model's call (`not_first_step`), or the service's answer came too
+     * late (`match_late`). Like {@link lateMatch}, it exists only for its
+     * ticket's report, with the reason.
+     */
+    declinedContinuation(match, code, continuation) {
+        const state = this.blankState(match, new Set(), "intent");
+        state.continuation = continuation;
+        state.declined = code;
+        state.retired = true;
+        logLine("replay.decision", {
+            verdict: "no-steer",
+            code,
+            run: match.runId,
+            scenario: match.scenarioId ?? undefined,
+            continues: `${continuation.ofScenarioId}@${continuation.stepIndex}`,
+            why: code === "not_first_step"
+                ? "a continuation starts only on its first step, and the model's call after the hand-over is another one"
+                : "the continuation came after the call it could have replaced had gone ahead",
+        });
+        return state;
+    }
     /**
      * Run the gate ladder and, if every gate passes, arm a plan.
      *
@@ -373,10 +406,14 @@ export class ReplayController {
      * up with a denominator nobody measured.
      *
      * `host` is given for a session whose host is not Claude Code, and is kept
-     * on the state (see {@link HostContext}).
+     * on the state (see {@link HostContext}). `extra.continuation` arms a
+     * continuation (the service's fallbk.md Part 3): see
+     * {@link ReplayState.continuation}.
      */
-    async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}, host) {
+    async arm(match, prompt, wrapped, armedBy = "prompt", ctx = {}, host, extra = {}) {
         const state = this.blankState(match, wrapped, armedBy, host);
+        if (extra.continuation)
+            state.continuation = extra.continuation;
         const decline = (why, code) => {
             state.declined = code;
             logLine("replay.decision", {
@@ -597,12 +634,13 @@ export class ReplayController {
         }
         // 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".
+        // A continuation is the rest of the user's request: it ends with the answer.
         state.plan = new ScenarioReplayPlan({
             scenario,
             params,
             mode,
             stopAt,
-            subTask: armedBy === "intent",
+            subTask: isSubTask(state),
         });
         if (mode === "steer") {
             // A steer directive shows the arguments the steps will run with, so the
@@ -643,7 +681,11 @@ export class ReplayController {
             host: host?.app,
             steps: steps.length,
             stopsAt: stopAt,
-            by: armedBy === "intent" ? "intent" : undefined,
+            by: armedBy === "intent" ? (state.continuation ? "continuation" : "intent") : undefined,
+            // The plan it continues and the step that plan stopped in front of.
+            continues: state.continuation
+                ? `${state.continuation.ofScenarioId}@${state.continuation.stepIndex}`
+                : undefined,
             similarity: match.similarity.toFixed(3),
             // Which steps the service told this plan to stop in front of, and why.
             stops: stopLines(steps),
@@ -752,7 +794,7 @@ export class ReplayController {
     directiveFor(state, opts = {}) {
         const asked = opts.previewMs;
         return state.plan?.steeringDirective(DIRECT_TOOL_NAME, {
-            subTask: state.armedBy === "intent",
+            subTask: isSubTask(state),
             // NaN is a caller's arithmetic gone wrong: no time known, no preview.
             previewBudgetMs: typeof asked === "number"
                 ? Math.max(0, Math.min(Number.isNaN(asked) ? 0 : asked, PREVIEW_BUDGET_MS))
@@ -1499,10 +1541,9 @@ export class ReplayController {
         const what = left.length === 1 ? `Not needed for this request: ${named[0]}${why}.` : `Not needed for this request: ${named.join(", ")}${why}.`;
         let next;
         if (plan.isDone() && !plan.atStop()) {
-            next =
-                state.armedBy === "intent"
-                    ? "The sequence is complete: continue your task, calling tools as needed."
-                    : "The sequence is complete: answer the user's request from the tool results.";
+            next = isSubTask(state)
+                ? "The sequence is complete: continue your task, calling tools as needed."
+                : "The sequence is complete: answer the user's request from the tool results.";
         }
         else {
             const step = plan.currentStep();
@@ -1890,7 +1931,8 @@ export class ReplayController {
         if (state.reported || !state.scenarioId)
             return undefined;
         state.reported = true;
-        const total = state.deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
+        const deriveCostUsd = state.deriveCostUsd + Math.max(0, d.chainDeriveUsd ?? 0);
+        const total = deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
         const steps = this.stepResultsOf(state);
         const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
         // A costless decline is noise on both sides — *unless* it says something the
@@ -1912,7 +1954,7 @@ export class ReplayController {
             runId: d.runId,
             ticket: state.ticket,
             outcome: state.outcome,
-            deriveCostUsd: state.deriveCostUsd,
+            deriveCostUsd,
             sessionCostUsd: d.sessionCostUsd,
             fallbackCostUsd: state.fallbackCostUsd,
             durationMs: d.durationMs,
@@ -1955,6 +1997,9 @@ export class ReplayController {
                 : undefined,
             // The agent did not take the plan's result and redid the task (AC1).
             ...(d.redoneBy ? { redoneBy: d.redoneBy } : {}),
+            // A continuation (the service's fallbk.md Part 3): the plan it continued
+            // books the whole turn, so this report books no saving of its own.
+            ...(state.continuation ? { continues: { scenarioId: state.continuation.ofScenarioId } } : {}),
             // 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

package/docs/calculatedReplayGuide.md

@@ -373,6 +373,7 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `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_PATH_ALLOW` | *(unset: any folder, from 0.3.21)* | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools reach it — a plan that reads the agent's memory file under `~/.claude` runs. `project` is the session's project folder alone (the rule up to 0.3.20); add folders after a comma, `~` for the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is refused and the plan hands over in front of it. `none` means no folder, and the file steps are steered in the session. `Bash` is `BIR_BASH_ALLOW`'s |
 | `BIR_INTENT_ARM` | *(unset: off)* | `1` lets a whole plan whose intent matches the agent's reasoning mid-turn arm in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500). Unset or `0`: off — no probe is sent and nothing arms mid-turn, as up to 0.3.18 |
+| `BIR_CONTINUATIONS` | *(unset: on, from 0.3.23)* | After a plan hands the task to the agent at a step, the agent's first call asks the service for the plan of the work recorded after an earlier hand-over at that step — once per hand-over, waiting 1.5 s at most for the answer and up to 7 s for its values — and runs it in that call's place only when the call is its first step (the same tool, on the same thing). Its saving is counted on the plan that handed over. `0`: off, and the agent's work is recorded as before. `BIR_INTENT_MATCH=0` turns it off too |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 
 The `bir` server reads its own, from the environment Claude Code starts it with:

package/package.json

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