@basein/runner 0.2.12 → 0.3.0

package/dist/control/daemon.d.ts

@@ -22,8 +22,11 @@
  * with a working directory that must equal the project's, each needing the
  * person to know which one they are on. The hook already runs in the right
  * directory with the right environment at exactly the right moment, and Claude
- * Code already supervises it. What is lost is restart-on-crash mid-session,
- * which the proxies already survive (they fall to Tier 2 and say so).
+ * Code already supervises it. Restart-on-crash mid-session is the proxies'
+ * part: a bound proxy (or `bir-scenario`) that finds the recorder gone —
+ * refusing connections, its pid dead — spawns `bir-hooks revive`
+ * ({@link reviveDaemon}), rate limited, unless `bir down` stopped it on
+ * purpose.
  *
  * HOW IT IS LAUNCHED. The daemon opens its own log file (`BIR_DAEMON_LOG`) and
  * inherits nothing from our stdio. On POSIX that is a `detached` spawn with
@@ -32,50 +35,177 @@
  * short-lived `powershell.exe`: libuv's CreateProcess inherits *every*
  * inheritable handle of the parent, not only the three it was told about, and
  * a node started under a PowerShell layer (the `irm | iex` bootstrap, a `.ps1`
- * shim, a captured `bir up`) carries an extra copy of its own stdout pipe. A
- * daemon that inherits it holds that pipe open for days, and whoever is reading
- * it never sees EOF. `Start-Process` passes the environment and no handles.
+ * shim, a captured `bir up`, a `$r = claude -p …`) carries an extra copy of its
+ * own stdout pipe. A daemon that inherits it holds that pipe open for days, and
+ * whoever is reading it never sees EOF. `Start-Process` passes the environment
+ * and no handles. It costs about a second, once per project per boot; a direct
+ * spawn is faster but only safe when nothing above the hook captured its
+ * output, so it is an opt-in (`BIR_WINDOWS_LAUNCH=spawn`), not the default.
+ *
+ * WHERE IT RUNS. The daemon's working directory is the runner's own state
+ * directory, never the project: on Windows a process's current directory
+ * cannot be renamed or deleted, and an invisible recorder holding the project
+ * folder made "delete the folder", `git worktree remove` and a re-clone fail
+ * with "in use by another program". The project is passed as `BIR_DAEMON_CWD`.
+ *
+ * WHAT IT MAY NOT DO. Every path is bounded: the SessionStart hook has a budget
+ * well inside Claude Code's hook timeout (ensure-hook.ts), a recorder that is
+ * alive but slow is never mistaken for a dead one (that started a duplicate
+ * that could not bind), and nothing here touches the network — the recorder
+ * listens before it signs in (recorder-keeper.ts).
  */
-import { type DiscoveryInfo } from "./discovery.js";
-/** A log file larger than this is rolled over to `.1` when a daemon starts. */
+import { type DiscoveryInfo, type SupersededRecorder } from "./discovery.js";
+import { type InstalledSidecar } from "../config/generate.js";
+export { listSupersededRecorders, type SupersededRecorder } from "./discovery.js";
+/** A log file larger than this is rolled over to `.1` (at start, and while it runs). */
 export declare const LOG_ROTATE_BYTES: number;
 /** Marks a `bir-hooks` as started by this module; it says so in its discovery file. */
 export declare const DAEMON_ENV = "BIR_DAEMON";
 /** Where that process writes its audit lines. It opens the file itself. */
 export declare const DAEMON_LOG_ENV = "BIR_DAEMON_LOG";
+/**
+ * The project a background recorder serves. It runs in the runner's state
+ * directory, not the project (see WHERE IT RUNS above), so it cannot learn the
+ * project from its own working directory.
+ */
+export declare const DAEMON_CWD_ENV = "BIR_DAEMON_CWD";
 /**
  * The setup token's environment variable (`bir setup` reads it when `--token`
  * is absent). Never handed to the recorder: it is a one-use secret for signing
  * in, and a process that lives for days has no business holding it.
  */
 export declare const SETUP_TOKEN_ENV = "BIR_SETUP_TOKEN";
+/**
+ * An Anthropic key meant for the runner's derivation, and nothing else. Set
+ * explicitly; it is the only key the recorder uses by default.
+ */
+export declare const DERIVE_KEY_ENV = "BIR_DERIVE_API_KEY";
+/**
+ * `1` lets the recorder use an `ANTHROPIC_API_KEY` from its environment for
+ * derivation, as it did before. Off by default: the hook-started recorder has
+ * Claude Code's environment, and an API-billed Claude Code has its key there —
+ * using it silently spent the person's own money on something the service
+ * does for a signed-in runner.
+ */
+export declare const USE_API_KEY_ENV = "BIR_USE_ANTHROPIC_API_KEY";
+/** `spawn` launches the Windows daemon directly instead of through PowerShell. */
+export declare const WINDOWS_LAUNCH_ENV = "BIR_WINDOWS_LAUNCH";
+/**
+ * `bir-hooks revive --cwd <project>`: bring the project's recorder back when
+ * it is gone. Spawned detached by a bound `bir-proxy` or `bir-scenario` whose
+ * recorder refuses connections and whose pid is dead (see {@link reviveDaemon}).
+ */
+export declare const REVIVE_ARG = "revive";
+/**
+ * {@link EnsureOptions.probeIdle}: the gap between the two `/health` probes
+ * that tell a recorder that only *reports* a run open from one doing work.
+ */
+export declare const IDLE_PROBE_GAP_MS = 2500;
 export interface DaemonStatus {
     info: DiscoveryInfo;
     health: Record<string, unknown>;
 }
+/** The recorder is running but did not answer in time: busy, not gone. */
+export declare class RecorderBusyError extends Error {
+    readonly pid: number;
+    constructor(pid: number);
+}
+/** A revive found the project's recorder stopped on purpose (`bir down`): it is left down. */
+export declare class RecorderStoppedError extends Error {
+    constructor();
+}
 /** Absolute path of `dist/bin/bir-hooks.js` in the package this module runs from. */
 export declare function hooksScriptPath(): string;
+/** What answered on a recorder's address, told apart as far as HTTP can. */
+export type HealthProbe = 
+/** A recorder that accepted the token. */
+{
+    kind: "ok";
+    health: Record<string, unknown>;
+}
+/** Nothing listening (connection refused, or unreachable). */
+ | {
+    kind: "refused";
+    reason: string;
+}
+/** Something accepted the connection and did not answer in time. */
+ | {
+    kind: "timeout";
+}
+/** A listener that refused the token. */
+ | {
+    kind: "unauthorized";
+    status: number;
+}
+/** A listener that answered, but not as a recorder. */
+ | {
+    kind: "foreign";
+    status: number;
+};
+/**
+ * `GET /health` with the bearer token, bounded, with the failure kept apart:
+ * "refused" means gone, "timeout" means busy, and the difference is the one
+ * that decides whether a second recorder is started.
+ */
+export declare function probeHealth(url: string, token: string, timeoutMs?: number): Promise<HealthProbe>;
 /**
  * The live control server for `cwd`, or undefined.
  *
- * "Live" means the discovery file is fresh, its pid is alive, **and** it
- * answers `/health` with its token. A file left by a crash fails the second
- * test; a process that hung, or a recycled pid, fails the third.
+ * "Live" means the discovery file names a pid that is alive **and** that
+ * answers `/health` with its token. A file left by a crash fails the first
+ * test; a process that hung, or a recycled pid, fails the second.
  */
 export declare function daemonStatus(cwd: string): Promise<DaemonStatus | undefined>;
+/**
+ * This project's recorder, found by its port rather than its discovery file,
+ * and its file written again. For a recorder whose file was removed (by hand,
+ * by an older runner that took a slow recorder for a dead one): starting a
+ * second one would only find the port taken.
+ *
+ * A file that already names the recorder that answered is left as it is. What
+ * is written here is rebuilt from `/health`, which does not say whether the
+ * process runs in the background or where its log is: overwriting the
+ * recorder's own, complete record with it made `bir status` lose the log path
+ * and the start time, and hid the recorder from the reinstall check (which
+ * only replaces background recorders) — for the half hour until its own
+ * heartbeat. The recorder also rewrites a record of itself that differs from
+ * what it would write (recorder-main.ts), so what this writes is short-lived.
+ */
+export declare function rediscover(cwd: string, port: number, token: string, timeoutMs?: number): Promise<DaemonStatus | undefined>;
 export interface EnsureOptions {
     /** `dist/bin/bir-hooks.js` to run. Defaults to this package's. */
     hooksScript?: string;
     /** Environment for the new process. Defaults to this process's. */
     env?: NodeJS.ProcessEnv;
-    /** How long to wait for a fresh process to answer `/health`. */
+    /**
+     * The whole call's budget: finding, replacing and starting the recorder.
+     * Default 15 s. The SessionStart hook passes less (ensure-hook.ts).
+     */
     timeoutMs?: number;
     /**
-     * Restart a running recorder whose version is not ours, provided no session
-     * is mid-run. Off by default: only `bir setup`/`bir up` and the SessionStart
-     * hook — the moments a restart costs nothing — ask for it.
+     * Restart a running recorder that is an older version than ours, provided
+     * no session is mid-run. Off by default: only `bir setup`/`bir up` and the
+     * SessionStart hook — the moments a restart costs nothing — ask for it. A
+     * newer recorder (another runner copy on this machine) is kept.
      */
     restartOnSkew?: boolean;
+    /**
+     * Do not take the word of a recorder that predates the idle bound. A 0.2.12
+     * (or older) recorder's `/health` has no `sessions[].idleMs`, and its
+     * `active` means "a run was opened and never finished" — an Esc-interrupted
+     * turn, a crashed window or a `claude -p` run leaves one open for the
+     * recorder's whole life, and it was then never replaced. With this set, such
+     * a recorder counts as idle — and replaceable — when two `/health` probes
+     * {@link IDLE_PROBE_GAP_MS} apart show no change in its sessions' steps and
+     * no registered proxy of it is alive. Costs that gap, so only `bir setup`
+     * and `bir up` pass it; the SessionStart hook stays conservative.
+     */
+    probeIdle?: boolean;
+    /**
+     * Set by {@link reviveDaemon} only: honour a `bir down` (the down marker)
+     * instead of clearing it, and throw {@link RecorderStoppedError} when found.
+     */
+    revive?: boolean;
 }
 export interface EnsureResult {
     status: DaemonStatus;
@@ -86,14 +216,150 @@ export interface EnsureResult {
 }
 /** How many of the recorder's sessions are mid-run right now. */
 export declare function activeSessions(health: Record<string, unknown>): number;
+/**
+ * `a` against `b` as versions: -1, 0 or 1, or undefined when either is not
+ * `x.y.z` (with an optional pre-release, which sorts below its release, and
+ * build metadata, which is ignored).
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1 | undefined;
+/**
+ * True for the `/health` of a recorder that predates the idle bound (0.2.12
+ * and older): it lists sessions, and none of them says how long it has been
+ * idle. Its `active` is then "a run is open", with nothing to close one that
+ * was abandoned. An empty list says nothing either way (and counts none active).
+ */
+export declare function isLegacyHealth(health: Record<string, unknown>): boolean;
+/** A TCP port number, or undefined for anything that is not one. */
+export declare function validPort(value: unknown): number | undefined;
+/** The address this project's hooks were written with, as far as anything recorded it. */
+export interface ProjectEndpoint {
+    /**
+     * The port the hooks post to: a valid `BIR_CONTROL_PORT`, else the
+     * project's record. Undefined when neither names one — the recorder then
+     * takes the machine-wide or default port and may fall back to another.
+     */
+    port?: number;
+    /** The project's token, when the project has a record. */
+    token?: string;
+    /** True when {@link port} is known: a recorder must bind exactly it. */
+    pinned: boolean;
+    /**
+     * True when `BIR_CONTROL_PORT=0` asks for any free port: the recorder binds
+     * an ephemeral one and says which in its discovery file, `/health` and its
+     * log. {@link port} is then undefined — no port is expected — so a running
+     * recorder is never replaced for listening on the "wrong" one. Absent
+     * otherwise. For tests and the smoke run, which must never take the real
+     * default port; a project's hooks name a fixed port, so 0 is not for them.
+     */
+    ephemeral?: true;
+}
+/**
+ * `BIR_CONTROL_PORT` read once, for everything that reads it: `"0"` is any
+ * free port, a valid port is that port, and anything else (unset, empty, not
+ * a number, out of range) is no setting at all.
+ */
+export declare function controlPortFromEnv(env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * The one reading of "which port and token does this project use", shared by
+ * the recorder (which binds it) and by {@link ensureDaemon} (which checks a
+ * running recorder against it). They used to read `BIR_CONTROL_PORT`
+ * differently: the recorder took an empty or invalid value as "the default
+ * port, pinned", the check ignored it and used the project's port — and every
+ * session start then "replaced" a recorder that could only ever bind the
+ * default port again. An invalid value is now ignored by both, and `0` means
+ * "any free port" to both (see {@link ProjectEndpoint.ephemeral}).
+ */
+export declare function projectEndpoint(cwd: string, env?: NodeJS.ProcessEnv, sidecar?: InstalledSidecar): ProjectEndpoint;
 /**
  * The control server for `cwd`, started in the background if none is live.
  *
- * Idempotent: a live one is returned as-is. Throws when a fresh process did
- * not come up in time, with the tail of its log, because "it did not start" is
- * the one message that must carry its own diagnosis.
+ * Idempotent: a live one is returned as-is — unless it is an older version
+ * with nothing mid-run (`restartOnSkew`; with `probeIdle`, a legacy
+ * recorder whose "mid-run" is a run nobody will finish counts as idle), or a
+ * background recorder that the project's current hooks do not reach
+ * (another port or token). Any call but a revive ends a `bir down`.
+ *
+ * WHAT A REINSTALL MAY NOT BREAK. Claude Code reads a session's hooks when the
+ * session starts and keeps them: every window opened before `bir install
+ * --port N` or `bir uninstall` + `bir setup` still posts to the old port with
+ * the old token, until it is closed. The old recorder is what answers them. So
+ *
+ *   - another **port**: the old recorder is left running for the sessions it
+ *     has seen, and a second one is started on the new port — two ports, no
+ *     conflict. The new one takes the discovery file; the old one steps back
+ *     from it, is recorded as superseded (`listSupersededRecorders`, so
+ *     `bir status`/`bir down` can find it), writes a log of its own, and
+ *     exits once it has had nothing left to serve for a day
+ *     (recorder-main.ts). A recorder that has never seen a session is simply
+ *     replaced;
+ *   - another **token** on the same port: only one process can listen there.
+ *     It is replaced between turns (a restart then costs the old windows their
+ *     next hooks, and gives every new one working hooks), never mid-run.
+ *
+ * A recorder that is alive but slow to answer is never replaced and never
+ * duplicated on its own port: this throws {@link RecorderBusyError} instead.
+ *
+ * Throws when a fresh process did not come up within the budget, with the
+ * tail of its log, because "it did not start" is the one message that must
+ * carry its own diagnosis.
  */
 export declare function ensureDaemon(cwd: string, opts?: EnsureOptions): Promise<EnsureResult>;
+/**
+ * Mark `cwd`'s recorder as stopped on purpose. {@link stopDaemon} does it; a
+ * revive then leaves the project without a recorder until something that
+ * asks for one on purpose — a session start, `bir up`, `bir setup` — clears
+ * it. Never throws.
+ */
+export declare function markDown(cwd: string): void;
+/** Remove the {@link markDown} marker. Never throws. */
+export declare function clearDownMarker(cwd: string): void;
+/** True while `cwd`'s recorder is marked as stopped on purpose. */
+export declare function isMarkedDown(cwd: string): boolean;
+export interface ReviveResult {
+    outcome: 
+    /** The project has no install record: nothing is started for it. */
+    "not_installed"
+    /** `bir down` stopped it on purpose, and nothing started it since. */
+     | "stopped_on_purpose"
+    /** A recorder was already there (another revive, or a session start, won). */
+     | "running"
+    /** This call started it. */
+     | "started"
+    /** Alive but not answering: left alone. */
+     | "busy" | "failed";
+    pid?: number;
+    error?: string;
+}
+/**
+ * `bir-hooks revive --cwd <project>` (K1): the recorder of an installed
+ * project, started again when it is gone.
+ *
+ * Every hook but SessionStart is an HTTP hook to the recorder, and a refused
+ * one is shown in the session as a hook error — on every prompt and every tool
+ * call — until the next SessionStart. A recorder killed mid-session (an
+ * antivirus, the OOM killer, a restart that missed its budget) used to stay
+ * gone until then. A bound `bir-proxy` or `bir-scenario` that finds it
+ * refusing connections with its pid dead spawns this, detached and rate
+ * limited, so the window of refused hooks is seconds.
+ *
+ * {@link ensureDaemon} with `restartOnSkew: false`, under the same start lock,
+ * so several revives at once start one recorder. Only for a project with an
+ * install record, and never after `bir down` (the down marker). Started even
+ * while the runner is off: the off recorder is what answers every hook `{}`.
+ * Never throws.
+ */
+export declare function reviveDaemon(cwd: string, opts?: Pick<EnsureOptions, "hooksScript" | "env" | "timeoutMs">): Promise<ReviveResult>;
+/**
+ * The environment a background recorder gets: the caller's, marked as a
+ * daemon, told its project, and without the secrets it has no use for.
+ *
+ * Nor `BIR_OFF` (K2), in any spelling: the recorder serves every window of
+ * the project, and a `BIR_OFF=1` in the environment of whichever window
+ * happened to start it switched all of them off for the recorder's life. That
+ * window's SessionStart hook tells the recorder its own session is off
+ * instead (ensure-hook.ts); the flag files still switch everything.
+ */
+export declare function daemonEnv(base: NodeJS.ProcessEnv, cwd: string, logFile: string): NodeJS.ProcessEnv;
 /**
  * Stop the control server for `cwd`.
  *
@@ -103,14 +369,130 @@ export declare function ensureDaemon(cwd: string, opts?: EnsureOptions): Promise
  * the polite route exists. Only a process that answers `/health` as the
  * recorder is ever signalled: a discovery file survives a crash, and its pid
  * is recycled — on Windows quickly — so "the pid in the file is alive" is not
- * evidence that it is ours.
+ * evidence that it is ours. One that is alive but too busy to answer is asked
+ * and waited for, never signalled.
  */
 export declare function stopDaemon(cwd: string, opts?: {
     timeoutMs?: number;
+    /**
+     * Mark the project's recorder as stopped on purpose (default true), so a
+     * proxy that finds it gone does not bring it back (`bir-hooks revive`)
+     * until a session start, `bir up` or `bir setup` asks for one. A restart
+     * inside {@link ensureDaemon} passes false.
+     */
+    markDown?: boolean;
 }): Promise<{
     stopped: boolean;
     pid?: number;
     stale?: boolean;
     forced?: boolean;
 }>;
+/**
+ * Stop one superseded recorder (see {@link listSupersededRecorders}) the same
+ * way {@link stopDaemon} stops the project's: asked, and signalled only when
+ * it answers `/health` as its own pid. Its record is removed once it is gone
+ * (its own exit does that too), or when nothing answers as it.
+ */
+export declare function stopSupersededRecorder(record: SupersededRecorder, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    stopped: boolean;
+    pid: number;
+    stale?: boolean;
+    forced?: boolean;
+}>;
+/**
+ * Stop every superseded recorder of `cwd` (or of every project, without
+ * one). For `bir down` and `bir uninstall`; the project's own recorder is
+ * {@link stopDaemon}'s.
+ */
+export declare function stopSupersededRecorders(cwd?: string, opts?: {
+    timeoutMs?: number;
+}): Promise<Array<{
+    record: SupersededRecorder;
+    stopped: boolean;
+    stale?: boolean;
+    forced?: boolean;
+}>>;
+/**
+ * Why the background recorder for a project could not bind the port its
+ * hooks name. Written by that recorder as it exits, read by `bir doctor` and
+ * the next SessionStart, removed by the first recorder that binds it.
+ */
+export interface PortProblem {
+    port: number;
+    /** `EADDRINUSE` or `EACCES`. */
+    code: string;
+    /**
+     * `excluded`: the system reserved the port (Windows/Hyper-V/WSL ranges).
+     * `foreign`: another program answers there. `unauthorized`: a listener
+     * that refused this project's token — possibly a recorder from an earlier
+     * install. `other-project`: another project's recorder. `unknown`: busy,
+     * and nothing answered.
+     */
+    holder: "excluded" | "foreign" | "unauthorized" | "other-project" | "unknown";
+    at: number;
+    /** One sentence for a person. */
+    detail: string;
+    /** What to run. */
+    fix: string;
+}
+export declare function readPortProblem(cwd: string): PortProblem | undefined;
+export declare function writePortProblem(cwd: string, problem: PortProblem): void;
+export declare function clearPortProblem(cwd: string): void;
+/**
+ * The log a background recorder writes its audit lines to.
+ *
+ * Three things the plain stream did not do. It never fails the process: a
+ * file (or a logs directory) that cannot be opened or written — a full disk,
+ * a read-only or locked profile — used to be an unhandled `'error'` that
+ * killed the recorder at start, and with it every hook of the session. Now the
+ * lines are dropped instead. It comes back: a failure is usually brief (the
+ * disk full for a minute, an antivirus scan holding the file), and a recorder
+ * that runs for days must not stay silent for all of them — the minute tick
+ * ({@link rotateIfLarge}) opens the file again. And it stays bounded while the
+ * recorder runs for weeks: rolled to `.1` once it passes
+ * {@link LOG_ROTATE_BYTES}, not only when a new one starts.
+ *
+ * And it shares a path safely. Two recorders of one project can run at once
+ * (a reinstall moved the hooks to another port while a window was open), and
+ * `ensureDaemon` rolls the log before a start. Whoever rolled it, the other
+ * writer's stream follows the renamed file — all its lines went to `.1`, which
+ * then grew without bound, and on Windows the held `.1` made every later roll
+ * fail. So the minute tick first checks that the file at the path is the one
+ * it writes, and opens the path again when it is not. A recorder superseded
+ * like that also moves to a file of its own ({@link moveTo}).
+ */
+export declare class DaemonLog {
+    private stream?;
+    /** The descriptor {@link stream} writes to, once it is open. */
+    private fd?;
+    private current;
+    private readonly maxBytes;
+    /** Set once lines have been dropped, so the reopen can say so. */
+    private droppedSince?;
+    constructor(path: string, maxBytes?: number);
+    /** The file lines go to now. */
+    get path(): string;
+    /** Open the file and point `console` (every `logLine`) at it. Never throws. */
+    open(): void;
+    /**
+     * Write to `path` from now on — a superseded recorder's own file, so the
+     * project's log keeps one writer and one rotation. Never throws.
+     */
+    moveTo(path: string): void;
+    private silence;
+    private attach;
+    /**
+     * Roll the file to `.1` if it is past the limit, and open it again if it
+     * failed earlier, or if the file at the path is no longer the one written
+     * (another writer rolled or removed it). True when it rolled. Never throws.
+     */
+    rotateIfLarge(): boolean;
+    /** Whether `onDisk` is the file this log's stream writes (true when it cannot tell). */
+    private writes;
+    /** After a failure: try the file again. A stream that fails again just stays silent. */
+    private reopen;
+    close(): void;
+}
 //# sourceMappingURL=daemon.d.ts.map