@basein/runner 0.2.0 → 0.2.1

package/dist/control/server.js

@@ -24,21 +24,29 @@
  * accepts unauthenticated step reports is a local exfiltration channel.
  */
 import { createServer } from "node:http";
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { FINGERPRINT_WINDOW_MS, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
 import { StepIndexAllocator } from "./ordering.js";
-import { contextForToolUse, markTranscriptUsage, settledLastAssistantText, usageSince, } from "./transcript.js";
+import { contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, usageSince, } from "./transcript.js";
 import { isHousekeeping } from "../record/housekeeping.js";
 import { redact } from "../record/redact.js";
 import { serializeCapped } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
-import { NullRecorder, isMatchAware, isScenarioReporter, } from "../record/recorder.js";
+import { NullRecorder, isIntentMatcher, isMatchAware, isRunCreationAware, isScenarioReporter, } from "../record/recorder.js";
 import { ReplayController, POLL_HOLD_MS, } from "../replay/controller.js";
 import { calculateCostUsd } from "../replay/pricing.js";
 import { logDetail, logLine, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
 /** How long a `/tool/post` waits for the proxy's own report before recording its own view. */
 const PROXY_REPORT_GRACE_MS = 1_500;
+/** One MCP call, as seen from up to two sides. */
+/**
+ * Field separator for the probe's dedupe hash (segmented.md R-HIT-5). A NUL,
+ * so that a text ending where a tool name begins can never hash the same as the
+ * other way round. Built rather than written as an escape, because a literal
+ * NUL in source is a trap for every tool that reads the file.
+ */
+const PROBE_SEP = String.fromCharCode(0);
 export class ControlServer {
     token;
     sessionId = "birsess_" + randomUUID();
@@ -57,6 +65,18 @@ export class ControlServer {
     pendingSeals = [];
     /** Calculated replay. Inert unless `opts.replay.enabled`. */
     replay;
+    /**
+     * How many of this prompt's tool results derivation may read
+     * (`BIR_DERIVE_RECENT_RESULTS`, segmented.md R-PARAM-2). A target is often
+     * named by an earlier step's output and never by the prompt.
+     */
+    deriveRecentResults;
+    /**
+     * Which rungs of R-INTENT-1 the runner may send (`BIR_INTENT_SOURCES`). It
+     * governs only what is *sent*: with every source off, the probe still goes out
+     * with an empty text and the server builds the tool line (R-HIT-4).
+     */
+    intentSources;
     constructor(opts) {
         this.opts = opts;
         this.recorder = opts.recorder;
@@ -64,6 +84,8 @@ export class ControlServer {
         for (const name of opts.wrappedServers ?? [])
             this.wrapped.add(name);
         this.replay = new ReplayController(opts.replay ?? { enabled: false, minSimilarity: 1 });
+        this.deriveRecentResults = opts.deriveRecentResults ?? 5;
+        this.intentSources = opts.intentSources ?? new Set(["text", "thinking", "tool"]);
         this.queue = new StepQueue({
             onDrop: (dropped) => {
                 // §10: drop oldest, flag the run lossy. The flag is louder than a
@@ -138,8 +160,25 @@ export class ControlServer {
                     stepsPlanned: s.run.replay.stepsPlanned,
                     stepsPinned: s.run.replay.stepsPinned,
                     armed: Boolean(s.run.replay.plan) && !s.run.replay.retired,
+                    armedBy: s.run.replay.armedBy,
+                    handover: s.run.replay.handover
+                        ? { kind: s.run.replay.handover.kind, stepIndex: s.run.replay.handover.stepIndex }
+                        : null,
+                    plans: s.run.replays.length,
+                    kind: s.run.replay.kind,
+                }
+                : null,
+            // Present whether or not a plan is armed (segmented.md R-LIFE-8): the
+            // whole point of the observe-only period is that it is visible, and
+            // "nothing armed" and "nothing even probed" are different problems.
+            intent: s.run
+                ? {
+                    probes: s.run.intent.requests,
+                    armed: s.run.intent.armed,
+                    lastStepHit: s.run.intent.lastStepHit ?? null,
                 }
                 : null,
+            fragment: s.run?.fragment ? { state: s.run.fragment.state } : null,
         }));
         return {
             ok: true,
@@ -147,6 +186,11 @@ export class ControlServer {
             tier: "bound",
             // The authoritative answer to "is anything actually being saved?".
             recording: this.opts.recording ?? !(this.recorder instanceof NullRecorder),
+            // Whether a handed-out segment may actually run mid-task, or whether the
+            // runner is only watching (R-OUT-10, R-LIFE-8). Observe-only must never
+            // be invisible: an operator has to be able to see which of the two this
+            // machine is doing without reading a log file.
+            segmentArm: this.replay.segmentArm,
             authUrl: process.env.BIR_AUTH_URL ?? null,
             sessionId: this.sessionId,
             pid: process.pid,
@@ -326,6 +370,9 @@ export class ControlServer {
             promptSeen: input.length > 0,
             builtIns: new Map(),
             correlations: new Map(),
+            replays: [],
+            turnId: runId,
+            intent: { armed: 0, requests: 0 },
             // Taken here, beside `startedAtMs`, so the cost window and the duration
             // window are the same window (docs/calculatedReplay.md §11.4).
             usageMark: markTranscriptUsage(session.transcriptPath),
@@ -334,7 +381,7 @@ export class ControlServer {
         logLine("run.start", { run: runId, sess: session.sessionId, tier: "bound" });
         // Started here so the round trip overlaps whatever the caller does next;
         // `onPrompt` awaits the same memoized promise under its own budget.
-        void this.watchForMatch(run);
+        void this.watchForMatch(session, run);
         return run;
     }
     runMetadata(session) {
@@ -362,7 +409,7 @@ export class ControlServer {
      *
      * Resolves with the steering directive to inject, or undefined.
      */
-    watchForMatch(run, prompt = "") {
+    watchForMatch(session, run, prompt = "") {
         if (run.matchWatch)
             return run.matchWatch;
         if (!isMatchAware(this.recorder))
@@ -370,7 +417,7 @@ export class ControlServer {
         const pending = this.recorder.getMatch(run.runId);
         run.matchWatch = this.replay
             .awaitMatch(pending)
-            .then((match) => {
+            .then(async (match) => {
             if (!match)
                 return undefined;
             run.recording = false;
@@ -381,8 +428,15 @@ export class ControlServer {
                 similarity: match.similarity,
                 why: "similar prompt — the service kept its own run; not recording this one",
             });
-            run.replay = this.replay.arm(match, prompt || run.input, this.wrapped);
-            return this.replay.directiveFor(run.replay);
+            // Awaited: a scenario with a target derives before the directive goes
+            // out, so a plan that cannot find its target is never delivered
+            // (segmented.md R-PARAM-4). Inside `UserPromptSubmit`'s 15 s.
+            const state = await this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", {
+                recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
+            });
+            run.replay = state;
+            run.replays.push(state);
+            return this.replay.directiveFor(state);
         })
             .catch((err) => {
             // Replay is an optimisation; a broken one must never cost a turn.
@@ -423,7 +477,12 @@ export class ControlServer {
         // A matched turn records nothing, but it still owes the ledger a number —
         // including when it declined to steer, which is a *baseline* sample and is
         // what every saving is measured against (docs/calculatedReplay.md §11).
-        this.reportExecution(run, durationMs, cost);
+        this.reportExecution(session, run, durationMs, cost);
+        // A fragment is recorded from the hand-over on (fallbk.md D7), so its cost
+        // and duration are the model's own work, not the steps the scenario did.
+        const fragment = run.fragment?.state === "open" ? run.fragment : undefined;
+        const recordedCost = fragment ? this.costSince(session, fragment.usageMark) : cost;
+        const recordedMs = fragment?.startedAtMs ? Date.now() - fragment.startedAtMs : durationMs;
         if (run.recording) {
             const transcriptPath = session.transcriptPath;
             // Resolve the answer *outside* the queue: the wait below is up to two
@@ -442,8 +501,8 @@ export class ControlServer {
                     // scenario that has no samples yet. A run recorded at $0 makes
                     // every later saving measured against nothing.
                     this.recorder.finishRun(run.runId, answer || undefined, {
-                        durationMs,
-                        costUsd: cost.measured ? cost.usd : undefined,
+                        durationMs: recordedMs,
+                        costUsd: recordedCost.measured ? recordedCost.usd : undefined,
                     });
                 });
             }));
@@ -486,24 +545,66 @@ export class ControlServer {
             });
             return { usd: 0, measured: false };
         }
-        const deltas = usageSince(session.transcriptPath, run.usageMark);
+        return this.costSince(session, run.usageMark);
+    }
+    /** Transcript cost since `mark`; unmeasured (and zero) without one. */
+    costSince(session, mark) {
+        if (mark === undefined)
+            return { usd: 0, measured: false };
+        const deltas = usageSince(session.transcriptPath, mark);
         const usd = deltas.reduce((sum, u) => sum + calculateCostUsd(u.model, u), 0);
         return { usd, measured: deltas.length > 0 };
     }
-    reportExecution(run, durationMs, cost) {
-        const state = run.replay;
-        if (!state || !isScenarioReporter(this.recorder))
-            return;
-        const report = this.replay.buildReport(state, {
-            sessionCostUsd: cost.usd,
-            measured: cost.measured,
-            durationMs,
-            prompt: run.input || undefined,
-        });
-        if (!report)
+    reportExecution(session, run, durationMs, cost) {
+        if (!isScenarioReporter(this.recorder))
             return;
+        const states = run.replays.length > 0 ? run.replays : run.replay ? [run.replay] : [];
         const recorder = this.recorder;
-        this.queue.push(() => recorder.reportExecution(report));
+        // 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 nextMark = next?.armedBy === "intent" ? next.usageMark : undefined;
+            let windowCost = cost;
+            let windowMs = durationMs;
+            // An intent-armed plan's window *ends* where its work ended (segmented.md
+            // R-MONEY-3): at its own retire mark when it completed, else at the next
+            // plan's arm, else at the end of the turn. Without the first, a segment
+            // that finished in three steps would be billed for everything the agent
+            // did afterwards, and its saving would read as a loss.
+            let end = nextMark;
+            if (state.armedBy === "intent") {
+                windowCost = this.costSince(session, state.usageMark);
+                windowMs = (state.retiredAt ?? next?.armedAt ?? Date.now()) - state.armedAt;
+                end = state.retiredMark ?? nextMark;
+            }
+            else if (next) {
+                windowMs = next.armedAt - run.startedAtMs;
+            }
+            if (end !== undefined) {
+                const later = this.costSince(session, end);
+                windowCost = { usd: Math.max(0, windowCost.usd - later.usd), measured: windowCost.measured };
+            }
+            const report = this.replay.buildReport(state, {
+                sessionCostUsd: windowCost.usd,
+                measured: windowCost.measured,
+                durationMs: Math.max(0, windowMs),
+                prompt: run.input || undefined,
+                siblings: states,
+            });
+            if (!report)
+                return;
+            if (state.armedBy === "intent") {
+                logDetail("replay.done", {
+                    scenario: state.scenarioId ?? undefined,
+                    windowMs: Math.max(0, windowMs),
+                    billedTo: state.retiredMark !== undefined ? "its own retire" : "the next arm or the turn",
+                });
+            }
+            this.queue.push(() => recorder.reportExecution(report));
+        });
     }
     /** Seal the run *and* wait for everything queued to reach the service. */
     async finalizeRun(session) {
@@ -569,7 +670,7 @@ export class ControlServer {
         // a slow or unreachable service costs the user nothing but an ordinary turn
         // (docs/calculatedReplay.md §10); `additionalContext` carries no `decision`,
         // so the prompt still reaches the model either way.
-        const directive = await this.watchForMatch(run, input);
+        const directive = await this.watchForMatch(session, run, input);
         if (!directive)
             return {};
         return {
@@ -605,36 +706,49 @@ export class ControlServer {
             return {};
         }
         const agentId = payload.agent_id ?? session.agentId;
-        const reasoning = contextForToolUse(session.transcriptPath, toolUseId);
+        // The real intent, read from every line sharing this message's id
+        // (segmented.md R-INTENT-3). `context` stays the *written* text only, with
+        // its agent prefix: thinking is embedded but never stored as text
+        // (R-INTENT-2), so it rides separately in `intent`.
+        const intent = intentForToolUse(session.transcriptPath, toolUseId, this.intentSources);
+        const reasoning = intent?.source === "text" ? intent.text : "";
+        // The prefix rides on whether there is a subagent, not on whether it said
+        // anything: a subagent's steps must be tellable apart even when it narrated
+        // nothing. What it never carries is thinking (R-INTENT-2).
         const context = agentId ? `[agent ${agentId}] ${reasoning}`.trim() : reasoning;
+        const thinkingIntent = intent?.source === "thinking" ? { text: intent.text, source: "thinking" } : undefined;
         // ── replay steering (docs/calculatedReplay.md §7) ────────────────────────
         // Runs before anything else, because two of its four answers end the call.
         let pinned;
         if (run.replay?.plan && !run.replay.retired) {
             const action = await this.replay.preTool(run.replay, toolName, toolUseId);
-            switch (action.kind) {
-                case "pin":
-                    pinned = action.input;
-                    break;
-                case "bash":
-                    return {
-                        hookSpecificOutput: {
-                            hookEventName: "PreToolUse",
-                            permissionDecision: "allow",
-                            updatedInput: { command: action.command },
-                        },
-                    };
-                case "deny":
-                    return {
-                        hookSpecificOutput: {
-                            hookEventName: "PreToolUse",
-                            permissionDecision: "deny",
-                            permissionDecisionReason: action.reason,
-                        },
-                    };
-                case "abort":
-                case "passthrough":
-                    break;
+            // A hand-over inside `preTool` (an input logic that threw) must still
+            // schedule the fragment, even though this call ends here.
+            this.noteHandover(run);
+            if (action.kind === "pin")
+                pinned = action.input;
+            const answer = this.preToolAnswer(action);
+            if (answer)
+                return answer;
+        }
+        if (!pinned && (!run.replay?.plan || run.replay.retired)) {
+            // ── falling back to the model (fallbk.md) ──────────────────────────────
+            // 1. A hand-over noticed where no hook answer could carry it — a proxy
+            //    report threaded after its PostToolUse had already answered — reaches
+            //    the model in place of this call. Never silence (D4).
+            const note = this.replay.takeNote(run.replay);
+            if (note) {
+                this.noteHandover(run);
+                return this.preToolAnswer(this.replay.deliverInstead(note, toolName));
+            }
+            // 2. The model is driving: look for a scenario by this iteration's intent.
+            const armed = await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
+            if (armed)
+                return armed;
+            // 3. No scenario took over: the model's own work after a hand-over is
+            //    recorded as a fragment, starting with this call.
+            if (run.fragment?.state === "due") {
+                await this.openFragment(session, run, reasoning, toolName, modelArgs);
             }
         }
         // The arguments that will actually run — which is what must be correlated and
@@ -654,6 +768,11 @@ export class ControlServer {
                 createdAt: Date.now(),
                 settled: false,
                 fingerprint: fingerprint(mcp.serverName, mcp.toolName, args),
+                // Captured here because this is the last moment the code knows: by the
+                // time `settle` records the step, `postTool` has consumed the pin
+                // (segmented.md R-INTENT-7).
+                pinnedBy: pinned ? (run.replay?.scenarioId ?? undefined) : undefined,
+                intent: thinkingIntent,
             };
             run.correlations.set(correlation.callId, correlation);
             logDetail("tool.pre.correlate", {
@@ -699,16 +818,26 @@ export class ControlServer {
             responseIndex: pair.response,
             toolName,
         });
+        // A step a plan executed is pinned and never embedded (R-INTENT-7), so the
+        // system's own replays never look like the work recurring. Two paths reach
+        // here: a built-in step the plan pinned, and the direct plan's own vehicle
+        // `mcp__bir__run_scenario`, which is recorded as a built-in while its plan
+        // is live and is just as much the system's own doing.
+        const pinnedBy = pinned || (this.replay.isDirectTool(toolName) && run.replay?.plan && !run.replay.retired)
+            ? (run.replay?.scenarioId ?? undefined)
+            : undefined;
         if (run.recording) {
             this.queue.push(() => {
                 this.recorder.recordToolSelected(run.runId, pair.selected, {
                     toolName,
                     toolInput: serializeCapped(redact(args)),
                     context: context || undefined,
+                    intent: thinkingIntent,
+                    metadata: pinnedBy ? { pinnedBy } : undefined,
                 });
             });
         }
-        logDetail("tool.pre", { run: run.runId, tool: toolName, step: pair.selected });
+        logDetail("tool.pre", { run: run.runId, tool: toolName, step: pair.selected, pinnedBy });
         if (pinned) {
             return {
                 stepIndex: pair.selected,
@@ -721,6 +850,365 @@ export class ControlServer {
         }
         return { stepIndex: pair.selected };
     }
+    /** A controller decision as a `PreToolUse` answer, or undefined to carry on. */
+    preToolAnswer(action) {
+        switch (action.kind) {
+            case "bash":
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        updatedInput: { command: action.command },
+                    },
+                };
+            case "deny":
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "deny",
+                        permissionDecisionReason: action.reason,
+                    },
+                };
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Recordings this turn must not count a step hit against (segmented.md
+     * R-HIT-7).
+     *
+     * A repeat of a recording's own prompt is *prompt* recurrence, counted as
+     * `iterations`, never step recurrence. Without this, three prompt repeats
+     * would reach `SEGMENT_MIN_HITS` on every step of the whole recording and the
+     * detector would build a whole-run-sized segment beside the whole-run
+     * scenario.
+     */
+    excludeRunsFor(run) {
+        const out = new Set();
+        if (run.recording)
+            out.add(run.runId);
+        const prompt = run.replays.find((s) => s.armedBy === "prompt")?.matchedRunId;
+        if (prompt)
+            out.add(prompt);
+        if (run.fragment?.hitRunId)
+            out.add(run.fragment.hitRunId);
+        return [...out];
+    }
+    /**
+     * Per recording a plan of this turn came from, how far that plan got
+     * (segmented.md R-OUT-6).
+     *
+     * The server uses it to refuse a segment that starts *before* where this turn
+     * already is: re-running steps the turn has just done is worse than not
+     * replaying at all. The largest position per recording wins, and a plan
+     * declined for anything but a known-bad first step reports nothing — it ran
+     * none of the recording, so it blocks none of it.
+     *
+     * Rebuilt on every probe rather than cached: a plan that hands over between
+     * two calls changes the answer.
+     */
+    ranThroughFor(run) {
+        const best = new Map();
+        for (const state of run.replays) {
+            if (!state.scenarioId)
+                continue;
+            const recording = state.matchedRunId;
+            if (!recording)
+                continue;
+            let position;
+            if (!state.plan) {
+                // Only a known-bad first step means the turn is committed to doing this
+                // recording's work itself from position 0 (R-HIT-14); every other
+                // decline leaves the recording untouched.
+                if (state.declined === "known_bad_first_step")
+                    position = 0;
+            }
+            else if (state.handover) {
+                position = state.handover.stepIndex;
+            }
+            else {
+                // Ran to its end: the last position it planned.
+                position = Math.max(0, state.plan.stepCount - 1);
+            }
+            if (position === undefined)
+                continue;
+            const seen = best.get(recording);
+            if (!seen || position > seen.position) {
+                best.set(recording, { position, scenarioId: state.scenarioId });
+            }
+        }
+        return [...best].map(([runId, v]) => ({
+            runId,
+            position: v.position,
+            scenarioId: v.scenarioId,
+        }));
+    }
+    /**
+     * Intent matching in the ReAct loop (fallbk.md §Runner 4, segmented.md 10.3).
+     *
+     * Called only while the model is driving. Every unsteered, non-housekeeping
+     * tool call is sent: the service counts it as a hit on whatever recorded step
+     * it matches, and may hand back a scenario or a segment to run in its place.
+     *
+     * A call made with **no reasoning at all** still probes (R-HIT-4): the server
+     * builds an intent from the tool name and arguments, and a step the agent took
+     * without narrating it is exactly as much a recurrence as one it explained.
+     * Every failure is a miss.
+     */
+    async tryIntentMatch(session, run, toolName, intent, modelArgs) {
+        const opts = this.replay.intentMatch;
+        if (!this.replay.enabled || !opts.enabled)
+            return undefined;
+        if (!isIntentMatcher(this.recorder))
+            return undefined;
+        if (this.replay.isDirectTool(toolName))
+            return undefined;
+        const text = (intent?.text ?? "").trim().slice(0, 4_000);
+        const source = intent?.source ?? "tool";
+        // Valid JSON with the serializer's own truncation marker, never a raw slice:
+        // the same string feeds the dedupe hash, the server's live question and the
+        // live call handed to derivation (R-HIT-4).
+        const toolInput = serializeCapped(redact(modelArgs), {
+            maxPayloadBytes: 2048,
+            maxStringBytes: 256,
+        });
+        // A retried identical call is not sent again; two different calls under one
+        // reasoning line both are (R-HIT-5).
+        const probeHash = createHash("sha1")
+            .update([text, toolName, toolInput].join(PROBE_SEP))
+            .digest("hex");
+        if (probeHash === run.intent.lastProbeHash)
+            return undefined;
+        run.intent.lastProbeHash = probeHash;
+        if (run.intent.requests >= opts.maxRequestsPerTurn)
+            return undefined;
+        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 startedAt = Date.now();
+        const answer = await this.withinBudget(this.recorder.matchIntent({
+            text,
+            source,
+            // The same value twice: `currentToolName` is what today's server reads,
+            // `toolName` is what the new one reads beside `toolInput`.
+            currentToolName: toolName,
+            toolName,
+            toolInput,
+            exclude,
+            turnId: run.turnId,
+            stepPosition: run.ordering.next,
+            excludeRuns: this.excludeRunsFor(run),
+            ranThrough: this.ranThroughFor(run),
+            ...(this.replay.segmentArm ? { acceptSegments: true } : {}),
+            supportsCalls: true,
+        }), opts.budgetMs);
+        if (!answer) {
+            logDetail("replay.intent_miss", { run: run.runId, tool: toolName });
+            return undefined;
+        }
+        if (answer.stepHit) {
+            run.intent.lastStepHit = { ...answer.stepHit, at: Date.now() };
+        }
+        // What *would* have armed, had segments been armed (segmented.md R-OUT-10).
+        // Logged at line level, not detail: this is the whole observe-only period,
+        // and the decision to turn arming on is made by reading these. The turn
+        // then carries on with whatever else the answer holds (R-OUT-15).
+        if (answer.segmentWouldArm) {
+            const w = answer.segmentWouldArm;
+            logLine("replay.segment_would_arm", {
+                scenario: w.scenarioId,
+                run: w.runId,
+                key: w.key,
+                similarity: w.similarity.toFixed(3),
+                band: w.band,
+                verified: w.verified
+                    ? w.verified.verdict === "skipped"
+                        ? `skipped:${w.verified.reason}`
+                        : `${w.verified.verdict}: ${w.verified.reason}`
+                    : undefined,
+                tool: w.tool ?? toolName,
+                firstTool: w.firstTool,
+                stepFrom: w.stepFrom,
+                stepTo: w.stepTo,
+                hitCount: w.hitCount,
+            });
+        }
+        const match = answer.matched;
+        logDetail("replay.intent_probe", {
+            run: run.runId,
+            tool: toolName,
+            source,
+            stepHit: answer.stepHit ? `${answer.stepHit.runId}:${answer.stepHit.stepIndex}` : "none",
+            bestStepSimilarity: answer.bestStepSimilarity,
+            elapsedMs: Date.now() - startedAt,
+            matched: match?.scenarioId ?? "none",
+            kind: match?.kind,
+        });
+        if (!match)
+            return undefined;
+        if (match.scenarioId && exclude.includes(match.scenarioId))
+            return undefined;
+        // The arms cap is checked *after* the response, not before it (R-HIT-5):
+        // hit counting must not stop just because the turn has already armed three
+        // plans. The ticket the server issued goes unredeemed and is swept
+        // (R-OUT-12).
+        if (run.intent.armed >= opts.maxPerTurn) {
+            logLine("replay.intent_arm_capped", {
+                scenario: match.scenarioId ?? undefined,
+                kind: match.kind ?? "scenario",
+                similarity: match.similarity.toFixed(3),
+                tool: toolName,
+            });
+            return undefined;
+        }
+        const state = await this.replay.arm(match, text, this.wrapped, "intent", {
+            liveCall: { toolName, toolInput },
+            recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
+        });
+        if (!state.plan) {
+            // A declined intent hit reports nothing: the turn's cost is not a
+            // measurement of that scenario's task, so it is no baseline sample either.
+            state.reported = true;
+            return undefined;
+        }
+        state.usageMark = markTranscriptUsage(session.transcriptPath);
+        // The closure, not the mark: only the control server holds the transcript
+        // path, and a completing retire happens in the controller (R-MONEY-3).
+        state.markUsage = () => markTranscriptUsage(session.transcriptPath);
+        // A segment of a recording whose whole-run plan already armed this turn
+        // takes its share off that plan's baseline (R-MONEY-4). One recording's
+        // steps are never counted in two baselines of one turn.
+        if (state.kind === "segment" && state.segment && state.scenarioId) {
+            for (const earlier of run.replays) {
+                if (earlier === state || !earlier.plan)
+                    continue;
+                if (earlier.kind !== "scenario")
+                    continue;
+                if (earlier.matchedRunId !== state.segment.runId)
+                    continue;
+                earlier.sharedWith.push(state.scenarioId);
+            }
+        }
+        run.replays.push(state);
+        run.replay = state;
+        run.intent.armed += 1;
+        const directive = this.replay.directiveFor(state) ?? "";
+        logLine("replay.intent_armed", {
+            run: run.runId,
+            scenario: state.scenarioId ?? undefined,
+            similarity: match.similarity.toFixed(3),
+            mode: state.mode,
+            instead: toolName,
+            kind: match.kind ?? "scenario",
+            key: match.key,
+            verified: match.verified?.verdict,
+            why: "the model's reasoning matched a calculated scenario's intent",
+        });
+        return this.preToolAnswer(this.replay.deliverInstead(directive, toolName));
+    }
+    /**
+     * Schedule a fragment once a matched turn's plan has handed over (fallbk.md
+     * D7). Only a turn that is not already recording needs one: an unmatched turn
+     * whose intent-armed plan handed over is recording the model's work anyway.
+     */
+    noteHandover(run) {
+        if (run.fragment || run.recording || run.finished)
+            return;
+        const state = run.replay;
+        const h = state?.handover;
+        if (!h || !state?.scenarioId)
+            return;
+        run.fragment = { scenarioId: state.scenarioId, stepIndex: h.stepIndex, state: "due" };
+    }
+    /**
+     * Open the fragment run and record from this call on (fallbk.md D7).
+     *
+     * The run id is swapped in place: steps allocated before belonged to a turn
+     * the service never created a run for, and nothing of theirs may land in the
+     * fragment — so pending correlations are latched and built-ins forgotten.
+     */
+    async openFragment(session, run, reasoning, toolName, args) {
+        const f = run.fragment;
+        if (!f || f.state !== "due")
+            return;
+        const input = reasoning.trim() || `${toolName} ${serializeCapped(redact(args))}`.slice(0, 2_000);
+        const fallbackOf = { scenarioId: f.scenarioId, stepIndex: f.stepIndex };
+        const id = this.recorder.startRun(input, { ...this.runMetadata(session), fallbackOf }, { fallbackOf });
+        for (const c of run.correlations.values()) {
+            c.settled = true;
+            if (c.fallback)
+                clearTimeout(c.fallback);
+        }
+        run.builtIns.clear();
+        run.runId = id;
+        run.ordering = new StepIndexAllocator();
+        run.recording = true;
+        f.state = "open";
+        f.usageMark = markTranscriptUsage(session.transcriptPath);
+        f.startedAtMs = Date.now();
+        logLine("run.fragment", {
+            run: id,
+            scenario: f.scenarioId,
+            step: f.stepIndex,
+            why: "recording the agent's own work after the scenario handed over",
+        });
+        if (isRunCreationAware(this.recorder)) {
+            const created = await this.withinBudget(this.recorder.runCreated(id), this.replay.budgets.matchMs);
+            if (created && !created.created) {
+                run.recording = false;
+                f.state = "hit";
+                // Which run it hit matters from here on: this turn must not count step
+                // hits against the fragment it is a repeat of (segmented.md R-HIT-7).
+                f.hitRunId = created.fragmentOf?.runId;
+                logLine("run.fragment_hit", {
+                    run: id,
+                    scenario: f.scenarioId,
+                    step: f.stepIndex,
+                    of: created.fragmentOf?.runId,
+                    why: "a hand-over at this step was recorded before — counted as a hit, not recorded",
+                });
+            }
+        }
+    }
+    /** Resolve with `p`, or null once `ms` passes or it rejects. */
+    async withinBudget(p, ms) {
+        let timer;
+        const budget = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), ms);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([p, budget]);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * `PostToolUse`, and where a hand-over noticed while threading this call's
+     * output reaches the model at once, as `additionalContext` (fallbk.md D4).
+     */
+    onToolPost(payload) {
+        const out = this.toolPost(payload);
+        const run = this.sessions.get(payload.session_id ?? "unknown-session")?.run;
+        if (!run || run.finished)
+            return out;
+        this.noteHandover(run);
+        const note = this.replay.takeNote(run.replay);
+        if (!note)
+            return out;
+        return {
+            ...out,
+            hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: note },
+        };
+    }
     /**
      * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
      * For a correlated MCP call it normally does nothing — the proxy owns that
@@ -728,7 +1216,7 @@ export class ControlServer {
      * or the call never reached it), the hook's own view is recorded after
      * {@link PROXY_REPORT_GRACE_MS} rather than the step being lost entirely.
      */
-    onToolPost(payload) {
+    toolPost(payload) {
         const session = this.ensureSession(payload);
         const run = this.ensureRun(session);
         const toolUseId = payload.tool_use_id ?? "";
@@ -1004,6 +1492,7 @@ export class ControlServer {
                     correlation.threadFallback = undefined;
                 }
                 this.replay.postTool(run.replay, toolUseId, serializeCapped(redact(report.result)));
+                this.noteHandover(run);
             }
             if (correlation.settled) {
                 logDetail("proxy.step.deduped", { run: run.runId, tool: report.qualifiedName });
@@ -1088,6 +1577,10 @@ export class ControlServer {
             isError: data.isError,
             errorMessage: data.errorMessage,
             context: correlation.context,
+            // Carried from where the correlation was created: by now the pin is gone
+            // from the map (segmented.md R-INTENT-7).
+            pinnedBy: correlation.pinnedBy,
+            intent: correlation.intent,
         });
         logDetail("proxy.step.merged", {
             run: run.runId,
@@ -1111,6 +1604,8 @@ export class ControlServer {
                 toolName: d.toolName,
                 toolInput,
                 context: d.context,
+                intent: d.intent?.source === "thinking" ? { text: d.intent.text, source: "thinking" } : undefined,
+                metadata: d.pinnedBy ? { pinnedBy: d.pinnedBy } : undefined,
             });
             this.recorder.recordToolResponse(run.runId, pair.response, {
                 toolName: d.toolName,