@basein/runner 0.2.3 → 0.2.4

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/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;

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/package.json

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