@basein/runner 0.2.12 → 0.3.1

package/dist/proxy/revive.js

@@ -0,0 +1,251 @@
+/**
+ * revive — a bound proxy brings back the recorder that died under it.
+ *
+ * Every Claude Code hook but SessionStart is an HTTP post to the project's
+ * recorder. When that process dies mid-session (killed by an antivirus or the
+ * OOM killer, or a restart from another window that did not come back), every
+ * later prompt and tool call shows the user a hook error, and only a new
+ * session, `/clear` or a compaction — the next SessionStart — started it again.
+ * A bound proxy is the one long-lived process of the session that notices, so
+ * it asks for a new one: it launches `bir-hooks revive --cwd <project>`,
+ * detached, which starts the recorder under the same start lock the
+ * SessionStart hook uses, so any number of proxies (and bir-scenario) asking
+ * at once start one recorder.
+ *
+ * ONLY WHEN IT IS DEAD, NOT SLOW. All of these, checked in this order, cheapest
+ * first:
+ *
+ *   - the project's discovery file is still there and names a pid that is no
+ *     longer running. A recorder that stopped cleanly — `bir down`, a restart —
+ *     removed its file, so a recorder the user stopped on purpose is never
+ *     brought back from here; a pid that is alive (busy, or recycled by an
+ *     unrelated process) is never second-guessed either;
+ *   - the recorder's address refuses a TCP connection. Anything that accepts
+ *     one — a recorder coming up, whatever else took the port — or does not
+ *     answer within a couple of seconds is left alone;
+ *   - `bir install` set this directory up (the sidecar has its project record).
+ *
+ * NEVER IN ANYONE'S WAY. {@link RecorderReviver.nudge} is synchronous and
+ * constant-time: it only arms a timer. The checks run on that timer, after a
+ * random 0-5 s (so the proxies of one session do not all launch in the same
+ * instant), and the launch is a detached, unref'd process with no stdio: the
+ * proxy neither waits for it nor learns how it went. At most one launch per
+ * {@link REVIVE_MIN_INTERVAL_MS} per process, backing off to
+ * {@link REVIVE_MAX_INTERVAL_MS} while launches keep not taking (a recorder
+ * that dies on start). Each launch is one audit line.
+ *
+ * Not for an explicit control channel (`BIR_CONTROL_URL` + `BIR_CONTROL_TOKEN`,
+ * the Agent SDK's): that control server is its owner's to run.
+ */
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { connect } from "node:net";
+import { pidAlive } from "../control/discovery.js";
+import { discoveryPath, installedPath } from "../control/paths.js";
+import { projectRecord } from "../config/generate.js";
+import { isLoopbackHost } from "../upstream/http-transport.js";
+import { errText, logDetail, logLine } from "../util/log.js";
+/** At most one launch per process in this long. */
+export const REVIVE_MIN_INTERVAL_MS = 30_000;
+/** ...doubling per launch that did not take, up to this. */
+export const REVIVE_MAX_INTERVAL_MS = 10 * 60_000;
+/** A launch is delayed by a random 0 to this, so sibling proxies spread out. */
+export const REVIVE_MAX_JITTER_MS = 5_000;
+/** The checks themselves (two small file reads, a loopback connect) run at most this often. */
+const CHECK_INTERVAL_MS = 10_000;
+/**
+ * A connect that neither succeeds nor is refused in this long is "slow", not
+ * "dead". Generous: nobody waits on it, and a refusal is not always instant.
+ */
+const REFUSED_PROBE_MS = 2_500;
+/**
+ * The project's discovery file as it is on disk, when the pid it names is no
+ * longer running. `readDiscovery` hides exactly these files — correctly, for
+ * binding — and they are the evidence here: a recorder that stopped cleanly
+ * removed its own.
+ */
+export async function deadRecorder(cwd) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(discoveryPath(cwd), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed.pid !== "number" || typeof parsed.url !== "string")
+        return undefined;
+    if (pidAlive(parsed.pid))
+        return undefined;
+    return { pid: parsed.pid, url: parsed.url };
+}
+/** Whether the install sidecar has a project record for `cwd`. Unreadable → no. */
+export async function projectRecordedHere(cwd) {
+    try {
+        const parsed = JSON.parse(await readFile(installedPath(), "utf8"));
+        const sidecar = { version: 1, servers: {}, ...parsed };
+        return projectRecord(sidecar, cwd) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True only when a loopback `url`'s port actively refuses a TCP connection.
+ * Accepted, timed out, any other error, or not a loopback address: false.
+ */
+export function refusesConnections(url, timeoutMs = REFUSED_PROBE_MS) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+    if (!isLoopbackHost(target.hostname))
+        return Promise.resolve(false);
+    const port = Number(target.port || (target.protocol === "https:" ? 443 : 80));
+    const host = target.hostname.replace(/^\[|\]$/g, "");
+    return new Promise((resolve) => {
+        let settled = false;
+        const socket = connect({ host, port });
+        const done = (refused) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(refused);
+        };
+        const timer = setTimeout(() => done(false), timeoutMs);
+        timer.unref?.();
+        socket.once("connect", () => done(false));
+        socket.once("error", (err) => done(err.code === "ECONNREFUSED"));
+    });
+}
+/**
+ * Launch `bir-hooks revive --cwd <cwd>` detached, and forget it. Never throws.
+ *
+ * On Windows the revive always starts the recorder through PowerShell's
+ * `Start-Process`, whatever `BIR_WINDOWS_LAUNCH` says: a process started from
+ * here inherits this proxy's handles — its stdout is the host's JSON-RPC pipe
+ * — and a recorder launched directly from it would hold that pipe for days
+ * (see HOW IT IS LAUNCHED in control/daemon.ts). The revive itself lives for
+ * seconds.
+ */
+export async function launchRevive(cwd, opts = {}) {
+    try {
+        // Loaded here, not at the top: the daemon module is needed only on the
+        // rare occasion a recorder died, never on a proxy's start-up path.
+        const { hooksScriptPath, WINDOWS_LAUNCH_ENV } = await import("../control/daemon.js");
+        const env = { ...(opts.env ?? process.env) };
+        if (process.platform === "win32") {
+            // Windows variable names ignore case; a copy of the environment does not.
+            for (const key of Object.keys(env))
+                if (key.toUpperCase() === WINDOWS_LAUNCH_ENV)
+                    delete env[key];
+        }
+        const script = opts.script ?? hooksScriptPath();
+        const child = spawn(process.execPath, [script, "revive", "--cwd", cwd], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env,
+        });
+        child.once("error", (err) => logDetail("proxy.recorder_revive_failed", { error: errText(err) }));
+        child.unref();
+        return true;
+    }
+    catch (err) {
+        logDetail("proxy.recorder_revive_failed", { error: errText(err) });
+        return false;
+    }
+}
+/** One per bound proxy: decides whether, and when, to launch a revive. */
+export class RecorderReviver {
+    opts;
+    minIntervalMs;
+    maxIntervalMs;
+    maxJitterMs;
+    checkIntervalMs;
+    interval;
+    timer;
+    pending = false;
+    stopped = false;
+    nextLaunchAt = 0;
+    nextCheckAt = 0;
+    lastLaunchAt = 0;
+    /** How many revives this process launched. */
+    launches = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.minIntervalMs = opts.minIntervalMs ?? REVIVE_MIN_INTERVAL_MS;
+        this.maxIntervalMs = Math.max(this.minIntervalMs, opts.maxIntervalMs ?? REVIVE_MAX_INTERVAL_MS);
+        this.maxJitterMs = opts.maxJitterMs ?? REVIVE_MAX_JITTER_MS;
+        this.checkIntervalMs = opts.checkIntervalMs ?? CHECK_INTERVAL_MS;
+        this.interval = this.minIntervalMs;
+    }
+    /**
+     * The recorder did not answer. Arms the check, unless one is pending or
+     * the rate limit says not yet. Synchronous, constant-time, never throws.
+     */
+    nudge(why) {
+        if (this.stopped || this.pending)
+            return;
+        const now = Date.now();
+        if (now < this.nextLaunchAt || now < this.nextCheckAt)
+            return;
+        if (process.env.BIR_CONTROL_URL && process.env.BIR_CONTROL_TOKEN)
+            return;
+        this.pending = true;
+        const jitter = this.maxJitterMs > 0 ? Math.floor(Math.random() * (this.maxJitterMs + 1)) : 0;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.attempt(why)
+                .catch((err) => logDetail("proxy.recorder_revive_failed", { server: this.opts.server, error: errText(err) }))
+                .finally(() => {
+                this.pending = false;
+            });
+        }, jitter);
+        this.timer.unref?.();
+    }
+    /** No more launches: the proxy is closing. */
+    stop() {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    async attempt(why) {
+        this.nextCheckAt = Date.now() + this.checkIntervalMs;
+        if (this.stopped)
+            return;
+        const cwd = this.opts.cwd;
+        const dead = await deadRecorder(cwd);
+        if (!dead || this.stopped)
+            return;
+        if (!(await refusesConnections(dead.url)) || this.stopped)
+            return;
+        // Last: the sidecar can be large (it keeps backups of the files install edited).
+        if (!(await projectRecordedHere(cwd)) || this.stopped)
+            return;
+        const now = Date.now();
+        // A while without a launch: whatever went wrong before is history.
+        if (this.lastLaunchAt && now - this.lastLaunchAt > this.maxIntervalMs)
+            this.interval = this.minIntervalMs;
+        const launched = this.opts.launch
+            ? await this.opts.launch(cwd)
+            : await launchRevive(cwd, { env: this.opts.env });
+        if (!launched)
+            return;
+        this.launches += 1;
+        this.lastLaunchAt = now;
+        this.nextLaunchAt = now + this.interval;
+        logLine("proxy.recorder_revive", {
+            server: this.opts.server,
+            pid: dead.pid,
+            why,
+            effect: "the project's recorder had died; a new one is being started in the background",
+        });
+        this.interval = Math.min(this.maxIntervalMs, this.interval * 2);
+    }
+}
+//# sourceMappingURL=revive.js.map

package/dist/proxy/session.d.ts

@@ -9,21 +9,42 @@
  *   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 type { UpstreamClient } from "../upstream/client.js";
 import type { ProxyStepReport } from "../control/correlation.js";
 import { type Recorder } from "../record/recorder.js";
+import { type ReviverOptions } from "./revive.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
 /**
  * Ten seconds, not five: the recorder is now started by the SessionStart hook,
@@ -33,7 +54,17 @@ import { type Recorder } from "../record/recorder.js";
  * dropped, and a host session is never waiting on this.
  */
 export declare const DISCOVERY_WINDOW_MS = 10000;
-export type Tier = "bound" | "standalone" | "pending";
+/** While not bound, how often to look for a control server that came (back) up. */
+export declare const REBIND_INTERVAL_MS = 15000;
+/**
+ * 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 declare const STEP_BACKLOG = 250;
+export type Tier = "bound" | "standalone" | "pending" | "passthrough";
 export interface ProxySessionOptions {
     serverName: string;
     cwd: string;
@@ -42,6 +73,10 @@ export interface ProxySessionOptions {
     /** Suppress schema relaxation; the control server joins on fingerprints instead. */
     noCorrelation?: boolean;
     discoveryWindowMs?: number;
+    /** While not bound, how often to look for a control server again. Tests shorten it. */
+    rebindIntervalMs?: number;
+    /** The work loop's idle ceiling ({@link MAX_POLL_BACKOFF_MS}). Tests shorten it. */
+    maxPollBackoffMs?: number;
     /** Injected by tests. */
     recorderFactory?: () => Promise<Recorder | undefined>;
     /**
@@ -51,7 +86,50 @@ export interface ProxySessionOptions {
      * would have come here falls back to a recorded output.
      */
     upstream?: UpstreamClient;
+    /**
+     * Bringing back a recorder that died under this proxy (proxy/revive.ts).
+     * `false` turns it off; an object overrides its launch and pacing (tests).
+     */
+    revive?: false | Partial<Omit<ReviverOptions, "cwd" | "server">>;
 }
+/**
+ * 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 declare function normalizedServiceUrl(configured: string, fetchImpl?: typeof fetch): Promise<string>;
+/** What the install sidecar says about recording here, for one wrapped server. */
+export interface InstallFacts {
+    /** `bir install` set this directory up (a project record, or a server record made here). */
+    installedHere: boolean;
+    /**
+     * The scope of every install record for this server name, wherever it was
+     * installed: `user` for a `~/.claude.json` user-scope entry, `project` /
+     * `local` for Claude Code's per-project ones, `explicit` for another
+     * client's file (`install --config`). Empty when no install wrote an entry
+     * under this name — a `bir wrap` entry pasted into a client by hand.
+     */
+    scopes: string[];
+}
+/**
+ * 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 declare function readInstallFacts(cwd: string, serverName?: string): Promise<InstallFacts>;
+/** Whether `bir install` set this directory up for recording. */
+export declare function projectInstalledHere(cwd: string): Promise<boolean>;
 export declare class ProxySession {
     readonly serverName: string;
     /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
@@ -59,7 +137,11 @@ export declare class ProxySession {
     private readonly opts;
     private tierValue;
     private control?;
-    /** Tier 2 only. */
+    /** Where `control` lives, for the log and to reuse a client across re-binds. */
+    private controlKey?;
+    /** The last control server this proxy was bound to; the work loop polls it. */
+    private pollClient?;
+    /** Tier 2 only. One per proxy, however often the tier changes. */
     private recorder?;
     private runId?;
     private ordering;
@@ -68,23 +150,111 @@ export declare class ProxySession {
     private buffer;
     private lossyValue;
     private negotiation?;
+    private downgrading?;
     private startedAt;
     /** The replay work loop, when one was started. */
     private workLoop?;
+    /** What the control server last said about calculated replay. */
+    private replayOn;
+    private pollHoldMs;
+    private rebindTimer?;
+    /** A discovery file for this cwd has been seen: a recorder was started here. */
+    private sawDiscovery;
+    /**
+     * May a control server inject call ids here? Decided from the project at
+     * start-up (see {@link declaresCallId}), not from how negotiation is going.
+     */
+    private expectsBinding;
+    /** `readInstallFacts(cwd, serverName)`, started once and shared by everything that asks. */
+    private installFactsPromise?;
     private closing;
+    /**
+     * 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.
+     */
+    private pollBackoff;
+    /** Ends the work loop's current pause early (see {@link pause}). */
+    private wakeLoop?;
+    /** A re-registration in flight, so a burst of triggers makes one request. */
+    private 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.
+     */
+    private reviver?;
     constructor(opts: ProxySessionOptions);
+    /** The install sidecar's facts for this directory and server. Read once, off the start-up path. */
+    private installFacts;
+    private isInstalled;
     get tier(): Tier;
     get lossy(): boolean;
     /**
      * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /** False when nothing this proxy sees will be recorded (passthrough, or the runner is off). */
+    get recording(): boolean;
     /** Begin tier negotiation. Returns immediately; relaying never waits on it. */
     start(): void;
+    /** Cheap first guess, at construction, of whether this proxy will end up bound. */
+    private likelyBound;
+    /**
+     * 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.
+     */
+    private optedIn;
     private negotiate;
+    /** Where this cwd's control server is, if anywhere. */
+    private findControl;
+    /** Register with this cwd's control server, if one answers. True when bound. */
+    private tryBind;
+    private bind;
+    private maxIdleBackoff;
+    /**
+     * 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.
+     */
+    private reregister;
+    /** Sleep `ms`, or less if {@link wakeLoop} is called first. True when woken early. */
+    private pause;
+    /** No control server: record on our own if this project opted in, else stay out of the way. */
+    private settleUnbound;
+    /** While not bound, look for a control server again now and then. */
+    private scheduleRebind;
     /**
      * Take calculated-scenario steps from the control server and run them on the
      * upstream this proxy already owns (docs/calculatedReplay.md §16.2).
@@ -93,9 +263,23 @@ export declare 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.
      */
     private startWorkLoop;
     /**
@@ -107,8 +291,20 @@ export declare 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.
      */
     private becomeStandalone;
+    /**
+     * 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.
+     */
+    private becomePassthrough;
     private buildRecorder;
     /**
      * Record one completed `tools/call`. Fire-and-forget by contract: it is called
@@ -119,7 +315,19 @@ export declare class ProxySession {
     private bufferStep;
     private flushBuffer;
     private dispatch;
-    /** Close the Tier 2 run, if we own one, and drain the queue. */
+    /**
+     * 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.
+     */
+    private downgrade;
+    /**
+     * 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.
+     */
     close(): Promise<void>;
 }
 //# sourceMappingURL=session.d.ts.map