@basein/runner 0.2.12 → 0.3.0

package/dist/proxy/session.js

@@ -9,30 +9,56 @@
  *   the run; this proxy only reports steps. Built-ins and MCP land in one
  *   ordered stream, with the prompt and the final answer.
  *
- *   **Tier 2 — Standalone.** No control server inside the discovery window. The
- *   proxy owns a run of its own and records MCP calls only — no prompt, no final
- *   answer, no built-in steps. That is not a degraded bug; it is the honest
- *   ceiling of what an MCP proxy can observe, and the run says so in
- *   `metadata.tier` so nothing downstream mistakes it for a complete trace.
+ *   **Tier 2 — Standalone.** No control server inside the discovery window, in
+ *   a project that asked to be recorded. The proxy owns a run of its own and
+ *   records MCP calls only — no prompt, no final answer, no built-in steps.
+ *   That is not a degraded bug; it is the honest ceiling of what an MCP proxy
+ *   can observe, and the run says so in `metadata.tier` so nothing downstream
+ *   mistakes it for a complete trace.
+ *
+ *   **Passthrough.** No control server, in a project that never opted in. A
+ *   user-scope server is wrapped once, by `bir install` in *one* project, but
+ *   Claude Code starts it in *every* project — and Tier 2 there meant uploading
+ *   that project's tool arguments and results to the service without anyone
+ *   having asked. So a hooks-wired user-scope entry records only where its
+ *   directory was set up, or a recorder is running for it; anywhere else it
+ *   relays and records nothing. Every other entry — another client's config
+ *   file, a project-scope entry, a hand-pasted `bir wrap` — keeps Tier 2 (see
+ *   `optedIn`).
  *
  * THE DISCOVERY WINDOW EXISTS BECAUSE OF A RACE: the host may spawn MCP servers
  * before `SessionStart` fires, and the ordering between the two is not
  * guaranteed. So steps are **buffered in memory** while the search runs, and
  * flushed into whichever owner wins. Nothing is lost to the race, and nothing
  * blocks: relaying never waits on this.
+ *
+ * AND IT IS NOT A ONE-WAY DOOR. A recorder that starts late, or is restarted
+ * mid-session (an upgrade), is found again: while not bound, the proxy looks
+ * for it every {@link REBIND_INTERVAL_MS} and binds when it answers. Losing it
+ * costs one downgrade and at most one standalone run per proxy, however many
+ * reports were queued when it went. A recorder that *died* under a bound proxy
+ * — its pid gone, its port refusing — is started again from here, in the
+ * background (proxy/revive.ts): until it is back, every hook of the session
+ * fails in front of the user.
  */
 import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
+import { readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import { ControlClient } from "../control/client.js";
-import { resolveControl } from "../control/discovery.js";
+import { readDiscovery } from "../control/discovery.js";
 import { qualifyToolName } from "../control/correlation.js";
-import { authenticate, resolveAuthUrl } from "../auth/client.js";
+import { projectRecord } from "../config/generate.js";
+import { installedPath, normalizePath } from "../control/paths.js";
+import { authenticate, loadCredentials, normalizeAuthUrl, resolveAuthUrl } from "../auth/client.js";
 import { NullRecorder } from "../record/recorder.js";
 import { RemoteRecorder } from "../record/remote-recorder.js";
 import { StepQueue } from "../record/queue.js";
 import { StepIndexAllocator } from "../control/ordering.js";
 import { serializeCapped } from "../record/truncate.js";
 import { redact } from "../record/redact.js";
+import { isRunnerOff } from "../util/off-switch.js";
+import { RecorderReviver } from "./revive.js";
 import { logLine, logDetail, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
@@ -44,6 +70,151 @@ import { packageVersion } from "../util/version.js";
  * dropped, and a host session is never waiting on this.
  */
 export const DISCOVERY_WINDOW_MS = 10_000;
+/** While not bound, how often to look for a control server that came (back) up. */
+export const REBIND_INTERVAL_MS = 15_000;
+/**
+ * Step reports waiting to be sent. Tier 1 sends go to loopback and take
+ * milliseconds; Tier 2 sends wait on the service (one step at a time, see
+ * `dispatch`). Either way a backlog this deep means the far end is not
+ * keeping up, and the oldest is dropped — and the run flagged lossy — rather
+ * than growing inside the user's MCP server process tree.
+ */
+export const STEP_BACKLOG = 250;
+/** Steps held while the tier is still being negotiated. */
+const DISCOVERY_BUFFER = 1000;
+/**
+ * The replay work loop's ceiling between polls of a control server that is
+ * reachable but not holding them — replay is off there, or it is an older one
+ * that answers at once. One loopback request every 30 s is nothing, and it is
+ * what lets a proxy notice that replay was turned back on (a restart applies
+ * that) without being told.
+ */
+const MAX_POLL_BACKOFF_MS = 30_000;
+/**
+ * The ceiling while the control server cannot be reached at all — most often
+ * because it is restarting. Lower than the idle ceiling on purpose: a
+ * restarted recorder routes nothing to this proxy until it polls, so every
+ * second of backoff past its return is a replay step that falls back to a
+ * recorded output. A refused loopback connect every 5 s costs nothing.
+ */
+const MAX_UNREACHABLE_BACKOFF_MS = 5_000;
+/**
+ * Spread over which proxies that all hit the end of the discovery window at
+ * once (one per wrapped server) start their Tier 2 recorder, so they do not
+ * all refresh the same rotating token in the same instant.
+ */
+const STANDALONE_JITTER_MS = 2_000;
+/**
+ * All of {@link ProxySession.close}: negotiation, the step queue and the run's
+ * final flush. Under bir-proxy's hard 3 s shutdown budget, with room for the
+ * process to write its last bytes and exit.
+ */
+const CLOSE_BUDGET_MS = 2_500;
+/** The final flush is always given at least this, even when the queue used the budget up. */
+const MIN_FINAL_FLUSH_MS = 250;
+const sleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+});
+/** Settles when `promise` does or after `ms`, whichever is first; never rejects. */
+function settledWithin(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        promise.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+/** Loopback: never behind a TLS front that redirects, and not readable on the network. */
+function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return host === "localhost" || host.endsWith(".localhost") || host === "::1" || /^127\./.test(host);
+}
+/**
+ * The service address a Tier 2 recorder should use for `configured`, the way
+ * the recorder (control/recorder-keeper.ts) and `bir login` bind sessions:
+ *
+ *   - A saved session issued by the https form of a configured `http://host`
+ *     is the same service, already upgraded — use its address. No request.
+ *   - Any other plain-http address off this machine is checked once for a
+ *     same-host https redirect ({@link normalizeAuthUrl}, bounded): following
+ *     one would strip the bearer token from every request. Not when signed
+ *     out: there is no token to send.
+ *   - Everything else is used as configured.
+ */
+export async function normalizedServiceUrl(configured, fetchImpl = fetch) {
+    const base = configured.replace(/\/+$/, "");
+    let url;
+    try {
+        url = new URL(base);
+    }
+    catch {
+        return base;
+    }
+    if (url.protocol !== "http:")
+        return base;
+    const cached = loadCredentials();
+    const issuer = cached?.authUrl?.replace(/\/+$/, "");
+    if (issuer) {
+        try {
+            const to = new URL(issuer);
+            if (to.protocol === "https:" && to.host === url.host)
+                return issuer;
+        }
+        catch {
+            /* not a URL: not this service */
+        }
+    }
+    if (isLoopbackHost(url.hostname))
+        return base;
+    // Signed out: there is no token to protect, and authenticate() is about to
+    // say "no session" whatever the address — not worth a request per proxy.
+    if (!cached && process.env.BIR_AUTH_DISABLE !== "1")
+        return base;
+    return normalizeAuthUrl(base, fetchImpl);
+}
+/**
+ * Read the install sidecar's facts for `cwd` and `serverName`.
+ *
+ * Read asynchronously, and only when a decision needs it: the sidecar carries
+ * byte-exact backups of the files install edited — `~/.claude.json` among
+ * them, which can run to megabytes — and a proxy must not spend its start-up
+ * parsing that in front of the host's `initialize`. Unreadable → no facts,
+ * which every caller treats as "not installed, not written by an install".
+ */
+export async function readInstallFacts(cwd, serverName) {
+    try {
+        const parsed = JSON.parse(await readFile(installedPath(), "utf8"));
+        const sidecar = { version: 1, ...parsed, servers: parsed.servers ?? {} };
+        const key = normalizePath(resolvePath(cwd));
+        let installedHere = projectRecord(sidecar, cwd) !== undefined;
+        const scopes = [];
+        for (const [recordKey, r] of Object.entries(sidecar.servers)) {
+            if (!r || typeof r !== "object")
+                continue;
+            if (!installedHere && typeof r.cwd === "string" && normalizePath(resolvePath(r.cwd)) === key) {
+                installedHere = true;
+            }
+            // Records are keyed `<cwd>::<serverName>` (generate.ts `sidecarKey`).
+            if (serverName !== undefined && recordKey.endsWith(`::${serverName}`)) {
+                scopes.push(typeof r.scope === "string" ? r.scope : "unknown");
+            }
+        }
+        return { installedHere, scopes };
+    }
+    catch {
+        return { installedHere: false, scopes: [] };
+    }
+}
+/** Whether `bir install` set this directory up for recording. */
+export async function projectInstalledHere(cwd) {
+    return (await readInstallFacts(cwd)).installedHere;
+}
 export class ProxySession {
     serverName;
     /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
@@ -51,11 +222,16 @@ export class ProxySession {
     opts;
     tierValue = "pending";
     control;
-    /** Tier 2 only. */
+    /** Where `control` lives, for the log and to reuse a client across re-binds. */
+    controlKey;
+    /** The last control server this proxy was bound to; the work loop polls it. */
+    pollClient;
+    /** Tier 2 only. One per proxy, however often the tier changes. */
     recorder;
     runId;
     ordering = new StepIndexAllocator();
     queue = new StepQueue({
+        capacity: STEP_BACKLOG,
         onDrop: (dropped) => {
             if (!this.lossyValue)
                 logLine("run.lossy", { why: "step queue overflowed", dropped });
@@ -67,13 +243,51 @@ export class ProxySession {
     buffer = [];
     lossyValue = false;
     negotiation;
+    downgrading;
     startedAt = Date.now();
     /** The replay work loop, when one was started. */
     workLoop;
+    /** What the control server last said about calculated replay. */
+    replayOn = false;
+    pollHoldMs = 25_000;
+    rebindTimer;
+    /** A discovery file for this cwd has been seen: a recorder was started here. */
+    sawDiscovery = false;
+    /**
+     * May a control server inject call ids here? Decided from the project at
+     * start-up (see {@link declaresCallId}), not from how negotiation is going.
+     */
+    expectsBinding;
+    /** `readInstallFacts(cwd, serverName)`, started once and shared by everything that asks. */
+    installFactsPromise;
     closing = false;
+    /**
+     * The work loop's current pause between polls. An instance field, not a
+     * local, so that {@link bind} can reset it: a proxy that finds its recorder
+     * again must poll it now, not after a backoff it grew while it was gone.
+     */
+    pollBackoff = 0;
+    /** Ends the work loop's current pause early (see {@link pause}). */
+    wakeLoop;
+    /** A re-registration in flight, so a burst of triggers makes one request. */
+    reregistering;
+    /**
+     * Brings back a recorder that died under this proxy. Made at the first
+     * bind: only a proxy that has had a recorder asks for one back.
+     */
+    reviver;
     constructor(opts) {
         this.opts = opts;
         this.serverName = opts.serverName;
+        this.expectsBinding = !opts.standalone && !opts.noCorrelation && this.likelyBound();
+    }
+    /** The install sidecar's facts for this directory and server. Read once, off the start-up path. */
+    installFacts() {
+        this.installFactsPromise ??= readInstallFacts(this.opts.cwd, this.serverName);
+        return this.installFactsPromise;
+    }
+    async isInstalled() {
+        return (await this.installFacts()).installedHere;
     }
     get tier() {
         return this.tierValue;
@@ -83,22 +297,94 @@ export class ProxySession {
     }
     /**
      * Whether the schema-relaxation half of correlation should be applied to
-     * `tools/list` (Phase 6). Only ever true in Tier 1 with correlation enabled:
-     * relaxation is visible to the model on every call, so it is never paid for
-     * unless it is actually buying a merge.
+     * `tools/list` (Phase 6). Only ever true in Tier 1 with correlation enabled.
      */
     get correlationActive() {
         return this.tierValue === "bound" && !this.opts.noCorrelation;
     }
+    /**
+     * Whether `tools/list` should declare the call-id key. True where a control
+     * server may inject one: bound, or still negotiating in a project that is set
+     * up for it — decided from the project, not from whether registration
+     * happened to finish before the host listed tools, so a warm and a cold
+     * start show the model the same schemas.
+     */
+    get declaresCallId() {
+        if (this.opts.noCorrelation || this.opts.standalone)
+            return false;
+        if (isRunnerOff(this.opts.cwd))
+            return false;
+        return this.tierValue === "bound" || (this.tierValue === "pending" && this.expectsBinding);
+    }
+    /** False when nothing this proxy sees will be recorded (passthrough, or the runner is off). */
+    get recording() {
+        return this.tierValue !== "passthrough" && !isRunnerOff(this.opts.cwd);
+    }
     /** Begin tier negotiation. Returns immediately; relaying never waits on it. */
     start() {
         if (this.negotiation)
             return;
+        // A hooks-wired entry with no recorder up yet: whether this directory is
+        // installed decides the schemas the model is shown, so learn it early —
+        // but after relaying has started, never in front of it.
+        if (!this.expectsBinding && !this.opts.standalone && !this.opts.noCorrelation && process.env.BIR_CONTROL_URL) {
+            void this.isInstalled().then((installed) => {
+                if (installed)
+                    this.expectsBinding = true;
+            });
+        }
         this.negotiation = this.negotiate().catch((err) => {
             logLine("proxy.negotiation_failed", { server: this.serverName, error: errText(err) });
-            this.tierValue = "standalone";
+            if (this.tierValue === "pending")
+                this.becomePassthrough("negotiation failed");
         });
     }
+    /** Cheap first guess, at construction, of whether this proxy will end up bound. */
+    likelyBound() {
+        if (process.env.BIR_CONTROL_URL && process.env.BIR_CONTROL_TOKEN)
+            return true;
+        return readDiscovery(this.opts.cwd) !== undefined;
+    }
+    /**
+     * May this proxy record on its own (Tier 2) when no control server answers?
+     *
+     * The one entry that must NOT is the one that leaks: a Claude Code
+     * **user-scope** server. `bir install` wraps it once, in one project, but
+     * Claude Code starts it in every project — and Tier 2 there meant uploading
+     * that project's tool arguments and results without anyone having asked.
+     * Everything else records as it always did:
+     *
+     *   - An explicit SDK channel (`BIR_CONTROL_TOKEN`) or `--standalone`: yes.
+     *   - An entry without `BIR_CONTROL_URL` (`install --no-hooks`, a `bir wrap`
+     *     made before any install): Tier 2 is what it asked for.
+     *   - This directory was installed, or a recorder has run for it: yes.
+     *   - Otherwise it depends on where the entry came from, which the install
+     *     sidecar knows by server name. Another client's file (`install
+     *     --config`, whose host starts servers from any directory — Claude
+     *     Desktop uses `/`), a project- or local-scope entry (which Claude Code
+     *     only starts in its own project), or no install record at all (a `bir
+     *     wrap` entry, which bakes `BIR_CONTROL_URL` too once any install has
+     *     run): yes. Only when every record for this name is a user-scope one is
+     *     this a global entry running somewhere nobody set up — and then no.
+     *
+     * Keying this on `BIR_CONTROL_URL` alone was wrong: `install --config` and
+     * `bir wrap` bake it as well, and those entries silently stopped recording
+     * whenever their host's directory differed from the install's.
+     */
+    async optedIn() {
+        if (this.opts.standalone || process.env.BIR_CONTROL_TOKEN)
+            return true;
+        if (!process.env.BIR_CONTROL_URL)
+            return true;
+        if (this.sawDiscovery)
+            return true;
+        const facts = await this.installFacts();
+        if (facts.installedHere)
+            return true;
+        if (facts.scopes.length === 0)
+            return true;
+        return facts.scopes.some((scope) => scope !== "user");
+    }
     async negotiate() {
         if (this.opts.standalone) {
             await this.becomeStandalone("--standalone was requested");
@@ -106,50 +392,182 @@ export class ProxySession {
         }
         const window = this.opts.discoveryWindowMs ?? DISCOVERY_WINDOW_MS;
         const deadline = Date.now() + window;
-        const found = await resolveControl(this.opts.cwd, window);
-        if (!found?.url) {
-            await this.becomeStandalone(`no control server within ${window}ms`);
+        // A control server that is still coming up — the SessionStart hook is
+        // starting it while the host spawns us — answers nothing for a moment.
+        // Keep trying inside the window rather than settle on the first refusal.
+        for (;;) {
+            if (this.closing)
+                return;
+            if (await this.tryBind())
+                return;
+            if (Date.now() >= deadline)
+                break;
+            await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
+        }
+        if (this.closing)
             return;
+        await this.settleUnbound(`no control server answered within ${window}ms`);
+        this.scheduleRebind();
+    }
+    /** Where this cwd's control server is, if anywhere. */
+    findControl() {
+        const envUrl = process.env.BIR_CONTROL_URL;
+        const envToken = process.env.BIR_CONTROL_TOKEN;
+        // Explicit wiring (the Agent SDK channel) wins.
+        if (envUrl && envToken)
+            return { url: envUrl.replace(/\/+$/, ""), token: envToken };
+        // Otherwise this directory's own recorder, wherever it listens. The URL an
+        // install baked into the entry is not consulted: for a user-scope server it
+        // names *another* project's recorder, whose token is not ours.
+        const found = readDiscovery(this.opts.cwd);
+        if (found) {
+            this.sawDiscovery = true;
+            return { url: found.url, token: found.token };
         }
-        const client = new ControlClient(found.url, found.token, undefined, {
-            proxyId: this.proxyId,
-            startedAt: this.startedAt,
-            pid: process.pid,
-        });
-        const info = {
+        return undefined;
+    }
+    /** Register with this cwd's control server, if one answers. True when bound. */
+    async tryBind() {
+        const target = this.findControl();
+        if (!target)
+            return false;
+        const key = `${target.url} ${target.token}`;
+        const client = this.control && this.controlKey === key
+            ? this.control
+            : new ControlClient(target.url, target.token, undefined, {
+                proxyId: this.proxyId,
+                startedAt: this.startedAt,
+                pid: process.pid,
+            });
+        const registered = await client.register({
             serverName: this.serverName,
             pid: process.pid,
             cwd: this.opts.cwd,
             version: packageVersion(),
-        };
-        // A control server that is still coming up — the SessionStart hook is
-        // starting it while the host spawns us — answers nothing for a moment.
-        // Keep trying inside the same window rather than settle for Tier 2 on the
-        // first refusal.
-        let registered = await client.register(info);
-        while (!registered && Date.now() < deadline) {
-            await new Promise((resolve) => {
-                const t = setTimeout(resolve, 250);
-                t.unref?.();
+        });
+        if (!registered || this.closing)
+            return false;
+        this.bind(client, key, target.url, registered);
+        return true;
+    }
+    bind(client, key, url, registered) {
+        const was = this.tierValue;
+        this.control = client;
+        this.controlKey = key;
+        this.pollClient = client;
+        this.tierValue = "bound";
+        if (!this.reviver && this.opts.revive !== false && !this.opts.standalone) {
+            this.reviver = new RecorderReviver({
+                ...(this.opts.revive || {}),
+                cwd: this.opts.cwd,
+                server: this.serverName,
             });
-            registered = await client.register(info);
         }
-        if (!registered) {
-            await this.becomeStandalone("control server did not answer /proxy/register");
-            return;
+        if (this.rebindTimer) {
+            clearTimeout(this.rebindTimer);
+            this.rebindTimer = undefined;
         }
-        this.control = client;
-        this.tierValue = "bound";
-        logLine("tier.bound", {
+        const fields = {
             server: this.serverName,
-            control: found.url,
+            control: url,
             sess: registered.sessionId,
             correlation: this.opts.noCorrelation ? "fingerprint" : "injected",
             replay: registered.replay ? "on" : undefined,
-        });
+        };
+        // The normal start is routine, and so is telling a restarted recorder we
+        // are still here; coming back after losing it is worth a line.
+        if (was === "pending")
+            logDetail("tier.bound", fields);
+        else if (was === "bound")
+            logDetail("tier.reregistered", fields);
+        else
+            logLine("tier.rebound", { ...fields, was });
         this.flushBuffer();
-        if (registered.replay)
-            this.startWorkLoop(client, registered.pollHoldMs ?? 25_000);
+        this.replayOn = registered.replay === true;
+        this.pollHoldMs = registered.pollHoldMs ?? 25_000;
+        // A bound proxy always has a work loop — paced to one poll every
+        // {@link MAX_POLL_BACKOFF_MS} while replay is off here — because replay is
+        // switched on by restarting the recorder, and a restarted recorder on the
+        // same address never makes a bound proxy register again. A loop that only
+        // started (or only kept going) while replay was on never noticed.
+        //
+        // Whatever pause the loop grew against the server it had before ends now:
+        // this one is answering, and routes nothing to us until we poll it.
+        this.pollBackoff = this.replayOn ? 0 : this.maxIdleBackoff();
+        this.wakeLoop?.();
+        this.startWorkLoop();
+    }
+    maxIdleBackoff() {
+        return this.opts.maxPollBackoffMs ?? MAX_POLL_BACKOFF_MS;
+    }
+    /**
+     * Tell the control server we exist again — it answered after a spell of not
+     * answering, so it is probably a restarted one that has never heard of this
+     * proxy (its `/health` would not list it, and it would not know this server
+     * has a proxy that can strip a call id). One request at a time; best-effort.
+     */
+    reregister() {
+        if (this.reregistering || this.closing || this.tierValue !== "bound")
+            return;
+        this.reregistering = this.tryBind()
+            .catch(() => false)
+            .finally(() => {
+            this.reregistering = undefined;
+        });
+    }
+    /** Sleep `ms`, or less if {@link wakeLoop} is called first. True when woken early. */
+    pause(ms) {
+        return new Promise((resolve) => {
+            const done = (early) => {
+                clearTimeout(timer);
+                if (this.wakeLoop === wake)
+                    this.wakeLoop = undefined;
+                resolve(early);
+            };
+            const wake = () => done(true);
+            const timer = setTimeout(() => done(false), ms);
+            timer.unref?.();
+            this.wakeLoop = wake;
+        });
+    }
+    /** No control server: record on our own if this project opted in, else stay out of the way. */
+    async settleUnbound(why) {
+        if (!(await this.optedIn())) {
+            this.becomePassthrough("this directory is not set up for recording, and no recorder is running for it");
+            return;
+        }
+        // Only the real recorder authenticates; an injected one (tests) has nothing to spread.
+        if (!this.opts.recorderFactory)
+            await sleep(Math.floor(Math.random() * STANDALONE_JITTER_MS));
+        if (this.closing)
+            return;
+        await this.becomeStandalone(why);
+    }
+    /** While not bound, look for a control server again now and then. */
+    scheduleRebind() {
+        if (this.rebindTimer || this.closing || this.opts.standalone)
+            return;
+        const interval = this.opts.rebindIntervalMs ?? REBIND_INTERVAL_MS;
+        this.rebindTimer = setTimeout(() => {
+            this.rebindTimer = undefined;
+            void (async () => {
+                if (this.closing || this.tierValue === "bound")
+                    return;
+                try {
+                    if (!isRunnerOff(this.opts.cwd) && (await this.tryBind()))
+                        return;
+                }
+                catch (err) {
+                    logDetail("proxy.rebind_failed", { server: this.serverName, error: errText(err) });
+                }
+                // Still no recorder, where there used to be one: if it died, ask for
+                // a new one (off the relay path; see proxy/revive.ts).
+                if (!this.closing)
+                    this.reviver?.nudge("no recorder answered since it was lost");
+                this.scheduleRebind();
+            })();
+        }, interval);
+        this.rebindTimer.unref?.();
     }
     /**
      * Take calculated-scenario steps from the control server and run them on the
@@ -159,37 +577,101 @@ export class ProxySession {
      * allocates an id in the reserved `bir:` space and the transport consumes its
      * own response in `accept()` before the relay's handlers ever see it — so this
      * costs **zero tokens**, the model is not involved, and `RecordingInterceptor`
-     * cannot double-record it. That interface comment says `request()` is "never
-     * used by the relay"; it was built for `bir doctor` and tests, and this is its
-     * second, load-bearing user.
+     * cannot double-record it.
+     *
+     * PACING. A long-poll that is held is free; one that is not must not become
+     * four requests a second for the rest of the session. So:
+     *
+     *   - held (the server parked it until work or its deadline): poll again now;
+     *   - unreachable (usually a recorder restarting): back off 250 ms → 5 s
+     *     ({@link MAX_UNREACHABLE_BACKOFF_MS}), and when it answers again,
+     *     register again so the new process knows about us;
+     *   - answered at once, or `{ replay: false }`: back off to one poll every
+     *     {@link MAX_POLL_BACKOFF_MS}. Never stop: replay is turned back on by a
+     *     restart that leaves this proxy bound, and a loop that had stopped for
+     *     good left every later scenario step falling back to recorded outputs
+     *     until the host itself was restarted.
+     *
+     * {@link bind} resets the pace and ends a pause early, so a proxy that finds
+     * its recorder again polls it at once rather than after a stale backoff.
      */
-    startWorkLoop(client, holdMs) {
+    startWorkLoop() {
         const upstream = this.opts.upstream;
         if (!upstream || this.workLoop)
             return;
         this.workLoop = (async () => {
-            logLine("replay.worker", { server: this.serverName, why: "polling for scenario steps" });
-            while (!this.closing) {
-                let work;
+            logDetail("replay.worker", { server: this.serverName, why: "polling for scenario steps" });
+            let wasUnreachable = false;
+            while (!this.closing && !upstream.dead) {
+                // Woken early by bind(): re-read the pace it set rather than poll blindly.
+                if (this.pollBackoff > 0 && (await this.pause(this.pollBackoff)))
+                    continue;
+                if (this.closing || upstream.dead)
+                    break;
+                const client = this.pollClient;
+                if (!client)
+                    break;
+                const holdMs = this.pollHoldMs;
+                const asked = Date.now();
+                let outcome;
                 try {
-                    work = await client.poll(this.serverName, holdMs);
+                    outcome = await client.pollWork(this.serverName, holdMs);
                 }
                 catch {
-                    work = undefined;
+                    outcome = { reachable: false };
                 }
                 if (this.closing)
                     break;
+                const work = outcome.work;
+                // Re-bound while this poll was out: bind() already set the pace for
+                // the new server, and this answer says nothing about it. Work handed
+                // out by the old one is still run, below — it is waiting for it.
+                const current = client === this.pollClient;
                 if (!work) {
-                    // Either an empty hold (normal) or an unreachable server. A short
-                    // pause keeps the second case from becoming a busy loop.
-                    await new Promise((resolve) => {
-                        const t = setTimeout(resolve, 250);
-                        t.unref?.();
-                    });
+                    if (!current)
+                        continue;
+                    if (!outcome.reachable) {
+                        wasUnreachable = true;
+                        this.reviver?.nudge("the recorder stopped answering");
+                        this.pollBackoff = Math.min(MAX_UNREACHABLE_BACKOFF_MS, this.pollBackoff ? this.pollBackoff * 2 : 250);
+                        continue;
+                    }
+                    if (wasUnreachable) {
+                        wasUnreachable = false;
+                        this.reregister();
+                    }
+                    if (outcome.replayOff) {
+                        if (this.replayOn) {
+                            logDetail("replay.worker_idle", { server: this.serverName, why: "replay is off; polling slowly" });
+                        }
+                        this.replayOn = false;
+                        this.pollBackoff = this.maxIdleBackoff();
+                        continue;
+                    }
+                    const held = Date.now() - asked >= Math.min(holdMs / 2, 5_000);
+                    if (held) {
+                        this.replayOn = true;
+                        this.pollBackoff = 0;
+                    }
+                    else {
+                        this.pollBackoff = Math.min(this.maxIdleBackoff(), this.pollBackoff ? this.pollBackoff * 2 : 250);
+                    }
                     continue;
                 }
+                if (current) {
+                    if (wasUnreachable) {
+                        wasUnreachable = false;
+                        this.reregister();
+                    }
+                    this.replayOn = true;
+                    this.pollBackoff = 0;
+                }
+                // A little under the control server's own budget for the step, so that
+                // on a timeout the cancellation reaches the upstream *before* the server
+                // gives up on it and, possibly, substitutes a recorded output.
+                const budget = Math.max(1, work.timeoutMs - Math.min(1_000, Math.floor(work.timeoutMs / 10)));
                 try {
-                    const result = await upstream.request("tools/call", { name: work.toolName, arguments: work.arguments }, AbortSignal.timeout(work.timeoutMs));
+                    const result = await upstream.request("tools/call", { name: work.toolName, arguments: work.arguments }, AbortSignal.timeout(budget));
                     await client.result(work.workId, result);
                 }
                 catch (err) {
@@ -200,7 +682,11 @@ export class ProxySession {
                     await client.result(work.workId, undefined, errText(err));
                 }
             }
-        })().catch((err) => logLine("replay.worker_failed", { server: this.serverName, error: errText(err) }));
+        })()
+            .catch((err) => logLine("replay.worker_failed", { server: this.serverName, error: errText(err) }))
+            .finally(() => {
+            this.workLoop = undefined;
+        });
     }
     /**
      * Take ownership of a run ourselves.
@@ -211,45 +697,88 @@ export class ProxySession {
      * buffered nor recordable, and every `tools/call` in that window is lost.
      * `dispatch` re-buffers defensively too — belt and braces on a race whose
      * failure mode is silent data loss.
+     *
+     * One run per proxy: a proxy that went standalone, re-bound, and lost its
+     * control server again carries on in the run it already owns.
      */
     async becomeStandalone(why) {
-        logLine("tier.standalone", {
-            server: this.serverName,
-            why,
-            records: "MCP calls only — no prompt, no final answer, no built-in steps",
-        });
-        this.recorder = await this.buildRecorder();
-        this.runId = this.recorder.startRun("", {
-            recorder: "baseinstrunner",
-            tier: "standalone",
-            host: { app: process.env.BIR_HOST_APP ?? "unknown", version: process.env.BIR_HOST_VERSION },
-            wrappedServers: [this.serverName],
-            lossy: this.lossyValue,
-            machine: hostname(),
-            cwd: this.opts.cwd,
-        });
+        // The first Tier 2 start, its run and (in close) its finish are routine —
+        // every proxy for a host without hooks does this on every start — so they
+        // are BIR_VERBOSE detail: Claude Code files each stderr line of an MCP
+        // server as a "Server stderr" error. Losing a recorder mid-session
+        // (tier.downgrade), an overflow (run.lossy) and failures stay on stderr.
+        if (!this.recorder || !this.runId) {
+            logDetail("tier.standalone", {
+                server: this.serverName,
+                why,
+                records: "MCP calls only — no prompt, no final answer, no built-in steps",
+            });
+            this.recorder = await this.buildRecorder();
+            this.runId = this.recorder.startRun("", {
+                recorder: "baseinstrunner",
+                tier: "standalone",
+                host: { app: process.env.BIR_HOST_APP ?? "unknown", version: process.env.BIR_HOST_VERSION },
+                wrappedServers: [this.serverName],
+                lossy: this.lossyValue,
+                machine: hostname(),
+                cwd: this.opts.cwd,
+            });
+            logDetail("run.start", { run: this.runId, tier: "standalone", server: this.serverName });
+        }
+        else {
+            logDetail("tier.standalone", { server: this.serverName, why, run: this.runId, resumed: true });
+        }
         this.tierValue = "standalone";
-        logLine("run.start", { run: this.runId, tier: "standalone", server: this.serverName });
         this.flushBuffer();
     }
+    /**
+     * Record nothing; relay only. Held steps are released, not kept.
+     *
+     * Detail, not a stderr line: this is the designed outcome for a user-scope
+     * server in a project nobody set up, and a line there would appear as a
+     * "Server stderr" error in a project that never asked for the runner at all.
+     * `bir doctor`, run in that directory, is where "not set up here" is told.
+     */
+    becomePassthrough(why) {
+        this.tierValue = "passthrough";
+        this.buffer.length = 0;
+        logDetail("tier.passthrough", { server: this.serverName, why, records: "nothing" });
+    }
     async buildRecorder() {
         if (this.opts.recorderFactory) {
             return (await this.opts.recorderFactory()) ?? new NullRecorder();
         }
         // BIR_AUTH_URL, or the address 'bir setup' stored — the same lookup the
         // control server and the CLI make, so no two processes disagree about it.
-        const baseUrl = resolveAuthUrl();
-        if (!baseUrl) {
-            logLine("recorder.disabled", { why: "no service address — run 'bir setup', or set BIR_AUTH_URL" });
+        // "Not set up" and "signed out" are states `bir doctor` reports, not
+        // failures of this session: detail here, so a signed-out machine does not
+        // add a stderr "error" to every wrapped server on every start.
+        const configured = resolveAuthUrl();
+        if (!configured) {
+            logDetail("recorder.disabled", { why: "no service address — run 'bir setup', or set BIR_AUTH_URL" });
             return new NullRecorder();
         }
+        // The address as the rest of the runner binds sessions to it: a plain-http
+        // service that redirects to https is used at its https address (a
+        // cross-origin redirect strips the bearer token), and a session saved
+        // under that address is this one's. Asking with the configured http form
+        // instead read as "issued by another service" (auth.url_mismatch), and
+        // the proxy recorded nothing for its whole life.
+        const baseUrl = await normalizedServiceUrl(configured);
+        if (this.closing)
+            return new NullRecorder();
         // A proxy runs inside the host's process tree with its stdio bound to the
         // JSON-RPC stream: there is nowhere to prompt, and blocking on one would
         // hang the host's server startup. `authenticate` never interacts — signing
         // in lives in `bir login` alone — so that is guaranteed here, not requested.
-        const session = await authenticate({ authUrl: baseUrl });
+        //
+        // `keepStaleOnNoAnswer`: a service that is down or slow at the moment this
+        // proxy goes standalone must not disable recording for the proxy's whole
+        // life when the refresh token is fine. The recorder renews the session in
+        // the background once the service answers (a 401 there refreshes).
+        const session = await authenticate({ authUrl: baseUrl, keepStaleOnNoAnswer: true });
         if (!session) {
-            logLine("recorder.disabled", { why: "no BaseIn session — run `bir login`" });
+            logDetail("recorder.disabled", { why: "no BaseIn session — run `bir login`" });
             return new NullRecorder();
         }
         return new RemoteRecorder({ baseUrl, session });
@@ -259,6 +788,8 @@ export class ProxySession {
      * *after* the result is already on its way to the host, and it never awaits.
      */
     reportStep(step) {
+        if (!this.recording)
+            return;
         if (this.tierValue === "pending") {
             this.bufferStep(step);
             return;
@@ -267,7 +798,7 @@ export class ProxySession {
     }
     /** Hold a step until an owner exists. Bounded, and honest when it overflows. */
     bufferStep(step) {
-        if (this.buffer.length >= 1000) {
+        if (this.buffer.length >= DISCOVERY_BUFFER) {
             this.buffer.shift();
             if (!this.lossyValue) {
                 logLine("run.lossy", { why: "discovery buffer overflowed", server: this.serverName });
@@ -285,23 +816,37 @@ export class ProxySession {
         }
     }
     dispatch(step) {
+        if (this.tierValue === "passthrough")
+            return;
         if (this.tierValue === "bound" && this.control) {
             const control = this.control;
             this.queue.push(async () => {
-                const ok = await control.report(step);
-                if (!ok) {
-                    // §10: the control server died mid-session. Everything after this is
-                    // Tier 2, and the run is flagged lossy — the steps already sent live in
-                    // the bound run, the rest in ours.
-                    logLine("tier.downgrade", {
-                        server: this.serverName,
-                        why: "control server stopped answering",
-                    });
-                    this.control = undefined;
-                    this.lossyValue = true;
-                    await this.becomeStandalone("control server stopped answering");
+                // Queued under a control server this proxy has since left (or found
+                // again under another address): route it by the tier as it is *now*,
+                // rather than fail against the old one and downgrade a second time.
+                if (this.control !== control) {
                     this.dispatch(step);
+                    return;
+                }
+                let ok = await control.report(step);
+                if (!ok && !this.closing) {
+                    // One refused report is not a dead recorder — a restart for an
+                    // upgrade refuses connections for a second or two.
+                    await sleep(1_000);
+                    if (this.control !== control) {
+                        this.dispatch(step);
+                        return;
+                    }
+                    ok = await control.report(step);
+                    // Refused, then taken: most likely a restarted recorder, which has
+                    // never heard of this proxy. Introduce ourselves again.
+                    if (ok)
+                        this.reregister();
                 }
+                if (ok)
+                    return;
+                await this.downgrade(control);
+                this.dispatch(step);
             });
             return;
         }
@@ -320,24 +865,88 @@ export class ProxySession {
         const toolError = step.isError
             ? (step.errorMessage ?? serializeCapped(redact(step.result)))
             : undefined;
-        this.queue.push(() => {
+        this.queue.push(async () => {
             recorder.recordToolSelected(runId, pair.selected, { toolName, toolInput });
             recorder.recordToolResponse(runId, pair.response, { toolName, toolOutput, toolError });
+            // Wait for the service to take them before the next step goes. The
+            // recorder's own per-run chain is unbounded; waiting here is what makes
+            // the step queue's bound apply to what is actually waiting on the
+            // network, so a slow or dead service costs a bounded backlog (oldest
+            // dropped, run flagged lossy) instead of a growing one.
+            //
+            // Not while closing: then every step is handed over at once, and the
+            // one bounded flush in close() waits for them all.
+            if (!this.closing)
+                await recorder.flush(runId);
+        });
+    }
+    /**
+     * The control server stopped answering. Exactly once per loss, however many
+     * reports were queued against it: later failures wait for this one and are
+     * re-routed, instead of each building a recorder and opening a run.
+     */
+    downgrade(control) {
+        if (this.control !== control)
+            return this.downgrading ?? Promise.resolve();
+        this.downgrading ??= (async () => {
+            // §10: the control server died mid-session. What follows goes to a run of
+            // our own (where this project records at all) until it is found again.
+            logLine("tier.downgrade", {
+                server: this.serverName,
+                why: "control server stopped answering",
+            });
+            this.control = undefined;
+            this.controlKey = undefined;
+            this.lossyValue = true;
+            this.reviver?.nudge("the recorder stopped taking step reports");
+            await this.settleUnbound("control server stopped answering");
+            this.scheduleRebind();
+        })().finally(() => {
+            this.downgrading = undefined;
         });
+        return this.downgrading;
     }
-    /** Close the Tier 2 run, if we own one, and drain the queue. */
+    /**
+     * Close the Tier 2 run, if we own one, and drain the queue — within
+     * {@link CLOSE_BUDGET_MS} all told. bir-proxy gives shutdown a hard 3 s; a
+     * close that spent it waiting on a slow service never reached `finishRun`.
+     * Whatever has not been sent by then carries on in the background for as
+     * long as the process lives.
+     */
     async close() {
+        const deadline = Date.now() + CLOSE_BUDGET_MS;
+        const left = () => Math.max(0, deadline - Date.now());
         // Stops the work loop at its next turn. It is not awaited: it may be parked
         // in a 25 s long-poll, and shutdown does not wait on a poll that will be
         // answered by the control server closing anyway.
         this.closing = true;
-        await this.negotiation?.catch(() => undefined);
+        this.reviver?.stop();
+        this.wakeLoop?.();
+        if (this.rebindTimer) {
+            clearTimeout(this.rebindTimer);
+            this.rebindTimer = undefined;
+        }
+        // The interceptor reports on a later tick (setImmediate), after the relay
+        // has written the answer — and at shutdown the relay has just answered or
+        // abandoned whatever was in flight, with those reports still scheduled.
+        // Let them land first, or the run is finished (or the process gone)
+        // before its last steps are queued.
+        await new Promise((resolve) => setImmediate(resolve));
+        // Negotiation stops at its next turn once `closing` is set, but a turn can
+        // be a sign-in refresh against a slow service: bounded, not awaited whole.
+        if (this.negotiation)
+            await settledWithin(this.negotiation, left());
         this.flushBuffer();
-        await this.queue.flush();
+        // Steps waiting behind a slow service: each is handed to the recorder at
+        // once now (dispatch skips its per-step wait while closing), so this is
+        // one in-progress wait at most.
+        await settledWithin(this.queue.flush(), left());
         if (this.recorder && this.runId) {
             this.recorder.finishRun(this.runId, undefined, { durationMs: Date.now() - this.startedAt });
-            await this.recorder.flush(this.runId).catch(() => undefined);
-            logLine("run.finish", {
+            await this.recorder
+                .flush(this.runId, { timeoutMs: Math.max(MIN_FINAL_FLUSH_MS, left()) })
+                .catch(() => undefined);
+            logDetail("run.finish", {
                 run: this.runId,
                 tier: "standalone",
                 steps: this.ordering.next,