@basein/runner 0.2.2 → 0.2.4

package/dist/bin/bir.js

@@ -576,6 +576,17 @@ async function doctor(args) {
         problems.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
             `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
     }
+    // THE SCENARIO SERVER IS ON THE CRITICAL PATH OF THE FIRST TURN. A plan armed
+    // at `UserPromptSubmit` is delivered through `mcp__bir__run_scenario`, so a
+    // `bir` entry that starts with `npx` has to resolve and unpack the package
+    // before the tool exists at all — measured at ~13s, against a first tool call
+    // ~6s in. The turn does not fail; it just quietly runs the ordinary way, which
+    // is the failure this whole command exists to make visible.
+    const scenarioEntry = entries.find((e) => e.name === SCENARIO_SERVER_KEY);
+    if (scenarioEntry && !isRemote(scenarioEntry.config) && scenarioEntry.config.command === "npx") {
+        notes.push("the bir scenario server starts via npx, which can take longer than the first tool call " +
+            "of a turn — reinstall with `bir install --replay --global` to pin it to the installed copy");
+    }
     const sidecar = readSidecar();
     if (sidecar.controlPort && discovery && !discovery.url.endsWith(`:${sidecar.controlPort}`)) {
         problems.push(`hooks were installed for port ${sidecar.controlPort} but the control server is on ${discovery.url}`);
@@ -796,6 +807,14 @@ async function replayCommand(args) {
         }
         const r = body;
         out(`params      ${JSON.stringify(r.params ?? {})}`);
+        // The difference between "this scenario works" and "this scenario works on
+        // last week's values". A dry replay fills an unnamed target from the
+        // recording; a real turn never does, so without this line a green trace here
+        // is no evidence at all that a session would steer.
+        if (r.targetsFromSamples?.length) {
+            out(`            ↑ not named by the prompt: ${r.targetsFromSamples.join(", ")}`);
+            out("              (a live turn finds these in an earlier step, or does not run)");
+        }
         (r.steps ?? []).forEach((s, i) => {
             out(`step ${i}      ${s.toolName}  ${JSON.stringify(s.input)}`);
             const emitted = Object.keys(s.emitted ?? {});

package/dist/control/client.d.ts

@@ -23,11 +23,23 @@ export interface ProxyWork {
     arguments: unknown;
     timeoutMs: number;
 }
+/**
+ * Who a proxy is, sent with every register, poll and step report. The control
+ * server uses it to run a session's replay steps on that session's own upstream
+ * rather than on whichever proxy polled first (see replay/executor.ts).
+ */
+export interface ProxyIdentity {
+    proxyId: string;
+    /** Process start, epoch ms. */
+    startedAt: number;
+    pid: number;
+}
 export declare class ControlClient {
     private readonly url;
     private readonly token;
     private readonly timeoutMs;
-    constructor(url: string, token: string, timeoutMs?: number);
+    private readonly identity?;
+    constructor(url: string, token: string, timeoutMs?: number, identity?: ProxyIdentity);
     register(info: {
         serverName: string;
         pid: number;

package/dist/control/client.js

@@ -10,18 +10,21 @@ export class ControlClient {
     url;
     token;
     timeoutMs;
-    constructor(url, token, timeoutMs = 5_000) {
+    identity;
+    constructor(url, token, timeoutMs = 5_000, identity) {
         this.url = url.replace(/\/+$/, "");
         this.token = token;
         this.timeoutMs = timeoutMs;
+        this.identity = identity;
     }
     async register(info) {
-        const body = await this.post("/proxy/register", info);
+        const body = await this.post("/proxy/register", { ...this.identity, ...info });
         return body;
     }
     /** Report one completed MCP call. Resolves false when the send was dropped. */
     async report(step) {
-        return (await this.post("/proxy/step", step)) !== undefined;
+        const body = this.identity ? { ...step, proxyId: this.identity.proxyId } : step;
+        return (await this.post("/proxy/step", body)) !== undefined;
     }
     async health() {
         return (await this.request("GET", "/health"));
@@ -36,7 +39,7 @@ export class ControlClient {
      * with a small delay so a dead server is not busy-looped.
      */
     async poll(serverName, holdMs) {
-        const body = (await this.request("POST", "/proxy/poll", { serverName, holdMs }, holdMs + 10_000));
+        const body = (await this.request("POST", "/proxy/poll", { ...this.identity, serverName, holdMs }, holdMs + 10_000));
         return body?.work;
     }
     /** Hand back one dispatched call's result, or the reason it could not run. */

package/dist/control/correlation.d.ts

@@ -49,6 +49,8 @@ export interface ProxyStepReport {
     /** Epoch ms. */
     startedAt: number;
     durationMs: number;
+    /** The reporting proxy, added by its control client. Absent from older proxies. */
+    proxyId?: string;
 }
 export declare function newCallId(): string;
 /**

package/dist/control/server.d.ts

@@ -328,6 +328,14 @@ export declare class ControlServer {
      *      hooks produces and is a complete MCP step in its own right.
      */
     private onProxyStep;
+    /**
+     * Tie the reporting proxy to the session whose hook minted the step's call id,
+     * so that session's replay steps run on this proxy's upstream and not on
+     * another session's (replay/executor.ts). Searches every session, not just the
+     * one {@link sessionForProxyStep} records into: with two sessions open, that
+     * guess is exactly what cannot be trusted.
+     */
+    private learnProxySession;
     /**
      * Which session a proxy's step belongs to.
      *

package/dist/control/server.js

@@ -443,6 +443,7 @@ export class ControlServer {
             const state = await this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", {
                 recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
             });
+            state.sessionId = session.sessionId;
             run.replay = state;
             run.replays.push(state);
             return this.replay.directiveFor(state);
@@ -1077,6 +1078,7 @@ export class ControlServer {
             liveCall: { toolName, toolInput },
             recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
         });
+        state.sessionId = session.sessionId;
         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.
@@ -1353,6 +1355,8 @@ export class ControlServer {
     async onSessionEnd(payload) {
         const session = this.ensureSession(payload);
         await this.finalizeRun(session);
+        // Its proxies outlive it after a `/clear`, and serve the next session.
+        this.replay.work.releaseSession(session.sessionId);
         return {};
     }
     // ── proxy routes ─────────────────────────────────────────────────────────
@@ -1368,7 +1372,12 @@ export class ControlServer {
             at: Date.now(),
             version: proxyVersion,
         });
-        logLine("proxy.registered", { server: serverName, pid: body.pid, version: proxyVersion });
+        logLine("proxy.registered", {
+            server: serverName,
+            pid: body.pid,
+            version: proxyVersion,
+            proxy: typeof body.proxyId === "string" ? body.proxyId.slice(-8) : undefined,
+        });
         // A half-upgraded machine is the update failure that looks like success:
         // `npm i -g` replaced the package, but a config still points at an older
         // copy, or this hooks process predates the upgrade and was never
@@ -1413,7 +1422,13 @@ export class ControlServer {
         if (!this.replay.enabled)
             return {};
         const hold = Number(body.holdMs);
-        const work = await this.replay.work.waitForWork(serverName, Number.isFinite(hold) && hold > 0 ? Math.min(hold, POLL_HOLD_MS) : POLL_HOLD_MS, signal);
+        const startedAt = Number(body.startedAt);
+        const pid = Number(body.pid);
+        const work = await this.replay.work.waitForWork(serverName, Number.isFinite(hold) && hold > 0 ? Math.min(hold, POLL_HOLD_MS) : POLL_HOLD_MS, signal, {
+            proxyId: typeof body.proxyId === "string" ? body.proxyId : undefined,
+            startedAt: Number.isFinite(startedAt) ? startedAt : undefined,
+            pid: Number.isFinite(pid) ? pid : undefined,
+        });
         return work ? { work } : {};
     }
     /** `POST /proxy/result` — the answer to one dispatched `tools/call`. */
@@ -1478,6 +1493,7 @@ export class ControlServer {
      *      hooks produces and is a complete MCP step in its own right.
      */
     onProxyStep(report) {
+        this.learnProxySession(report);
         const session = this.sessionForProxyStep();
         const run = this.ensureRun(session);
         this.wrapped.add(report.serverName);
@@ -1534,6 +1550,23 @@ export class ControlServer {
         });
         return { stepIndex: pair.selected, merged: false };
     }
+    /**
+     * Tie the reporting proxy to the session whose hook minted the step's call id,
+     * so that session's replay steps run on this proxy's upstream and not on
+     * another session's (replay/executor.ts). Searches every session, not just the
+     * one {@link sessionForProxyStep} records into: with two sessions open, that
+     * guess is exactly what cannot be trusted.
+     */
+    learnProxySession(report) {
+        if (!report.proxyId || !report.callId)
+            return;
+        for (const session of this.sessions.values()) {
+            if (session.run?.correlations.has(report.callId)) {
+                this.replay.work.bindProxy(report.proxyId, session.sessionId);
+                return;
+            }
+        }
+    }
     /**
      * Which session a proxy's step belongs to.
      *

package/dist/proxy/session.d.ts

@@ -47,6 +47,8 @@ export interface ProxySessionOptions {
 }
 export declare class ProxySession {
     readonly serverName: string;
+    /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
+    readonly proxyId: string;
     private readonly opts;
     private tierValue;
     private control?;

package/dist/proxy/session.js

@@ -21,6 +21,7 @@
  * flushed into whichever owner wins. Nothing is lost to the race, and nothing
  * blocks: relaying never waits on this.
  */
+import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
 import { ControlClient } from "../control/client.js";
 import { resolveControl } from "../control/discovery.js";
@@ -38,6 +39,8 @@ import { packageVersion } from "../util/version.js";
 export const DISCOVERY_WINDOW_MS = 5_000;
 export class ProxySession {
     serverName;
+    /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
+    proxyId = "birproxy_" + randomUUID();
     opts;
     tierValue = "pending";
     control;
@@ -100,7 +103,11 @@ export class ProxySession {
             await this.becomeStandalone(`no control server within ${window}ms`);
             return;
         }
-        const client = new ControlClient(found.url, found.token);
+        const client = new ControlClient(found.url, found.token, undefined, {
+            proxyId: this.proxyId,
+            startedAt: this.startedAt,
+            pid: process.pid,
+        });
         const registered = await client.register({
             serverName: this.serverName,
             pid: process.pid,

package/dist/record/recorder.d.ts

@@ -263,6 +263,17 @@ export interface ExecutionReport {
      * two baselines of one turn. The segments' own rows are untouched.
      */
     sharedWith?: string[];
+    /**
+     * Which gate of the ladder declined, on a `not_steered` report.
+     *
+     * The one thing the recording page could never learn. "Replay on, scenario
+     * ready, prompt matched, nothing steered" has exactly one explanation and it
+     * used to live only in a stderr line on the machine that decided it — so the
+     * owner of a scenario that never runs had nothing to look at. It travels as
+     * the gate's own code rather than the sentence beside it: the prose is for a
+     * person reading the audit log, this is for the console.
+     */
+    declined?: string;
 }
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {

package/dist/record/remote-recorder.js

@@ -212,6 +212,9 @@ export class RemoteRecorder {
                 fallbackKind: report.fallbackKind,
                 baselineEligible: report.baselineEligible,
                 sharedWith: report.sharedWith,
+                // 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,
             });
             const r = (body ?? {});
             const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
@@ -228,6 +231,7 @@ export class RemoteRecorder {
                 stepsFailed: failed || undefined,
                 baselineEligible: report.baselineEligible === false ? false : undefined,
                 sharedWith: report.sharedWith?.length,
+                declined: report.declined,
             });
         });
     }

package/dist/replay/controller.d.ts

@@ -158,6 +158,12 @@ export interface ReplayState {
     retired: boolean;
     /** What armed it: the prompt, or a ReAct iteration's intent (fallbk.md). */
     armedBy: "prompt" | "intent";
+    /**
+     * 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
+     * replay`, which has no session and takes the newest proxy.
+     */
+    sessionId?: string;
     /**
      * Which kind of row was handed out (segmented.md R-OUT-7). A `segment` is a
      * named sub-task of a recording rather than a whole task, and it is judged

package/dist/replay/controller.js

@@ -25,6 +25,7 @@ import { ScenarioReplayPlan } from "./plan.js";
 import { PRICING_VERSION } from "./pricing.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { clampToFrameStart, flattenChain, } from "./flatten.js";
+import { blockingTargets } from "./targets.js";
 import { toolResultError } from "./tool-error.js";
 import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
@@ -233,29 +234,60 @@ export class ReplayController {
         // because it is the only one that spends a model call and waits. A scenario
         // whose parameters are all settings arms at once, as before: there is
         // nothing the turn has to supply.
+        //
+        // A target the turn did not name stops the plan only when *this* plan could
+        // act on its recorded value; a target the chain discovers for itself does
+        // not ({@link ./targets.ts}). The unnamed value stays null either way, so
+        // nothing here ever runs on last week's.
         if (hasTargets(scenario.paramsObject)) {
+            // Of the targets this answer left unnamed, the ones this plan could act
+            // on the recorded value of. Empty means the chain finds them for itself.
+            const blocking = (missing) => blockingTargets(missing, scenario.paramsObject, planned);
             let result;
             try {
                 result = await this.withBudget(derivation, this.budgets.deriveMs, "derivation");
             }
             catch (err) {
-                // Out of budget, or the call threw. Either way the turn has not said
-                // what this task is to act on, and running it would act on something
-                // else (R-PARAM-3).
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`target ${first ?? "(unknown)"} not found — ${errText(err)}`, "missing_target");
+                // Out of budget, or the call threw. The turn has not said what this task
+                // is to act on, so every target is unnamed (R-PARAM-3).
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found — ${errText(err)}`, "missing_target");
+                }
+                logLine("replay.targets_unread", {
+                    scenario: scenario.id,
+                    why: "the derivation did not answer, and this chain takes no target from the caller",
+                    error: errText(err),
+                });
             }
-            if (!result.derived) {
+            if (result && !result.derived) {
                 // Nobody read the turn — no key here and no service to ask, or the
                 // service declined. Settings can still take their recorded values, but a
                 // target is a guess nobody is allowed to make (R-PARAM-5). The reason
                 // travels into the line, because "it did not run" without one is how
                 // this stayed invisible before.
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`${result.reason ?? "no_derive_key"}: target ${first ?? "(unknown)"}`, "no_derive_key");
+                //
+                // Every target is judged, not `missing`: an answer that derived nothing
+                // carries the recorded sample for *all* of them, so a chain that reads
+                // one would run on last week's value rather than on nothing.
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`${result.reason ?? "no_derive_key"}: target ${blocked[0]}`, "no_derive_key");
+                }
             }
-            if (result.missing.length > 0) {
-                return decline(`target ${result.missing[0]} not found`, "missing_target");
+            else if (result && result.missing.length > 0) {
+                const blocked = blocking(result.missing);
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found`, "missing_target");
+                }
+                // Worth a line of its own: this is the difference between a scenario
+                // that never runs and one that does, and it is the first thing to look
+                // at when a replay acts on the wrong thing.
+                logLine("replay.targets_found_by_chain", {
+                    scenario: scenario.id,
+                    unnamed: result.missing.join(","),
+                    why: "the chain computes these from its own steps; none is read from the caller",
+                });
             }
         }
         // A plan armed by intent runs inside a task the agent is already doing, so
@@ -584,7 +616,7 @@ export class ReplayController {
         const deadline = Date.now() + this.budgets.planMs;
         let result;
         try {
-            result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true });
+            result = await plan.runToCompletion(this.executeStep(state), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true });
         }
         catch (err) {
             // The scenario's own logic failed. Retire and let the model do the work.
@@ -681,10 +713,14 @@ export class ReplayController {
         const total = state.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* a step actually broke,
-        // which is the one thing the recording page cannot learn any other way. The
-        // service accepts a costless report that says why (its errorshandling.md).
-        if (isBaseline && total <= 0 && !steps?.some((s) => s.status === "failed")) {
+        // A costless decline is noise on both sides — *unless* it says something the
+        // recording page cannot learn any other way: a step that actually broke, or
+        // the gate that declined. The service accepts a costless report that carries
+        // either (its errorshandling.md).
+        if (isBaseline &&
+            total <= 0 &&
+            !state.declined &&
+            !steps?.some((s) => s.status === "failed")) {
             return undefined;
         }
         const blame = this.blameStep(steps);
@@ -709,6 +745,10 @@ export class ReplayController {
             errorStage: blame?.stage,
             errorStepIndex: blame?.stepIndex,
             errorToolName: blame?.toolName,
+            // Which gate said no. Only ever set on a decline, and the decline is
+            // always `not_steered`, so a steered report carries it byte-identically
+            // to before.
+            declined: state.declined,
             // Where the plan handed the task to the model (fallbk.md). Only on
             // `fell_back`: a hand-over before any step ran is `failed`, and a parked
             // step found after a divergence is still a divergence.
@@ -849,7 +889,7 @@ export class ReplayController {
         }
         const trace = [];
         try {
-            const result = await plan.runToCompletion(this.executeStep(), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, (info) => {
+            const result = await plan.runToCompletion(this.executeStep(state), state.sourceRun ? (entry) => state.sourceRun.outputFor(entry) : undefined, (info) => {
                 this.observeStep(state)(info);
                 trace.push({
                     step: info.step.stepIndex,
@@ -983,7 +1023,7 @@ export class ReplayController {
         this.retire(state, undefined);
         let composed;
         try {
-            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), 
+            composed = await plan.composeBundle(MAX_REPLAY_REASON, this.executeStep(state), state.sourceRun ? (step) => state.sourceRun.outputFor(step) : undefined, this.observeStep(state), 
             // A parked step ends the bundle short of the task (fallbk.md D3).
             { handover: plan.stopsEarly() });
         }
@@ -1135,13 +1175,13 @@ export class ReplayController {
      * under which a recorded output may stand in. A tool that ran and failed
      * resolves with its failure as the response, exactly as it would in a session.
      */
-    executeStep() {
+    executeStep(state) {
         return async (step, input) => {
             const mcp = parseQualifiedName(step.toolName ?? "");
             if (!mcp) {
                 throw new Error(`${step.toolName} is not an MCP tool — it can only run in the session`);
             }
-            const result = await this.work.call(mcp.serverName, mcp.toolName, input, this.budgets.stepMs);
+            const result = await this.work.call(mcp.serverName, mcp.toolName, input, this.budgets.stepMs, { sessionId: state.sessionId });
             // Serialize exactly as the proxy records it, or `toolOutputLogic` — which
             // was authored against that shape — silently derives nothing (§7.2).
             return serializeCapped(redact(result));
@@ -1292,11 +1332,11 @@ export class ReplayController {
         });
     }
 }
-/** The first target of a schema, for the sentence a decline logs. */
-function firstTargetKey(schema) {
+/** Every target of a schema. A parameter with no kind is one (R-PARAM-3). */
+function targetKeys(schema) {
     if (!schema)
-        return undefined;
-    return Object.keys(schema).find((k) => schema[k]?.kind !== "setting");
+        return [];
+    return Object.keys(schema).filter((k) => schema[k]?.kind !== "setting");
 }
 /**
  * Position of the first step whose failure count is above `maxStepFailures`

package/dist/replay/executor.d.ts

@@ -18,6 +18,36 @@
  * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
  * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
  * the step's recorded output.
+ *
+ * WHICH PROXY. Several proxies can poll for the same server at once — one per
+ * Claude Code session in the project, and a session's proxy outlives a
+ * `bir-hooks` restart by simply re-polling. They are NOT interchangeable: each
+ * holds its own upstream, and another session's upstream may be in any state (a
+ * database connection a benchmark reset killed, a browser on another page).
+ * Handing a step to "whoever is parked first" therefore ran it on the oldest
+ * proxy in the project, which is precisely the one most likely to be stale. So
+ * every proxy polls under its own id, and a step goes to, in order:
+ *
+ *   1. a proxy bound to the step's session — learned from a correlated step the
+ *      proxy reported, or from an earlier step of this session it ran;
+ *   2. otherwise the newest unbound proxy (latest process start) — a session's
+ *      proxies are spawned when it starts, so the newest is the best guess for
+ *      a session that has not called the server yet;
+ *   3. otherwise NOBODY. A proxy bound to another session is never used for
+ *      this one: the step resolves as a tool error, so the plan stops and hands
+ *      over to the agent, who calls the tool on its own upstream. It does not
+ *      reject — a rejection lets a recorded output stand in, or skips the step
+ *      and runs the rest of the plan past it.
+ *
+ * A session's bindings are released when it ends (a `/clear` starts a new
+ * session on the same proxies). Legacy proxies, which send no id, share one
+ * record per server and are never bound: they stay a pool anyone may use.
+ *
+ * `bir replay` has no session, and takes the newest proxy, bound or not.
+ *
+ * The choice is made against proxies that are *present*, parked or not, and the
+ * work is then held for that proxy if it is mid-round-trip — never handed to a
+ * different one that happens to be parked.
  */
 /** One dispatched tool call, as the proxy receives it. */
 export interface Work {
@@ -27,30 +57,47 @@ export interface Work {
     arguments: unknown;
     timeoutMs: number;
 }
+/** Who a dispatched step is for — decides which proxy runs it. */
+export interface WorkRoute {
+    /** The Claude Code session whose plan this step belongs to. */
+    sessionId?: string;
+}
+/** What a polling proxy says about itself. All optional: older proxies send none. */
+export interface PollerIdentity {
+    /** Stable for the proxy process's lifetime. */
+    proxyId?: string;
+    /** When the proxy process started, epoch ms — "newest" is judged by this. */
+    startedAt?: number;
+    pid?: number;
+}
 /** Rejection reason when no proxy is polling for a server. */
 export declare const NO_PROXY = "no_proxy";
 export declare class ProxyWorkQueue {
-    /** Work dispatched while its proxy was mid-round-trip, per server. */
+    /** Work held for a proxy that was mid-round-trip when it was dispatched, per proxy id. */
     private readonly pending;
     /** Pollers currently parked, per server. */
     private readonly waiters;
     /** Work handed out and awaiting a result. */
     private readonly inFlight;
-    /** serverName → when it last polled. A proxy between polls is still present. */
-    private readonly lastSeen;
+    /** Every proxy that has polled, by id. A proxy between polls is still present. */
+    private readonly proxies;
     private closed;
     /** Servers a proxy is currently serving — what `bir doctor` reports. */
     pollingServers(): string[];
     /** True when a proxy for `serverName` is available to take work. */
     hasPoller(serverName: string): boolean;
-    /** Parked now, or polled recently enough to be mid-round-trip. */
-    private isPresent;
+    /**
+     * Record that `proxyId` serves `sessionId`: it reported a call whose id the
+     * session's own hook minted. Proof, so it replaces any earlier binding — a
+     * `/clear` starts a new session on the same proxies.
+     */
+    bindProxy(proxyId: string, sessionId: string): void;
     /**
      * `POST /proxy/poll`. Resolves with work, or with `undefined` at the poll
-     * deadline so the proxy re-polls. Work queued while this proxy was between
-     * polls is handed over immediately.
+     * deadline so the proxy re-polls. Work held for this proxy while it was
+     * between polls is handed over immediately.
      */
-    waitForWork(serverName: string, pollDeadlineMs: number, signal?: AbortSignal): Promise<Work | undefined>;
+    waitForWork(serverName: string, pollDeadlineMs: number, signal?: AbortSignal, who?: PollerIdentity): Promise<Work | undefined>;
     /** `POST /proxy/result`. Unknown ids are ignored — a late result after a timeout. */
     complete(workId: string, result?: unknown, error?: string): boolean;
     /**
@@ -61,16 +108,40 @@ export declare class ProxyWorkQueue {
      * "could not be run here", which is exactly the condition under which the
      * caller may substitute a recorded output.
      */
-    call(serverName: string, toolName: string, args: unknown, timeoutMs: number): Promise<unknown>;
+    call(serverName: string, toolName: string, args: unknown, timeoutMs: number, route?: WorkRoute): Promise<unknown>;
     /** Remove queued work that timed out, so a later poll never gets stale work. */
     private dropPending;
     /** Fail everything in flight and release every poller. */
     close(): void;
+    /** Note a poll: create the proxy's record on first sight, refresh it after. */
+    private touch;
+    /** Parked now, or polled recently enough to be mid-round-trip. */
+    private isLive;
+    /** Live proxies for a server, newest first. */
+    private present;
+    /**
+     * The proxy a step for `sessionId` should run on — see the file comment.
+     * Undefined when no proxy is live at all; `other_sessions` when every live
+     * one belongs to a different session.
+     */
+    private pickProxy;
     /**
-     * The oldest *live* poller. Waiters whose request has already gone are
-     * discarded rather than handed work they can never run.
+     * Free every proxy bound to `sessionId`: the session ended. After a `/clear`
+     * the same proxies serve the next session, which must be able to pick them.
+     */
+    releaseSession(sessionId: string): void;
+    /**
+     * A live parked poller of `proxyId`. Waiters whose request has already gone
+     * are discarded rather than handed work they can never run.
      */
     private takeWaiter;
+    /**
+     * A proxy whose poll request closed has, almost always, exited. Forget it
+     * unless another of its polls is still parked, so it is never picked for a
+     * minute after it died. A proxy that merely lost one request re-registers on
+     * its next poll.
+     */
+    private forgetIfGone;
     private removeWaiter;
     /** Drop a waiter's timer and abort listener. Idempotent. */
     private detach;

package/dist/replay/executor.js

@@ -18,6 +18,36 @@
  * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
  * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
  * the step's recorded output.
+ *
+ * WHICH PROXY. Several proxies can poll for the same server at once — one per
+ * Claude Code session in the project, and a session's proxy outlives a
+ * `bir-hooks` restart by simply re-polling. They are NOT interchangeable: each
+ * holds its own upstream, and another session's upstream may be in any state (a
+ * database connection a benchmark reset killed, a browser on another page).
+ * Handing a step to "whoever is parked first" therefore ran it on the oldest
+ * proxy in the project, which is precisely the one most likely to be stale. So
+ * every proxy polls under its own id, and a step goes to, in order:
+ *
+ *   1. a proxy bound to the step's session — learned from a correlated step the
+ *      proxy reported, or from an earlier step of this session it ran;
+ *   2. otherwise the newest unbound proxy (latest process start) — a session's
+ *      proxies are spawned when it starts, so the newest is the best guess for
+ *      a session that has not called the server yet;
+ *   3. otherwise NOBODY. A proxy bound to another session is never used for
+ *      this one: the step resolves as a tool error, so the plan stops and hands
+ *      over to the agent, who calls the tool on its own upstream. It does not
+ *      reject — a rejection lets a recorded output stand in, or skips the step
+ *      and runs the rest of the plan past it.
+ *
+ * A session's bindings are released when it ends (a `/clear` starts a new
+ * session on the same proxies). Legacy proxies, which send no id, share one
+ * record per server and are never bound: they stay a pool anyone may use.
+ *
+ * `bir replay` has no session, and takes the newest proxy, bound or not.
+ *
+ * The choice is made against proxies that are *present*, parked or not, and the
+ * work is then held for that proxy if it is mid-round-trip — never handed to a
+ * different one that happens to be parked.
  */
 import { randomUUID } from "node:crypto";
 import { logDetail } from "../util/log.js";
@@ -32,44 +62,70 @@ export const NO_PROXY = "no_proxy";
  * plan lose every step after the first.
  */
 const PRESENT_MS = 60_000;
+/**
+ * The id a proxy that sends none polls under. One per server, so older proxies
+ * keep the old behaviour between themselves: any of them may take the work.
+ */
+function legacyId(serverName) {
+    return `legacy:${serverName}`;
+}
 export class ProxyWorkQueue {
-    /** Work dispatched while its proxy was mid-round-trip, per server. */
+    /** Work held for a proxy that was mid-round-trip when it was dispatched, per proxy id. */
     pending = new Map();
     /** Pollers currently parked, per server. */
     waiters = new Map();
     /** Work handed out and awaiting a result. */
     inFlight = new Map();
-    /** serverName → when it last polled. A proxy between polls is still present. */
-    lastSeen = new Map();
+    /** Every proxy that has polled, by id. A proxy between polls is still present. */
+    proxies = new Map();
     closed = false;
     /** Servers a proxy is currently serving — what `bir doctor` reports. */
     pollingServers() {
-        const now = Date.now();
-        return [...this.lastSeen.entries()]
-            .filter(([, at]) => now - at <= PRESENT_MS)
-            .map(([name]) => name);
+        const names = new Set();
+        for (const info of this.proxies.values()) {
+            if (this.isLive(info))
+                names.add(info.serverName);
+        }
+        return [...names];
     }
     /** True when a proxy for `serverName` is available to take work. */
     hasPoller(serverName) {
         if ((this.waiters.get(serverName)?.length ?? 0) > 0)
             return true;
-        return this.isPresent(serverName);
+        return this.present(serverName).length > 0;
     }
-    /** Parked now, or polled recently enough to be mid-round-trip. */
-    isPresent(serverName) {
-        const at = this.lastSeen.get(serverName);
-        return at !== undefined && Date.now() - at <= PRESENT_MS;
+    /**
+     * Record that `proxyId` serves `sessionId`: it reported a call whose id the
+     * session's own hook minted. Proof, so it replaces any earlier binding — a
+     * `/clear` starts a new session on the same proxies.
+     */
+    bindProxy(proxyId, sessionId) {
+        const info = this.proxies.get(proxyId);
+        if (!info)
+            return;
+        if (info.sessionId === sessionId && info.boundBy === "correlated")
+            return;
+        info.sessionId = sessionId;
+        info.boundBy = "correlated";
+        logDetail("replay.proxy_bound", {
+            server: info.serverName,
+            proxy: shortId(proxyId),
+            pid: info.pid,
+            sess: sessionId,
+            by: "correlated",
+        });
     }
     /**
      * `POST /proxy/poll`. Resolves with work, or with `undefined` at the poll
-     * deadline so the proxy re-polls. Work queued while this proxy was between
-     * polls is handed over immediately.
+     * deadline so the proxy re-polls. Work held for this proxy while it was
+     * between polls is handed over immediately.
      */
-    waitForWork(serverName, pollDeadlineMs, signal) {
+    waitForWork(serverName, pollDeadlineMs, signal, who = {}) {
         if (this.closed)
             return Promise.resolve(undefined);
-        this.lastSeen.set(serverName, Date.now());
-        const queued = this.pending.get(serverName);
+        const proxyId = who.proxyId || legacyId(serverName);
+        this.touch(proxyId, serverName, who);
+        const queued = this.pending.get(proxyId);
         if (queued && queued.length > 0) {
             return Promise.resolve(queued.shift());
         }
@@ -79,6 +135,7 @@ export class ProxyWorkQueue {
             const list = this.waiters.get(serverName) ?? [];
             const waiter = {
                 serverName,
+                proxyId,
                 resolve,
                 signal,
                 timer: setTimeout(() => {
@@ -90,6 +147,7 @@ export class ProxyWorkQueue {
                 waiter.onAbort = () => {
                     logDetail("replay.poller_gone", { server: serverName, why: "its request closed" });
                     this.removeWaiter(waiter);
+                    this.forgetIfGone(proxyId);
                     resolve(undefined);
                 };
                 signal.addEventListener("abort", waiter.onAbort, { once: true });
@@ -120,18 +178,36 @@ export class ProxyWorkQueue {
      * "could not be run here", which is exactly the condition under which the
      * caller may substitute a recorded output.
      */
-    call(serverName, toolName, args, timeoutMs) {
+    call(serverName, toolName, args, timeoutMs, route = {}) {
         if (this.closed)
             return Promise.reject(new Error(NO_PROXY));
-        const work = { workId: "birwork_" + randomUUID(), toolName, arguments: args, timeoutMs };
-        const waiter = this.takeWaiter(serverName);
-        if (!waiter && !this.isPresent(serverName)) {
+        const picked = this.pickProxy(serverName, route.sessionId);
+        if (!picked) {
             // No proxy has ever polled for this server, or one has been gone for a
             // minute. Do NOT queue: the caller is inside a turn the user is waiting on,
             // and work that sits until some proxy happens to appear would stall it past
             // every budget. Fail fast, and let the recorded-output fallback decide.
             return Promise.reject(new Error(NO_PROXY));
         }
+        if (picked === "other_sessions") {
+            const others = this.present(serverName).length;
+            logDetail("replay.no_session_proxy", {
+                server: serverName,
+                tool: toolName,
+                sess: route.sessionId,
+                others,
+                why: "only other sessions' proxies are here — the step is not run on their upstream",
+            });
+            return Promise.resolve(noSessionProxy(serverName, others));
+        }
+        const { info, why } = picked;
+        if (route.sessionId && !info.sessionId && !isLegacy(info.proxyId)) {
+            // Keep the rest of this session's plan on the same upstream.
+            info.sessionId = route.sessionId;
+            info.boundBy = "dispatched";
+        }
+        const work = { workId: "birwork_" + randomUUID(), toolName, arguments: args, timeoutMs };
+        const waiter = this.takeWaiter(serverName, info.proxyId);
         return new Promise((resolve, reject) => {
             const entry = {
                 serverName,
@@ -139,7 +215,7 @@ export class ProxyWorkQueue {
                 reject,
                 timer: setTimeout(() => {
                     this.inFlight.delete(work.workId);
-                    this.dropPending(serverName, work.workId);
+                    this.dropPending(info.proxyId, work.workId);
                     reject(new Error(`timeout after ${timeoutMs}ms`));
                 }, timeoutMs),
             };
@@ -149,23 +225,27 @@ export class ProxyWorkQueue {
                 server: serverName,
                 tool: toolName,
                 work: work.workId,
+                proxy: shortId(info.proxyId),
+                pid: info.pid,
+                pick: why,
                 queued: waiter ? undefined : true,
             });
             if (waiter) {
                 waiter.resolve(work);
                 return;
             }
-            // The proxy is mid-round-trip — POSTing the previous step's result, about
-            // to poll again. Hold the work for it; the per-call timeout above is what
-            // bounds the wait if it never comes back.
-            const list = this.pending.get(serverName) ?? [];
+            // The chosen proxy is mid-round-trip — POSTing the previous step's result,
+            // about to poll again. Hold the work for IT; another proxy that happens to
+            // be parked right now is not a substitute. The per-call timeout above is
+            // what bounds the wait if it never comes back.
+            const list = this.pending.get(info.proxyId) ?? [];
             list.push(work);
-            this.pending.set(serverName, list);
+            this.pending.set(info.proxyId, list);
         });
     }
     /** Remove queued work that timed out, so a later poll never gets stale work. */
-    dropPending(serverName, workId) {
-        const list = this.pending.get(serverName);
+    dropPending(proxyId, workId) {
+        const list = this.pending.get(proxyId);
         if (!list)
             return;
         const i = list.findIndex((w) => w.workId === workId);
@@ -184,33 +264,121 @@ export class ProxyWorkQueue {
         this.waiters.clear();
         this.pending.clear();
         // A closed queue has no proxies, whatever they were doing a moment ago.
-        this.lastSeen.clear();
+        this.proxies.clear();
         for (const [, entry] of this.inFlight) {
             clearTimeout(entry.timer);
             entry.reject(new Error("control server closed"));
         }
         this.inFlight.clear();
     }
+    /** Note a poll: create the proxy's record on first sight, refresh it after. */
+    touch(proxyId, serverName, who) {
+        const now = Date.now();
+        const info = this.proxies.get(proxyId);
+        if (info) {
+            info.lastSeen = now;
+            return;
+        }
+        const started = Number(who.startedAt);
+        this.proxies.set(proxyId, {
+            proxyId,
+            serverName,
+            startedAt: Number.isFinite(started) && started > 0 ? started : now,
+            pid: who.pid,
+            lastSeen: now,
+        });
+    }
+    /** Parked now, or polled recently enough to be mid-round-trip. */
+    isLive(info) {
+        return Date.now() - info.lastSeen <= PRESENT_MS;
+    }
+    /** Live proxies for a server, newest first. */
+    present(serverName) {
+        return [...this.proxies.values()]
+            .filter((p) => p.serverName === serverName && this.isLive(p))
+            .sort((a, b) => b.startedAt - a.startedAt);
+    }
+    /**
+     * The proxy a step for `sessionId` should run on — see the file comment.
+     * Undefined when no proxy is live at all; `other_sessions` when every live
+     * one belongs to a different session.
+     */
+    pickProxy(serverName, sessionId) {
+        const live = this.present(serverName);
+        if (live.length === 0)
+            return undefined;
+        if (!sessionId)
+            return { info: live[0], why: "newest" };
+        const mine = live.filter((p) => p.sessionId === sessionId);
+        const proven = mine.find((p) => p.boundBy === "correlated");
+        if (proven)
+            return { info: proven, why: "session" };
+        if (mine[0])
+            return { info: mine[0], why: "session" };
+        const unbound = live.find((p) => !p.sessionId);
+        if (unbound)
+            return { info: unbound, why: "newest" };
+        return "other_sessions";
+    }
     /**
-     * The oldest *live* poller. Waiters whose request has already gone are
-     * discarded rather than handed work they can never run.
+     * Free every proxy bound to `sessionId`: the session ended. After a `/clear`
+     * the same proxies serve the next session, which must be able to pick them.
      */
-    takeWaiter(serverName) {
+    releaseSession(sessionId) {
+        for (const info of this.proxies.values()) {
+            if (info.sessionId !== sessionId)
+                continue;
+            info.sessionId = undefined;
+            info.boundBy = undefined;
+            logDetail("replay.proxy_released", {
+                server: info.serverName,
+                proxy: shortId(info.proxyId),
+                pid: info.pid,
+                sess: sessionId,
+            });
+        }
+    }
+    /**
+     * A live parked poller of `proxyId`. Waiters whose request has already gone
+     * are discarded rather than handed work they can never run.
+     */
+    takeWaiter(serverName, proxyId) {
         const list = this.waiters.get(serverName);
         if (!list)
             return undefined;
-        for (;;) {
-            const waiter = list.shift();
-            if (!waiter)
-                return undefined;
-            this.detach(waiter);
+        for (let i = 0; i < list.length;) {
+            const waiter = list[i];
             if (waiter.signal?.aborted) {
                 // Its proxy is gone. Release the promise and keep looking.
+                list.splice(i, 1);
+                this.detach(waiter);
                 waiter.resolve(undefined);
                 continue;
             }
-            return waiter;
+            if (waiter.proxyId === proxyId) {
+                list.splice(i, 1);
+                this.detach(waiter);
+                return waiter;
+            }
+            i++;
         }
+        return undefined;
+    }
+    /**
+     * A proxy whose poll request closed has, almost always, exited. Forget it
+     * unless another of its polls is still parked, so it is never picked for a
+     * minute after it died. A proxy that merely lost one request re-registers on
+     * its next poll.
+     */
+    forgetIfGone(proxyId) {
+        for (const list of this.waiters.values()) {
+            if (list.some((w) => w.proxyId === proxyId && !w.signal?.aborted))
+                return;
+        }
+        if ((this.pending.get(proxyId)?.length ?? 0) > 0)
+            return;
+        this.proxies.delete(proxyId);
+        this.pending.delete(proxyId);
     }
     removeWaiter(waiter) {
         this.detach(waiter);
@@ -230,4 +398,29 @@ export class ProxyWorkQueue {
         }
     }
 }
+function isLegacy(proxyId) {
+    return proxyId.startsWith("legacy:");
+}
+/** Enough of an id to tell proxies apart in a log line. */
+function shortId(proxyId) {
+    return isLegacy(proxyId) ? proxyId : proxyId.slice(-8);
+}
+/**
+ * The step's result when only other sessions' proxies are here: an MCP tool
+ * error, so the plan stops on it and hands over (tool-error.ts), and the agent
+ * reads why.
+ */
+function noSessionProxy(serverName, others) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: bir did not run this step. No ${serverName} proxy of this session is ` +
+                    `connected; the ${others} that are belong to other sessions, and a step never ` +
+                    `runs on another session's upstream. Call the tool yourself.`,
+            },
+        ],
+    };
+}
 //# sourceMappingURL=executor.js.map

package/dist/replay/targets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+import type { FlatEntry } from "./flatten.js";
+import type { ParamsSchema } from "./types.js";
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export declare function blockingTargets(missing: readonly string[], schema: ParamsSchema | null | undefined, planned: readonly FlatEntry[]): string[];
+//# sourceMappingURL=targets.d.ts.map

package/dist/replay/targets.js

@@ -0,0 +1,133 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export function blockingTargets(missing, schema, planned) {
+    if (missing.length === 0)
+        return [];
+    if (!schema || planned.length === 0)
+        return [...missing];
+    const bodies = callerBodies(planned);
+    // Nothing to read the parameters: a plan with no logic at all cannot act on
+    // anything, but it is also not a shape worth reasoning about — keep it strict.
+    if (bodies.length === 0)
+        return [...missing];
+    return missing.filter((key) => bodies.some((body) => readsOutright(body, key) || carriesLiteral(body, schema[key]?.sampleValue)));
+}
+/**
+ * Every logic body that runs with the caller's own `parameters`.
+ *
+ * Both of a step's bodies, because `toolOutputLogic` is handed `parameters`
+ * too and a value baked in there travels just as far. Plus the `paramMapLogic`
+ * of each segment called directly from frame 0: it reads the caller's
+ * parameters to build the segment's.
+ */
+function callerBodies(planned) {
+    const bodies = [];
+    const seenFrames = new Set();
+    for (const entry of planned) {
+        if (entry.depth === 0) {
+            if (entry.step.toolInputLogic)
+                bodies.push(entry.step.toolInputLogic);
+            if (entry.step.toolOutputLogic)
+                bodies.push(entry.step.toolOutputLogic);
+            continue;
+        }
+        // The frame's own mapping, once, and only when its caller is frame 0.
+        const frame = entry.frame;
+        if (frame.depth !== 1 || seenFrames.has(frame.id))
+            continue;
+        seenFrames.add(frame.id);
+        if (frame.paramMapLogic)
+            bodies.push(frame.paramMapLogic);
+    }
+    return bodies;
+}
+/** `parameters.key`, `parameters["key"]`, `parameters['key']` — all three forms. */
+function referencePattern(key) {
+    const k = escapeRegExp(key);
+    return new RegExp(`parameters\\s*(?:\\.\\s*${k}\\b|\\[\\s*["']${k}["']\\s*\\])`, "g");
+}
+/**
+ * Whether `body` reads `key` other than as a fallback.
+ *
+ * A reference is a fallback when what stands immediately before it is `??` or
+ * `||` — the shape an analysis writes when the chain computes the value and
+ * keeps the caller's as a last resort. Every other reference is a read: the
+ * step wants the caller's value and nothing else will do.
+ */
+function readsOutright(body, key) {
+    const pattern = referencePattern(key);
+    for (let m = pattern.exec(body); m; m = pattern.exec(body)) {
+        const before = body.slice(0, m.index).trimEnd();
+        if (!before.endsWith("??") && !before.endsWith("||"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `body` carries the recorded sample as a literal.
+ *
+ * This is the case the parameter reference cannot see: `return { id: 'dev_4411' }`
+ * acts on last week's device without mentioning `parameters` at all. Read
+ * generously — a sample too short to search for (`1`, `on`) counts as carried,
+ * because a false "this plan is safe" is the one answer this file must not give.
+ */
+function carriesLiteral(body, sample) {
+    if (sample === null || sample === undefined)
+        return false;
+    const text = typeof sample === "string" ? sample : JSON.stringify(sample);
+    if (typeof text !== "string" || text.length === 0)
+        return false;
+    if (text.length < 3)
+        return true;
+    return body.includes(text);
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=targets.js.map

package/package.json

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