@basein/runner 0.2.11 → 0.3.0

package/dist/bin/scenario-liveness.d.ts

@@ -0,0 +1,194 @@
+/**
+ * scenario-liveness — the two things `bir-scenario` does besides answering MCP:
+ * it tells its project's recorder that a delivery tool is live
+ * (`POST /scenario/hello`), and it brings back a recorder that died
+ * mid-session (`bir-hooks revive`).
+ *
+ * WHY HELLO. A direct plan tells the model to call `mcp__bir__run_scenario`
+ * before any other tool. The control server used to announce one whenever the
+ * MCP config listed the `bir` server — but a configured server is not a
+ * connected one: a stale node path, a crash, the server disabled in `/mcp`, or
+ * a session run with `BIR_OFF=1` (which lists no tools) all leave the model
+ * told to call a tool it does not have. So this server says, on `initialize`,
+ * on `tools/list`, when the off switch flips, whenever its recorder changes,
+ * and every {@link HELLO_EVERY_MS} while it runs: this pid, this version, this
+ * many tools, off or not. The control server announces a direct plan only on
+ * the word of a live pid that lists a tool.
+ *
+ * WHY REVIVE. Every hook but SessionStart is an HTTP post to the recorder.
+ * With the recorder gone — killed by an antivirus, out of memory — Claude Code
+ * shows a hook error on every prompt and tool call until the next session
+ * start, `/clear` or compaction, because nothing else starts one mid-session.
+ * This server is the one long-lived process in every session of an installed
+ * project, wrapped servers or none, so it starts `bir-hooks revive --cwd <dir>`
+ * (which runs the ordinary ensure, under the ordinary start lock).
+ *
+ * NEITHER MAY COST THE SESSION ANYTHING.
+ *   - A hello is fire-and-forget: nothing on the MCP path awaits it, it is
+ *     bounded by {@link HELLO_TIMEOUT_MS}, one is in flight at a time, and a
+ *     recorder that cannot take it (not up yet, busy, an older version with no
+ *     such route) costs a retry later, never an error.
+ *   - A revive is a detached child that is never waited for, and it is started
+ *     only when the discovery file names a pid that is DEAD and the recorder's
+ *     address REFUSES the connection. A recorder that is alive but slow is never
+ *     replaced (that is how duplicates that cannot bind were made). A missing
+ *     discovery file is never revived either: `bir down` removes it, and a
+ *     recorder somebody stopped on purpose stays stopped. Only an installed
+ *     project is revived, at most once per {@link REVIVE_EVERY_MS} per process
+ *     (after a random wait of up to {@link REVIVE_JITTER_MS}, so the several
+ *     processes of a session that see the same death do not all start one),
+ *     less often each time a revive did not bring a recorder back, and not in
+ *     the server's first {@link REVIVE_GRACE_MS}, while the SessionStart hook
+ *     is starting the recorder itself.
+ *   - Neither writes a byte to stdout (the host's JSON-RPC stream), and
+ *     neither throws.
+ */
+/** A hello waits no longer than this for the recorder's answer. */
+export declare const HELLO_TIMEOUT_MS = 1000;
+/** A hello is repeated this often while the server runs (the recorder trusts one for 30 min). */
+export declare const HELLO_EVERY_MS: number;
+/**
+ * How often the discovery file is looked at: whether the recorder changed (a
+ * hello is owed to the new one) or died (a revive may be). One `stat`, and a
+ * parse only when the file changed.
+ */
+export declare const WATCH_EVERY_MS = 2000;
+/** At most one revive per this long per process; doubled each time one did not help. */
+export declare const REVIVE_EVERY_MS = 30000;
+/** The longest a revive waits, at random, before it looks again and starts. */
+export declare const REVIVE_JITTER_MS = 5000;
+/** The longest wait between revives that did not bring a recorder back. */
+export declare const REVIVE_MAX_EVERY_MS: number;
+/**
+ * No revive in a server's first this-long: it starts with the session, and so
+ * does the SessionStart hook, whose own ensure (up to 11 s, ensure-hook.ts) is
+ * what starts the recorder then — typically over a dead record left from
+ * before a reboot. Reviving beside it would only race it.
+ */
+export declare const REVIVE_GRACE_MS = 12000;
+/** How long the "does anything listen there" probe waits before calling the recorder busy. */
+export declare const REFUSED_PROBE_MS = 2000;
+/** What a hello says. */
+export interface HelloBody {
+    pid: number;
+    version: string;
+    /** How many tools this server lists now (0 when off). */
+    tools: number;
+    off: boolean;
+}
+/** A discovery record as written, its pid not yet checked. */
+export interface RecorderRecord {
+    url: string;
+    token: string;
+    pid: number;
+}
+/** How a request to the recorder's address ended. */
+export type Reach = "answered" | "refused" | "timeout" | "error";
+/**
+ * This project's discovery record, whether or not its pid is alive — the
+ * shared reader drops a dead pid's record, and a dead pid is exactly what a
+ * revive needs to see. Parsed again only when the file changed. Never throws.
+ */
+export declare function readRecorderRecord(cwd: string): RecorderRecord | undefined;
+/** Whether `cwd` is a project `bir setup`/`bir install` put the runner in. Never throws. */
+export declare function projectInstalled(cwd: string): boolean;
+/**
+ * Start `bir-hooks revive --cwd <cwd>` from this package, detached, and forget
+ * it: it reads nothing, writes nothing we could see, and exits by itself.
+ */
+export declare function launchRevive(cwd: string): Promise<void>;
+export interface LivenessOptions {
+    /** The project this server runs for. */
+    cwd: string;
+    /** What this server lists now. Called for every hello. */
+    state: () => {
+        tools: number;
+        off: boolean;
+    };
+    now?: () => number;
+    random?: () => number;
+    fetch?: typeof fetch;
+    record?: (cwd: string) => RecorderRecord | undefined;
+    alive?: (pid: number) => boolean;
+    installed?: (cwd: string) => boolean;
+    launch?: (cwd: string) => Promise<void> | void;
+    sleep?: (ms: number) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+    /** Default {@link REVIVE_GRACE_MS}. */
+    reviveGraceMs?: number;
+}
+/** See the module comment. One per `bir-scenario` process. */
+export declare class ScenarioLiveness {
+    private readonly opts;
+    private readonly cwd;
+    private readonly now;
+    private readonly random;
+    private readonly fetchImpl;
+    private readonly record;
+    private readonly alive;
+    private readonly installed;
+    private readonly launch;
+    private readonly sleep;
+    private readonly env;
+    private timer;
+    private stopped;
+    /** No revive before this (see {@link REVIVE_GRACE_MS}). */
+    private readonly reviveFrom;
+    private helloBusy;
+    /** A hello asked for while one was in flight: sent when it ends, with the state as it is then. */
+    private helloOwed;
+    /** The recorder the last hello was answered by (`url#pid`). */
+    private reached;
+    /** The recorder the last hello was sent to, answered or not. */
+    private tried;
+    private lastHelloAt;
+    private helloFailures;
+    private helloNotBefore;
+    private reviveBusy;
+    private reviveNotBefore;
+    /** Revives started since a recorder was last seen alive. */
+    private revivesInARow;
+    /** When this process last started one (0: never). */
+    private lastReviveAt;
+    /** Revives started by this process. */
+    revives: number;
+    /** Hellos a recorder answered. */
+    hellos: number;
+    constructor(opts: LivenessOptions);
+    /** Watch the discovery file every {@link WATCH_EVERY_MS}, on a timer that never keeps the process alive. */
+    start(everyMs?: number): void;
+    /** The host is gone: nothing more is sent or started. */
+    stop(): void;
+    /**
+     * Tell the recorder what this server lists, now — or, while a hello is in
+     * flight, as soon as it ends. Returns at once; never throws.
+     */
+    hello(why: string): void;
+    /**
+     * Something on the MCP path found no recorder (`run_scenario` found no live
+     * discovery file, or its request was refused): look now rather than at the
+     * next tick. Returns at once; never throws.
+     */
+    recorderGone(why: string): void;
+    /** One look at the discovery file. Exposed for tests; never throws. */
+    tick(): Promise<void>;
+    /**
+     * Where a hello goes, the way `run_scenario`'s request does: `BIR_CONTROL_URL`
+     * (with `BIR_CONTROL_TOKEN`, or the discovery file's token), else the
+     * discovery file — whose pid must be alive.
+     */
+    private target;
+    private state;
+    private sendHello;
+    /** Whether anything listens at `url`: only a refused connection counts as nothing. */
+    private probe;
+    /**
+     * A recorder is up: the revives before it helped (or were not needed), so the
+     * next death waits the plain {@link REVIVE_EVERY_MS} since the last one, not
+     * a doubled wait.
+     */
+    private recorderSeenAlive;
+    /** Start a revive if — and only if — the recorder is dead, refused and this project's. */
+    private checkRevive;
+}
+//# sourceMappingURL=scenario-liveness.d.ts.map

package/dist/bin/scenario-liveness.js

@@ -0,0 +1,459 @@
+/**
+ * scenario-liveness — the two things `bir-scenario` does besides answering MCP:
+ * it tells its project's recorder that a delivery tool is live
+ * (`POST /scenario/hello`), and it brings back a recorder that died
+ * mid-session (`bir-hooks revive`).
+ *
+ * WHY HELLO. A direct plan tells the model to call `mcp__bir__run_scenario`
+ * before any other tool. The control server used to announce one whenever the
+ * MCP config listed the `bir` server — but a configured server is not a
+ * connected one: a stale node path, a crash, the server disabled in `/mcp`, or
+ * a session run with `BIR_OFF=1` (which lists no tools) all leave the model
+ * told to call a tool it does not have. So this server says, on `initialize`,
+ * on `tools/list`, when the off switch flips, whenever its recorder changes,
+ * and every {@link HELLO_EVERY_MS} while it runs: this pid, this version, this
+ * many tools, off or not. The control server announces a direct plan only on
+ * the word of a live pid that lists a tool.
+ *
+ * WHY REVIVE. Every hook but SessionStart is an HTTP post to the recorder.
+ * With the recorder gone — killed by an antivirus, out of memory — Claude Code
+ * shows a hook error on every prompt and tool call until the next session
+ * start, `/clear` or compaction, because nothing else starts one mid-session.
+ * This server is the one long-lived process in every session of an installed
+ * project, wrapped servers or none, so it starts `bir-hooks revive --cwd <dir>`
+ * (which runs the ordinary ensure, under the ordinary start lock).
+ *
+ * NEITHER MAY COST THE SESSION ANYTHING.
+ *   - A hello is fire-and-forget: nothing on the MCP path awaits it, it is
+ *     bounded by {@link HELLO_TIMEOUT_MS}, one is in flight at a time, and a
+ *     recorder that cannot take it (not up yet, busy, an older version with no
+ *     such route) costs a retry later, never an error.
+ *   - A revive is a detached child that is never waited for, and it is started
+ *     only when the discovery file names a pid that is DEAD and the recorder's
+ *     address REFUSES the connection. A recorder that is alive but slow is never
+ *     replaced (that is how duplicates that cannot bind were made). A missing
+ *     discovery file is never revived either: `bir down` removes it, and a
+ *     recorder somebody stopped on purpose stays stopped. Only an installed
+ *     project is revived, at most once per {@link REVIVE_EVERY_MS} per process
+ *     (after a random wait of up to {@link REVIVE_JITTER_MS}, so the several
+ *     processes of a session that see the same death do not all start one),
+ *     less often each time a revive did not bring a recorder back, and not in
+ *     the server's first {@link REVIVE_GRACE_MS}, while the SessionStart hook
+ *     is starting the recorder itself.
+ *   - Neither writes a byte to stdout (the host's JSON-RPC stream), and
+ *     neither throws.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { pidAlive } from "../control/discovery.js";
+import { configDir, discoveryPath } from "../control/paths.js";
+import { nodeFlagsToCarry, projectRecord, readSidecar } from "../config/generate.js";
+import { errText, logDetail, logLine } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** A hello waits no longer than this for the recorder's answer. */
+export const HELLO_TIMEOUT_MS = 1_000;
+/** A hello is repeated this often while the server runs (the recorder trusts one for 30 min). */
+export const HELLO_EVERY_MS = 5 * 60_000;
+/**
+ * How often the discovery file is looked at: whether the recorder changed (a
+ * hello is owed to the new one) or died (a revive may be). One `stat`, and a
+ * parse only when the file changed.
+ */
+export const WATCH_EVERY_MS = 2_000;
+/** At most one revive per this long per process; doubled each time one did not help. */
+export const REVIVE_EVERY_MS = 30_000;
+/** The longest a revive waits, at random, before it looks again and starts. */
+export const REVIVE_JITTER_MS = 5_000;
+/** The longest wait between revives that did not bring a recorder back. */
+export const REVIVE_MAX_EVERY_MS = 5 * 60_000;
+/**
+ * No revive in a server's first this-long: it starts with the session, and so
+ * does the SessionStart hook, whose own ensure (up to 11 s, ensure-hook.ts) is
+ * what starts the recorder then — typically over a dead record left from
+ * before a reboot. Reviving beside it would only race it.
+ */
+export const REVIVE_GRACE_MS = 12_000;
+/** How long the "does anything listen there" probe waits before calling the recorder busy. */
+export const REFUSED_PROBE_MS = 2_000;
+/** The longest wait between hellos a recorder could not take. */
+const HELLO_RETRY_MAX_MS = 60_000;
+let recordCache;
+/**
+ * This project's discovery record, whether or not its pid is alive — the
+ * shared reader drops a dead pid's record, and a dead pid is exactly what a
+ * revive needs to see. Parsed again only when the file changed. Never throws.
+ */
+export function readRecorderRecord(cwd) {
+    try {
+        const path = discoveryPath(cwd);
+        let stamp;
+        try {
+            const st = statSync(path);
+            // The inode too: the file is replaced by a rename, and a coarse clock can
+            // give the replacement the same time and, by chance, the same size.
+            stamp = `${st.ino}:${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            recordCache = { path, stamp: "-", record: undefined };
+            return undefined;
+        }
+        if (recordCache && recordCache.path === path && recordCache.stamp === stamp)
+            return recordCache.record;
+        let record;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            record =
+                typeof parsed.url === "string" && typeof parsed.token === "string" && typeof parsed.pid === "number"
+                    ? { url: parsed.url, token: parsed.token, pid: parsed.pid }
+                    : undefined;
+        }
+        catch {
+            record = undefined; // being replaced this instant, or damaged: nothing to go on
+        }
+        recordCache = { path, stamp, record };
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `cwd` is a project `bir setup`/`bir install` put the runner in. Never throws. */
+export function projectInstalled(cwd) {
+    try {
+        return projectRecord(readSidecar(), cwd) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start `bir-hooks revive --cwd <cwd>` from this package, detached, and forget
+ * it: it reads nothing, writes nothing we could see, and exits by itself.
+ */
+export async function launchRevive(cwd) {
+    // Loaded here, not at the top: a revive is rare, and the module graph behind
+    // the daemon is not needed to answer MCP.
+    const { hooksScriptPath } = await import("../control/daemon.js");
+    const child = spawn(process.execPath, [...nodeFlagsToCarry(), hooksScriptPath(), "revive", "--cwd", cwd], {
+        // Not the project: on Windows a process holds its current directory, and
+        // the project folder must stay free to rename or delete (daemon.ts).
+        cwd: configDir(),
+        detached: true,
+        stdio: "ignore",
+        // A detached child on Windows would get a console window of its own.
+        windowsHide: true,
+        env: process.env,
+    });
+    child.on("error", (err) => logLine("scenario.revive_failed", { error: errText(err) }));
+    child.unref();
+}
+/** How a fetch to the recorder failed: busy (timed out), refused (nothing listens), or otherwise. */
+function reachOf(err) {
+    const e = err;
+    if (e?.name === "TimeoutError" || e?.name === "AbortError")
+        return "timeout";
+    if (e?.cause?.name === "TimeoutError")
+        return "timeout";
+    if (e?.cause?.code === "ECONNREFUSED")
+        return "refused";
+    // A host name with two addresses fails as one AggregateError of both.
+    const all = e?.cause?.errors;
+    if (Array.isArray(all) && all.length > 0 && all.every((x) => x?.code === "ECONNREFUSED"))
+        return "refused";
+    return "error";
+}
+function trimUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+const unrefSleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+});
+/** See the module comment. One per `bir-scenario` process. */
+export class ScenarioLiveness {
+    opts;
+    cwd;
+    now;
+    random;
+    fetchImpl;
+    record;
+    alive;
+    installed;
+    launch;
+    sleep;
+    env;
+    timer;
+    stopped = false;
+    /** No revive before this (see {@link REVIVE_GRACE_MS}). */
+    reviveFrom;
+    // ── hello ──
+    helloBusy = false;
+    /** A hello asked for while one was in flight: sent when it ends, with the state as it is then. */
+    helloOwed;
+    /** The recorder the last hello was answered by (`url#pid`). */
+    reached;
+    /** The recorder the last hello was sent to, answered or not. */
+    tried;
+    lastHelloAt = 0;
+    helloFailures = 0;
+    helloNotBefore = 0;
+    // ── revive ──
+    reviveBusy = false;
+    reviveNotBefore = 0;
+    /** Revives started since a recorder was last seen alive. */
+    revivesInARow = 0;
+    /** When this process last started one (0: never). */
+    lastReviveAt = 0;
+    /** Revives started by this process. */
+    revives = 0;
+    /** Hellos a recorder answered. */
+    hellos = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.cwd = opts.cwd;
+        this.now = opts.now ?? Date.now;
+        this.random = opts.random ?? Math.random;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.record = opts.record ?? readRecorderRecord;
+        this.alive = opts.alive ?? pidAlive;
+        this.installed = opts.installed ?? projectInstalled;
+        this.launch = opts.launch ?? launchRevive;
+        this.sleep = opts.sleep ?? unrefSleep;
+        this.env = opts.env ?? process.env;
+        this.reviveFrom = this.now() + Math.max(0, opts.reviveGraceMs ?? REVIVE_GRACE_MS);
+    }
+    /** Watch the discovery file every {@link WATCH_EVERY_MS}, on a timer that never keeps the process alive. */
+    start(everyMs = WATCH_EVERY_MS) {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => void this.tick(), everyMs);
+        this.timer.unref();
+    }
+    /** The host is gone: nothing more is sent or started. */
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * Tell the recorder what this server lists, now — or, while a hello is in
+     * flight, as soon as it ends. Returns at once; never throws.
+     */
+    hello(why) {
+        if (this.stopped)
+            return;
+        if (this.helloBusy) {
+            this.helloOwed = why;
+            return;
+        }
+        this.helloBusy = true;
+        // On the next turn of the loop: the answer this follows goes out first,
+        // and not even reading the discovery file happens before it.
+        setImmediate(() => void this.sendHello(why));
+    }
+    /**
+     * Something on the MCP path found no recorder (`run_scenario` found no live
+     * discovery file, or its request was refused): look now rather than at the
+     * next tick. Returns at once; never throws.
+     */
+    recorderGone(why) {
+        if (this.stopped)
+            return;
+        setImmediate(() => void this.checkRevive(why));
+    }
+    /** One look at the discovery file. Exposed for tests; never throws. */
+    async tick() {
+        if (this.stopped)
+            return;
+        try {
+            const rec = this.record(this.cwd);
+            if (rec && !this.alive(rec.pid)) {
+                await this.checkRevive("the recorder's pid is gone");
+                return;
+            }
+            if (rec)
+                this.recorderSeenAlive();
+            const target = this.target();
+            if (!target)
+                return;
+            const now = this.now();
+            if (target.identity !== this.tried) {
+                this.hello("recorder");
+                return;
+            }
+            if (now < this.helloNotBefore)
+                return;
+            if (target.identity !== this.reached || now - this.lastHelloAt >= HELLO_EVERY_MS) {
+                this.hello(target.identity !== this.reached ? "retry" : "periodic");
+            }
+        }
+        catch (err) {
+            logDetail("scenario.liveness_failed", { error: errText(err) });
+        }
+    }
+    /**
+     * Where a hello goes, the way `run_scenario`'s request does: `BIR_CONTROL_URL`
+     * (with `BIR_CONTROL_TOKEN`, or the discovery file's token), else the
+     * discovery file — whose pid must be alive.
+     */
+    target() {
+        const rec = this.record(this.cwd);
+        const live = rec && this.alive(rec.pid) ? rec : undefined;
+        const envUrl = this.env.BIR_CONTROL_URL?.trim();
+        if (envUrl) {
+            const token = this.env.BIR_CONTROL_TOKEN || live?.token;
+            if (!token)
+                return undefined;
+            return { url: trimUrl(envUrl), token, identity: `${trimUrl(envUrl)}#${live?.pid ?? 0}` };
+        }
+        if (!live)
+            return undefined;
+        return { url: trimUrl(live.url), token: live.token, identity: `${trimUrl(live.url)}#${live.pid}` };
+    }
+    state() {
+        try {
+            const s = this.opts.state();
+            return { tools: Number.isInteger(s.tools) && s.tools >= 0 ? s.tools : 0, off: s.off === true };
+        }
+        catch {
+            return { tools: 0, off: false };
+        }
+    }
+    async sendHello(why) {
+        this.helloBusy = true;
+        try {
+            if (this.stopped)
+                return;
+            // No recorder yet (the host often starts this server before SessionStart
+            // starts the recorder): the watch says hello when one appears.
+            const target = this.target();
+            if (!target)
+                return;
+            const { tools, off } = this.state();
+            const body = { pid: process.pid, version: packageVersion(), tools, off };
+            this.tried = target.identity;
+            this.lastHelloAt = this.now();
+            let reach;
+            let status;
+            try {
+                const res = await this.fetchImpl(`${target.url}/scenario/hello`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${target.token}` },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(HELLO_TIMEOUT_MS),
+                });
+                status = res.status;
+                // The answer is `{ok:true}` and nothing here needs it; read it so the
+                // connection can be reused, within the same bound.
+                await res.arrayBuffer().catch(() => undefined);
+                reach = "answered";
+            }
+            catch (err) {
+                reach = reachOf(err);
+            }
+            if (reach === "answered") {
+                this.reached = target.identity;
+                this.hellos += 1;
+                this.helloFailures = 0;
+                this.helloNotBefore = 0;
+                // A recorder from before this route answers 404: it does not ask for
+                // hellos, so there is nothing to retry until it is replaced.
+                logDetail("scenario.hello", { why, tools, off, status });
+                return;
+            }
+            this.helloFailures += 1;
+            this.helloNotBefore =
+                this.now() + Math.min(WATCH_EVERY_MS * 2 ** Math.min(this.helloFailures - 1, 10), HELLO_RETRY_MAX_MS);
+            logDetail("scenario.hello_failed", { why, reach });
+            if (reach === "refused")
+                this.recorderGone("the recorder refused a hello");
+        }
+        catch (err) {
+            logDetail("scenario.hello_failed", { why, error: errText(err) });
+        }
+        finally {
+            this.helloBusy = false;
+            const owed = this.helloOwed;
+            this.helloOwed = undefined;
+            if (owed !== undefined && !this.stopped)
+                this.hello(owed);
+        }
+    }
+    /** Whether anything listens at `url`: only a refused connection counts as nothing. */
+    async probe(url) {
+        try {
+            const res = await this.fetchImpl(`${trimUrl(url)}/health`, { signal: AbortSignal.timeout(REFUSED_PROBE_MS) });
+            await res.arrayBuffer().catch(() => undefined);
+            return "answered";
+        }
+        catch (err) {
+            return reachOf(err);
+        }
+    }
+    /**
+     * A recorder is up: the revives before it helped (or were not needed), so the
+     * next death waits the plain {@link REVIVE_EVERY_MS} since the last one, not
+     * a doubled wait.
+     */
+    recorderSeenAlive() {
+        if (this.revivesInARow === 0)
+            return;
+        this.revivesInARow = 0;
+        this.reviveNotBefore = Math.min(this.reviveNotBefore, this.lastReviveAt + REVIVE_EVERY_MS);
+    }
+    /** Start a revive if — and only if — the recorder is dead, refused and this project's. */
+    async checkRevive(why) {
+        if (this.stopped || this.reviveBusy)
+            return;
+        const now = this.now();
+        if (now < this.reviveNotBefore || now < this.reviveFrom)
+            return;
+        this.reviveBusy = true;
+        try {
+            // Every process of the session sees the same death at about the same
+            // moment. Each waits a moment of its own and looks again: whoever went
+            // first has usually brought a recorder back by then.
+            const wait = Math.floor(Math.max(0, Math.min(1, this.random())) * REVIVE_JITTER_MS);
+            if (wait > 0)
+                await this.sleep(wait);
+            if (this.stopped)
+                return;
+            const rec = this.record(this.cwd);
+            // No record: `bir down` removed it (stopped on purpose, so it stays
+            // stopped), or no recorder ever ran here. A live pid: busy, or back.
+            if (!rec)
+                return;
+            if (this.alive(rec.pid)) {
+                this.recorderSeenAlive();
+                return;
+            }
+            const every = Math.min(REVIVE_EVERY_MS * 2 ** Math.min(this.revivesInARow, 10), REVIVE_MAX_EVERY_MS);
+            this.reviveNotBefore = this.now() + every;
+            if (!this.installed(this.cwd))
+                return;
+            const reach = await this.probe(rec.url);
+            // Something answers there (a recorder that has not rewritten the file
+            // yet), or it is slow to: not ours to replace.
+            if (reach !== "refused" || this.stopped)
+                return;
+            logLine("scenario.recorder_revive", {
+                pid: rec.pid,
+                url: rec.url,
+                why,
+                detail: "the project's recorder is gone mid-session; starting it again so its hooks answer",
+            });
+            this.revives += 1;
+            this.revivesInARow += 1;
+            this.lastReviveAt = this.now();
+            await this.launch(this.cwd);
+        }
+        catch (err) {
+            logLine("scenario.revive_failed", { error: errText(err) });
+        }
+        finally {
+            this.reviveBusy = false;
+        }
+    }
+}
+//# sourceMappingURL=scenario-liveness.js.map