@basein/runner 0.2.3 → 0.2.5

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);
@@ -714,6 +715,15 @@ export class ControlServer {
             logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
             return {};
         }
+        // `run_scenario` with no live plan does nothing but answer "no scenario is
+        // armed". Recorded, that answer is a failed tool call, and a recording with
+        // one is never picked for calculation — observed in production on every
+        // first run in a project with the scenario server installed. With a live
+        // plan it is still recorded below, tagged `pinnedBy`.
+        if (this.replay.isDirectTool(toolName) && (!run.replay?.plan || run.replay.retired)) {
+            logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "no scenario armed" });
+            return {};
+        }
         const agentId = payload.agent_id ?? session.agentId;
         // The real intent, read from every line sharing this message's id
         // (segmented.md R-INTENT-3). `context` stays the *written* text only, with
@@ -1077,6 +1087,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.
@@ -1234,6 +1245,10 @@ export class ControlServer {
         // `tool_response` with no `tool_selected` before it.
         if (isHousekeeping(toolName))
             return {};
+        // Nor for an unarmed `run_scenario`. The plan may have retired since the
+        // pre hook, so the test is whether that hook opened a step, not the plan.
+        if (this.replay.isDirectTool(toolName) && !run.builtIns.has(toolUseId))
+            return {};
         const failed = payload.hook_event_name === "PostToolUseFailure" || payload.error !== undefined;
         // ── replay threading (docs/calculatedReplay.md §7.2) ─────────────────────
         // `toolOutputLogic` was authored against the bytes that were *recorded* for
@@ -1353,6 +1368,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 +1385,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 +1435,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 +1506,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 +1563,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/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

@@ -616,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.
@@ -889,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,
@@ -1023,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() });
         }
@@ -1175,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));

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;