@basein/runner 0.2.12 → 0.3.0

package/dist/config/generate.d.ts

@@ -7,21 +7,34 @@
  * model-visible edit (a non-goal) as well as a broken scenario corpus.
  *
  * Reversibility is not an afterthought (Phase 7.4): the original entry is stashed
- * verbatim in `~/.baseinstrunner/installed.json` before anything is rewritten, so
- * `bir uninstall` restores exactly what was there — including fields
+ * in `~/.baseinstrunner/installed.json` before anything is rewritten — verbatim
+ * but for its env and header VALUES, which uninstall reads back from the wrapped
+ * entry — so `bir uninstall` restores exactly what was there, including fields
  * BaseInstRunner never understood.
  */
-import { type McpServerConfig, type Scope } from "./resolve.js";
+import { type McpServerConfig, type RemoteServerConfig, type Scope } from "./resolve.js";
 /** npm package name, as it appears in a generated `npx -p` invocation. */
 export declare const PACKAGE_NAME = "@basein/runner";
 /**
  * How the generated entry reaches a `bir` binary.
  *
- *   npx     `npx -y -p @basein/runner@<version> bir-proxy` — resolves through the
- *           registry, so it survives a missing global install. Always pinned:
- *           an unpinned spec lets two runners provisioned a week apart run
- *           different proxy versions against the same service, with nothing in
- *           the recording to say which.
+ *   npx     `npx --prefer-offline -y -p @basein/runner@<version> bir-proxy` —
+ *           resolves through the registry, so it survives a missing global
+ *           install. Always pinned: an unpinned spec lets two runners
+ *           provisioned a week apart run different proxy versions against the
+ *           same service, with nothing in the recording to say which. Pinned is
+ *           also what makes `--prefer-offline` safe: an exact version in the
+ *           cache cannot be stale, and without it a cached package still waits
+ *           on the registry — measured at 70 s per server start offline, past
+ *           the host's MCP connect timeout. An MCP entry is plain `npx` on
+ *           every platform: Claude Code spawns MCP servers through cross-spawn,
+ *           which finds `npx.cmd` on Windows and escapes every argument for
+ *           cmd.exe itself. `cmd /c npx …` would hand the user's own arguments
+ *           (a URL with `&`, a `^1.2` range, a `%VAR%`) to cmd.exe unescaped.
+ *           Only the SessionStart hook, whose arguments are all ours, keeps
+ *           `cmd /c` there ({@link npxHookInvocation}).
+ *           Only on request (`--npx`), or when `bir` itself runs from the npx
+ *           cache: every spawn pays ~1 s of npx start-up.
  *   local   an absolute path into this checkout — developing BaseInstRunner.
  *   global  an absolute path into the globally installed package. No registry
  *           round trip, no PATH lookup, works offline. What a fleet wants.
@@ -66,21 +79,127 @@ export interface WrapOptions {
      * trust what the install did (see {@link nodeFlagsToCarry}).
      */
     nodeFlags?: string[];
+    /**
+     * The interpreter for `local` and `global` entries. Default
+     * `process.execPath`; `bir install` passes the stable path it chose
+     * (node-path.ts), the same one the SessionStart hook names.
+     */
+    node?: string;
+    /**
+     * Default `process.platform`. Kept for callers that pass one; an npx MCP
+     * entry is the same plain `npx` shape on every platform now (see
+     * {@link npxInvocation}).
+     */
+    platform?: NodeJS.Platform;
 }
+/** True when an HTTP(S) proxy is configured in `env` (either spelling). */
+export declare function proxyConfigured(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * True when NO_PROXY (either spelling) sends 127.0.0.1 straight to the socket.
+ *
+ * `--use-env-proxy` sends EVERY request through HTTP(S)_PROXY — the runner's own
+ * loopback traffic too: the hooks' recorder, a proxy registering, `bir setup`
+ * waiting for the recorder — unless NO_PROXY exempts the address. Measured on
+ * Node 24: `127.0.0.1`, `*` and a suffix such as `.0.0.1` do; `localhost`,
+ * `127.0.0.0/8` and `127.*` do not. Node and undici disagree on which spelling
+ * wins when both are set, so every one that is set must exempt it.
+ */
+export declare function loopbackBypassesProxy(env?: NodeJS.ProcessEnv): boolean;
+/** The addresses to add to NO_PROXY so the runner's loopback traffic skips the proxy. */
+export declare const LOOPBACK_NO_PROXY = "127.0.0.1,localhost,::1";
+/**
+ * What to tell a person whose proxy the runner will NOT use, or undefined. A
+ * proxy with a NO_PROXY that does not name 127.0.0.1 would swallow the runner's
+ * own loopback calls, so `--use-env-proxy` is left out rather than break every
+ * hook; the service is then reached directly, if at all.
+ */
+export declare function envProxyHint(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Make THIS process's loopback fetches skip the proxy when it runs with
+ * `--use-env-proxy` and NO_PROXY does not already exempt them: a launcher
+ * written behind a proxy keeps the flag after the shell's NO_PROXY changes.
+ * undici re-reads NO_PROXY per request, so fetch honours the change; so does
+ * every process started from here (a recorder `bir up` launches). Returns true
+ * when it changed anything. The flags carried into the entries are decided
+ * from the environment as it was ({@link nodeFlagsToCarry}).
+ */
+export declare function exemptLoopbackFromProxy(env?: NodeJS.ProcessEnv, execArgv?: string[]): boolean;
 /**
  * The node flags this process was started with that everything it sets up
  * should share. The install scripts run `bir setup` with `--use-system-ca`
  * when the Node supports it; a hook, a proxy or a recorder started without it
  * would then fail the first TLS-inspected upload while the install itself
  * succeeded.
+ *
+ * `--use-env-proxy` is carried the same way, and added when HTTPS_PROXY or
+ * HTTP_PROXY is set and this Node knows the flag: Node's `fetch` ignores those
+ * variables otherwise, so behind a proxy-only network every service call waited
+ * out a connect timeout. A FLAG rather than `NODE_USE_ENV_PROXY=1` in the
+ * entries' env on purpose: `bir-proxy` hands its environment to the user's own
+ * MCP server, and that server's networking is not ours to change.
+ *
+ * ONLY WHEN NO_PROXY EXEMPTS 127.0.0.1 ({@link loopbackBypassesProxy}). With the
+ * flag, Node sends the runner's loopback calls to the proxy too, which refuses
+ * or swallows them: the SessionStart hook could not see its own recorder, the
+ * proxies could not register, and `bir setup` timed out — on a network where
+ * all of that worked without the flag. So without that exemption the flag is
+ * neither added nor carried, and {@link envProxyHint} says what to set.
+ */
+export declare function nodeFlagsToCarry(execArgv?: string[], env?: NodeJS.ProcessEnv): string[];
+/**
+ * A wrapped entry is always a stdio entry: the proxy is the process the host
+ * spawns. Fields the client understands and the proxy does not care about
+ * (`disabled`, `autoApprove`, `timeout`, …) are carried over from the original.
  */
-export declare function nodeFlagsToCarry(execArgv?: string[]): string[];
-/** A wrapped entry is always a stdio entry: the proxy is the process the host spawns. */
 export interface WrappedEntry {
     command: string;
     args: string[];
     env?: Record<string, string>;
+    [field: string]: unknown;
 }
+/**
+ * The env variable a wrapped REMOTE entry carries its upstream's static
+ * headers in: a JSON object, `{"Header-Name": "value", …}`. bir-proxy reads it
+ * (merged with any `--header K:V` arguments, which an entry an older runner
+ * wrote still has), and never hands it to a stdio upstream. In the env rather
+ * than on the command line because argv is visible to every local user
+ * (`ps`, /proc), and a header is usually a credential.
+ */
+export declare const UPSTREAM_HEADERS_ENV = "BIR_UPSTREAM_HEADERS";
+/**
+ * The headers in a wrapped entry's {@link UPSTREAM_HEADERS_ENV}, or none. Only
+ * string values count; anything unreadable is no headers rather than an error.
+ */
+export declare function upstreamHeadersFromEnv(env: Record<string, string> | undefined): Record<string, string>;
+/**
+ * `npx … <bin>`, pinned and offline-first, for an MCP server entry.
+ *
+ * Plain `npx` on every platform, Windows included. Claude Code spawns MCP
+ * servers through cross-spawn, which resolves `npx` to `npx.cmd` and escapes
+ * each argument for cmd.exe the way cmd.exe reads it. Wrapping the entry in
+ * `cmd /c` instead hands cmd.exe a line it parses itself — and everything after
+ * `--` is the user's own server invocation: `?a=1&b=2` in a URL ran `b=2` as a
+ * command, `|` and `>` piped or redirected the proxy's stdout, `^1.2.0` lost its
+ * caret and `%VAR%` was expanded. `platform` is accepted and ignored.
+ */
+export declare function npxInvocation(bin: string, version: string | undefined, _platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/**
+ * `npx … <bin>` for a COMMAND HOOK (the SessionStart `bir-hooks ensure`).
+ *
+ * Claude Code spawns a hook's exec form directly, without cross-spawn's
+ * `.cmd` resolution, so on native Windows it keeps `cmd /c` — safe there
+ * because every argument is ours: a pinned package spec, a bin name and
+ * fixed flags, never a user's text.
+ */
+export declare function npxHookInvocation(bin: string, version: string | undefined, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/** True when an entry is spawned through npx (with or without `cmd /c`). */
+export declare function isNpxEntry(config: McpServerConfig): boolean;
 /** True when this entry already points at `bir-proxy` — makes install idempotent. */
 export declare function isWrapped(config: McpServerConfig): boolean;
 /**
@@ -89,6 +208,60 @@ export declare function isWrapped(config: McpServerConfig): boolean;
  * host would have spawned it.
  */
 export declare function wrapEntry(config: McpServerConfig, opts: WrapOptions): WrappedEntry;
+/**
+ * Rebuild the original entry from a wrapped one — for an entry wrapped by an
+ * older runner or on another machine (nothing stashed here), and for remote
+ * header values, which the sidecar does not keep. `undefined` when `wrapped`
+ * is not an entry `wrapEntry` could have produced.
+ */
+export declare function unwrapEntry(wrapped: McpServerConfig): McpServerConfig | undefined;
+/**
+ * The options `wrapEntry` was given for `wrapped`, read back from the entry:
+ * the interpreter, its flags and the proxy script (or the npx spec), the
+ * control URL and `--no-correlation`. What lets a local copy be re-generated
+ * over a changed source without knowing how `bir install` was run.
+ */
+export declare function wrapOptionsOf(wrapped: McpServerConfig): Omit<WrapOptions, "serverName"> | undefined;
+/** Two entries that say the same thing, whatever order or optional spelling they were written in. */
+export declare function sameServerConfig(a: unknown, b: unknown): boolean;
+/**
+ * A fingerprint of an entry (see {@link canonicalServer}), kept in an
+ * override's record so a later change to the entry it copied is noticed —
+ * without keeping the entry, whose env and headers are credentials.
+ */
+export declare function configSha(config: unknown): string;
+/**
+ * Whether a remote entry can be wrapped without breaking it.
+ *
+ * The proxy can only send what the entry spells out. A server Claude Code signs
+ * in itself — OAuth through `/mcp`, a `headersHelper` script, `${VAR}` headers
+ * Claude Code expands — would reach the upstream with no credentials, answer
+ * 401 on every call, and lose the "Authenticate" option in `/mcp` because the
+ * entry is now a stdio one. Those are left unwrapped: their calls are still
+ * recorded by the PreToolUse/PostToolUse hooks. Only an entry carrying a
+ * literal credential header is wrapped by default; `--server <name>` wraps
+ * any other one anyway.
+ */
+export declare function remoteWrapBlocker(config: RemoteServerConfig): string | undefined;
+/**
+ * `config` as the sidecar keeps it: a remote entry's header VALUES and a stdio
+ * entry's env VALUES are dropped — they are credentials more often than not
+ * (API keys, database URLs, bearer tokens), and a second long-lived copy of
+ * them in installed.json is exposure for nothing. The names stay; uninstall
+ * reads the values back from the wrapped entry, which carries them verbatim
+ * (and carries a key the user rotated since, which a stash would not).
+ */
+export declare function redactSecrets(config: McpServerConfig): {
+    config: McpServerConfig;
+    redacted: boolean;
+};
+/**
+ * Undo {@link redactSecrets}: the stash, with every redacted value read back
+ * from `wrapped`. Undefined when a value cannot be found there (the wrapped
+ * entry was changed or removed) — restoring an entry without its credentials
+ * would break it, so the caller leaves the entry alone instead.
+ */
+export declare function restoreSecrets(stash: McpServerConfig, wrapped: McpServerConfig | undefined): McpServerConfig | undefined;
 /**
  * The entry for the scenario server itself. Not a proxy: it wraps nothing and
  * spawns nothing, it just forwards one call to the control server.
@@ -99,17 +272,55 @@ export declare function scenarioEntry(opts: {
     controlUrl?: string;
     version?: string;
     nodeFlags?: string[];
+    node?: string;
+    platform?: NodeJS.Platform;
 }): WrappedEntry;
 /** True when this entry is the scenario server — makes `install --replay` idempotent. */
 export declare function isScenarioServer(config: McpServerConfig): boolean;
 export interface InstalledRecord {
-    /** Original entry, verbatim. `null` means the entry did not exist before. */
+    /**
+     * Original entry, verbatim — except header and env values (see
+     * {@link InstalledRecord.secretsRedacted}). `null` means the entry did not
+     * exist in `scope` before: uninstall removes it rather than restoring it.
+     */
     original: McpServerConfig | null;
     scope: Scope;
     /** File the entry was written to, so uninstall edits the same one. */
     file: string;
     cwd: string;
     installedAt: number;
+    /**
+     * Set when the wrapped entry was ADDED to the local scope as an override of
+     * the same name in `source` (the project's `.mcp.json`, or the user scope).
+     * The source entry itself is never touched: `.mcp.json` is a file a team
+     * commits, and the user scope applies to every project on the machine.
+     */
+    override?: {
+        source: Scope;
+    };
+    /**
+     * An override's {@link configSha} of the entry it copied, as it was then. The
+     * copy is frozen and outranks that entry, so a teammate's change to
+     * `.mcp.json` (or a token rotated in the user scope) would otherwise never
+     * reach this project; `bir doctor` compares it, and `bir setup` re-copies.
+     */
+    sourceSha?: string;
+    /** Local scope: the `~/.claude.json` project keys the entry was written under. */
+    keys?: string[];
+    /**
+     * `original.headers` / `original.env` hold names only; the values are read
+     * back from the wrapped entry (see {@link redactSecrets}). Such a record is
+     * kept under a {@link REDACTED_KEY_PREFIX} key, out of an older runner's sight.
+     */
+    secretsRedacted?: boolean;
+    /**
+     * Wrapped although {@link remoteWrapBlocker} advised against it, or although
+     * Claude Code had not yet been told to use the `.mcp.json` server it copies
+     * (config/mcp-approval.ts), because the person named it with `--server`.
+     * Remembered, so the next plain `bir setup` (the upgrade path) keeps that
+     * choice instead of un-wrapping it. A server they REJECTED is never kept.
+     */
+    optedIn?: boolean;
 }
 /**
  * A file we edited, captured before the first edit.
@@ -118,11 +329,64 @@ export interface InstalledRecord {
  * still hashes to it is restored from `originalText` **byte-for-byte**; a file
  * edited since is repaired entry-by-entry instead, because clobbering somebody's
  * later edit is worse than an imperfect restore.
+ *
+ * `stale` is set once somebody else changed the file between two of our
+ * writes: from then on `originalText` is older than a change we never saw, and
+ * restoring it would delete that change even though the file hashes to our
+ * last write. Never kept for `~/.claude.json` at all — Claude Code rewrites it
+ * constantly and it holds every project's settings; it is repaired entry by
+ * entry, always.
  */
 export interface FileBackup {
     originalText: string | null;
     writtenSha: string;
+    stale?: boolean;
+    /**
+     * A `.mcp.json` whose servers carry env or header VALUES (API keys, bearer
+     * tokens) is not kept verbatim — that would be a second long-lived copy of
+     * them under ~/.baseinstrunner. Its text is kept with each value's literal
+     * replaced by a placeholder, and {@link FileBackup.originalText} stays null;
+     * uninstall reads the values back from the entries in the file (wrapped or
+     * not) and restores the file byte-for-byte only when the result hashes to
+     * `sha`, the original's. See {@link protectBackupText}. A runner older than
+     * this field (0.2.12) reads the backup as a file install created, and never
+     * writes it back whole.
+     */
+    redacted?: RedactedText;
 }
+/** A file's text with its env and header values replaced by placeholders. */
+export interface RedactedText {
+    /** The text, each secret's JSON string literal replaced by a placeholder literal. */
+    text: string;
+    /** sha256 of the original text: a restore is used only when it matches. */
+    sha: string;
+    /** Placeholder `i` is the value of `mcpServers[server][field][key]`. */
+    secrets: Array<{
+        server: string;
+        field: "env" | "headers";
+        key: string;
+    }>;
+}
+/**
+ * The backup of a project file's pre-install text, as installed.json keeps it
+ * (SEC-8): verbatim when it holds no env or header value; otherwise with every
+ * such value's literal replaced by a placeholder ({@link FileBackup.redacted}).
+ * When that cannot be done exactly — a value spelled with escapes, a text that
+ * does not parse, a placeholder already in the text — no text is kept at all
+ * and the file is repaired entry by entry on uninstall (`stale`), which loses
+ * the byte-for-byte restore and nothing else.
+ */
+export declare function protectBackupText(text: string): FileBackup;
+/**
+ * The text a backup restores: its verbatim original, or the redacted one with
+ * every value read back from `currentText` — the file as it is now, whose
+ * entries (wrapped by us, or left as they were) carry those values. Null for a
+ * file install created; undefined when the original cannot be rebuilt exactly
+ * (a value is gone, or the result does not hash to the original's).
+ */
+export declare function backupOriginalText(backup: FileBackup, currentText: string | null): string | null | undefined;
+/** True when a backup says the file did not exist before install (nothing to restore). */
+export declare function backupIsCreation(backup: FileBackup): boolean;
 /**
  * The replay switches an operator set for one project, kept where a recorder
  * started by a hook can read them. They used to be environment variables read
@@ -131,8 +395,21 @@ export interface FileBackup {
  * the SessionStart hook started it with Claude Code's environment instead.
  */
 export interface ReplayPolicy {
-    /** `bir replay off` → false. Absent means on. */
+    /**
+     * `bir replay off` → false, `bir replay on` → true. Absent means on — the
+     * recorder reads `enabled !== false` at start (control/recorder-main.ts), and
+     * `BIR_REPLAY` in its environment outranks it.
+     */
     enabled?: boolean;
+    /**
+     * `"install"` when `enabled: false` was written by an install rather than by
+     * the person: `bir setup --no-replay`, `bir uninstall --replay`, or a `bir
+     * install` without `--replay` in a project with no scenario server. Replay
+     * was not asked for there, and a direct replay would have no delivery tool.
+     * An install that asks for replay again turns such an off back on; one the
+     * person set with `bir replay off` it never does. See {@link settleReplaySwitch}.
+     */
+    disabledBy?: "install";
     /** Server keys eligible for direct execution. Absent means every wrapped one. */
     allowServers?: string[];
     /** `BIR_MIN_STEER_SIMILARITY`'s stored twin. */
@@ -157,11 +434,26 @@ export interface ProjectRecord {
      * a fleet's absolute paths into pinned-npx entries.
      */
     invocation?: Invocation;
+    /**
+     * True when {@link ProjectRecord.invocation} was asked for with a flag. A
+     * remembered `npx` without it is the old flag-less default, which an
+     * installed `bir` replaces with its absolute path.
+     */
+    invocationChosen?: boolean;
+    /**
+     * Whether an install added `.claude/settings.local.json` to the repository's
+     * exclude file (false: the line was already there). Uninstall removes only a
+     * line it added. Absent (older installs): removed, as before.
+     */
+    excludeAdded?: boolean;
     /**
      * `bir scenario editing on|off` (editSteps.md D2, in the BaseIn repository):
      * whether this project's `bir` MCP server also offers the tools that CHANGE
      * a calculated scenario — `scenario_check`, `scenario_edit`, `scenario_undo`.
-     * Absent means off. The read tools are offered either way.
+     * Absent means off. The tools that only READ a scenario come with it too,
+     * and otherwise only with `BIR_SCENARIO_TOOLS=read` in that server's
+     * environment: their definitions ride along with every request of every
+     * session, and only somebody working on a scenario calls them.
      *
      * Per project, and off by default, because the `bir` server runs in every
      * session of every installed project — a fleet included — and a plan must
@@ -169,6 +461,20 @@ export interface ProjectRecord {
      * commands ignore it: a person in a terminal is asked before each one.
      */
     editing?: boolean;
+    /**
+     * Every `.claude.json` an install for this project wrote local-scope entries
+     * to. Claude Code reads `$CLAUDE_CONFIG_DIR/.claude.json` when that is set,
+     * so a project installed from two environments (two profiles, an IDE
+     * terminal) has entries in two files — and an uninstall run from either must
+     * find both, or the other profile's servers keep naming the runner's files
+     * after the runner is gone.
+     */
+    claudeJsonFiles?: string[];
+    /**
+     * The upgrade note about auto-approval (wrapped MCP calls are no longer
+     * approved by the runner) was shown for this project; it is said once.
+     */
+    approvalNoteShown?: boolean;
 }
 export interface InstalledSidecar {
     version: 1;
@@ -187,7 +493,10 @@ export interface InstalledSidecar {
      * gets its own port, chosen once and reused.
      */
     projects?: Record<string, ProjectRecord>;
-    /** `<cwd>::<serverName>` → record. */
+    /**
+     * `<cwd>::<serverName>` → record; `v2|<cwd>::<serverName>` for a record
+     * whose stash has its secrets blanked ({@link REDACTED_KEY_PREFIX}).
+     */
     servers: Record<string, InstalledRecord>;
     /** Absolute path → the text that was there before we touched it. */
     files?: Record<string, FileBackup>;
@@ -195,6 +504,40 @@ export interface InstalledSidecar {
     hookFiles?: string[];
 }
 export declare function readSidecar(): InstalledSidecar;
+/**
+ * The prefix of the key a record is kept under when its stash has its
+ * secrets blanked ({@link InstalledRecord.secretsRedacted}).
+ *
+ * A runner older than redaction (0.2.12) finds its records by the exact key
+ * `<cwd>::<name>`, or by that prefix, and writes `original` back VERBATIM: on
+ * a rollback (`BIR_VERSION=0.2.12`, a second `bir` earlier on PATH, `npx
+ * @basein/runner@0.2.12`) its `bir uninstall` would put a server back with its
+ * API key blanked, the key's only copy — the wrapped entry — overwritten. Under
+ * this prefix it finds no record, says nothing to undo for that server, and
+ * leaves the wrapped entry, credentials and all, alone. Records it can restore
+ * correctly (no env, no headers, or an `original: null`) keep the old key.
+ */
+export declare const REDACTED_KEY_PREFIX = "v2|";
+/** The key a record for `serverName` in `cwd` belongs under, redacted or not. */
+export declare function recordKey(cwd: string, serverName: string, redacted?: boolean): string;
+/**
+ * Put every record under the key its stash calls for ({@link REDACTED_KEY_PREFIX}):
+ * a redacted record written under the plain key (by an earlier build, or by
+ * code that wrote the plain key) moves out of an older runner's sight, and
+ * two records for one server — one per key shape, left by installs of both
+ * versions — become the newer one. Returns true when anything moved.
+ */
+export declare function normaliseRecordKeys(servers: Record<string, InstalledRecord>): boolean;
+/**
+ * Write the sidecar so no reader ever sees half of it (a recorder that read a
+ * torn file used to start with a random token and refuse every hook).
+ *
+ * `readSidecar` answers an empty sidecar for a file it cannot parse, so the
+ * next write would silently replace every project's originals, tokens and
+ * ports with nothing. Before that happens the unreadable file is copied aside
+ * as `installed.json.corrupt-<time>`, where a person (or support) can get the
+ * originals back.
+ */
 export declare function writeSidecar(sidecar: InstalledSidecar): void;
 export declare function sidecarKey(cwd: string, serverName: string): string;
 /** The lowest port a project is given when none was asked for. */
@@ -224,6 +567,14 @@ export declare function probeFreePort(port: number): Promise<boolean>;
  * kept as it is — the hooks name it — and the recorder says so if it is busy.
  */
 export declare function allocateFreeProjectPort(sidecar: InstalledSidecar, cwd: string): Promise<number>;
+/**
+ * A new port for a project whose recorded one this machine will no longer let
+ * it bind (a Hyper-V/WSL/Docker exclusion that moved after a reboot, or another
+ * program). The lowest free one no other project holds, never `avoid`;
+ * `undefined` when none of the 200 is free. The caller rewrites the hooks and
+ * every wrapped entry's control URL — `bir setup` does, by re-running install.
+ */
+export declare function allocateReplacementPort(sidecar: InstalledSidecar, cwd: string, avoid: number): Promise<number | undefined>;
 /** Merge `patch` into the record for `cwd`, creating it when absent. */
 export declare function setProjectRecord(sidecar: InstalledSidecar, cwd: string, patch: Partial<ProjectRecord> & Pick<ProjectRecord, "port">): ProjectRecord;
 /** The bearer token this project's hooks and control server share. */
@@ -237,4 +588,31 @@ export declare function editingEnabled(sidecar: InstalledSidecar, cwd: string):
  * inventing a record would invent a port the hooks do not use.
  */
 export declare function setEditing(sidecar: InstalledSidecar, cwd: string, on: boolean): ProjectRecord | undefined;
+/**
+ * What an install or uninstall said about calculated replay:
+ *
+ *   wanted     `--replay` (and `bir setup`, which adds it by default)
+ *   refused    `bir setup --no-replay`, `bir uninstall --replay`
+ *   unasked    a `bir install` without `--replay`
+ */
+export type ReplayIntent = "wanted" | "refused" | "unasked";
+/**
+ * Keep this project's stored replay switch ({@link ReplayPolicy.enabled}) in
+ * line with what the person asked for, so the recorder never steers — or runs
+ * steps unattended — in a project that did not opt in. It used to default to
+ * on everywhere: `bir setup --no-replay` printed "replay not installed" while
+ * the recorder replayed matched prompts anyway, and a direct plan named a
+ * delivery tool the session did not have.
+ *
+ *   refused  → off, unless it is off already.
+ *   unasked  → off, but only while the switch was never set and no scenario
+ *              server is here (a project that has one keeps it — a plain
+ *              `bir install --server x` must not take replay away — and
+ *              `bir replay on|off` is the person's to keep).
+ *   wanted   → on again, but only when an install turned it off; a
+ *              `bir replay off` stays off.
+ *
+ * Returns what changed, or undefined. The caller writes the sidecar.
+ */
+export declare function settleReplaySwitch(sidecar: InstalledSidecar, cwd: string, intent: ReplayIntent, scenarioServerHere: boolean): "on" | "off" | undefined;
 //# sourceMappingURL=generate.d.ts.map