@basein/runner 0.2.11 → 0.3.0

package/dist/util/journal.js

@@ -15,9 +15,10 @@
  * the reason a hook fails (design §1, rule 4), and a hook's answer must not
  * race the line that explains it.
  */
-import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { controlDir, controlKey, ensureDir } from "../control/paths.js";
+import { writeFileAtomic } from "./atomic-write.js";
 /** Events worth keeping: the run boundaries, every replay decision, the money. */
 const JOURNALED_PREFIXES = ["run.", "replay.", "plan.", "execution."];
 const JOURNALED_EVENTS = new Set(["session.start", "control.listening", "proxy.registered"]);
@@ -25,6 +26,14 @@ export function isJournaled(event) {
     return JOURNALED_EVENTS.has(event) || JOURNALED_PREFIXES.some((p) => event.startsWith(p));
 }
 export const JOURNAL_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * The longest string one journal field keeps. The journal explains decisions;
+ * a field that carries a whole error page or a pasted log would spend the
+ * 4 MB budget on one line and rotate the useful ones out.
+ */
+export const JOURNAL_FIELD_MAX_CHARS = 4_000;
+/** A journal nobody has written to for this long belongs to a project that is gone. */
+export const JOURNAL_STALE_MS = 30 * 24 * 60 * 60 * 1000;
 export function journalPath(cwd) {
     return join(controlDir(), "journal", `${controlKey(cwd)}.jsonl`);
 }
@@ -34,8 +43,40 @@ export function openJournal(cwd) {
     const path = journalPath(cwd);
     ensureDir(dirname(path));
     current = path;
+    pruneStaleJournals(dirname(path), path);
     return path;
 }
+/**
+ * Delete other projects' journals untouched for {@link JOURNAL_STALE_MS}.
+ * One file per directory ever recorded in, each up to 4 MB, never pruned, is
+ * how a year of throwaway checkouts becomes a gigabyte nobody asked for.
+ * Best-effort, and never the open file.
+ */
+export function pruneStaleJournals(dir, keep, now = Date.now()) {
+    let removed = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith(".jsonl"))
+                continue;
+            const file = join(dir, name);
+            if (file === keep)
+                continue;
+            try {
+                if (now - statSync(file).mtimeMs > JOURNAL_STALE_MS) {
+                    unlinkSync(file);
+                    removed += 1;
+                }
+            }
+            catch {
+                /* in use, or already gone */
+            }
+        }
+    }
+    catch {
+        /* no directory yet */
+    }
+    return removed;
+}
 export function closeJournal() {
     current = undefined;
 }
@@ -51,7 +92,10 @@ export function journal(event, fields = {}) {
     for (const [key, value] of Object.entries(fields)) {
         if (value === undefined || value === null)
             continue;
-        entry[key] = value;
+        entry[key] =
+            typeof value === "string" && value.length > JOURNAL_FIELD_MAX_CHARS
+                ? `${value.slice(0, JOURNAL_FIELD_MAX_CHARS)}…(+${value.length - JOURNAL_FIELD_MAX_CHARS} chars)`
+                : value;
     }
     try {
         appendFileSync(current, `${JSON.stringify(entry)}\n`);
@@ -73,7 +117,8 @@ function rotate(path) {
         return;
     const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
     const keep = lines.slice(Math.floor(lines.length / 2));
-    writeFileSync(path, keep.length ? `${keep.join("\n")}\n` : "");
+    // Atomic: `bir investigate` may be reading the file while a hook rotates it.
+    writeFileAtomic(path, keep.length ? `${keep.join("\n")}\n` : "");
 }
 /** Every entry in a journal file, oldest first. A malformed line is skipped, not fatal. */
 export function readJournal(path) {

package/dist/util/log.d.ts

@@ -18,10 +18,20 @@ export declare const VERBOSE: boolean;
  * session: the audit log is the only record of what the recorder decided.
  */
 export declare const QUIET: boolean;
+/**
+ * The longest value one field may print. An audit line is for a person reading
+ * a log, and one field that carries a whole HTML error page per failed step
+ * buries every other line during exactly the incident someone is reading it
+ * for. The cut is marked, never silent.
+ */
+export declare const LOG_FIELD_MAX_CHARS = 2000;
+/** Clip one field's text for a log line. */
+export declare function clipField(text: string, max?: number): string;
 /** Print one audit line: `[bir] <iso ts> <event> key=value …`. */
 export declare function logLine(event: string, fields?: Record<string, unknown>): void;
 /** A detail line, printed only under `BIR_VERBOSE=1`. */
 export declare function logDetail(event: string, fields?: Record<string, unknown>): void;
 export declare function logOnce(key: string, event: string, fields?: Record<string, unknown>): void;
+export declare function logEvery(key: string, intervalMs: number, event: string, fields?: Record<string, unknown>): boolean;
 export declare function errText(err: unknown): string;
 //# sourceMappingURL=log.d.ts.map

package/dist/util/log.js

@@ -19,6 +19,17 @@ export const VERBOSE = process.env.BIR_VERBOSE === "1";
  */
 export const QUIET = process.env.BIR_QUIET === "1";
 import { journal } from "./journal.js";
+/**
+ * The longest value one field may print. An audit line is for a person reading
+ * a log, and one field that carries a whole HTML error page per failed step
+ * buries every other line during exactly the incident someone is reading it
+ * for. The cut is marked, never silent.
+ */
+export const LOG_FIELD_MAX_CHARS = 2_000;
+/** Clip one field's text for a log line. */
+export function clipField(text, max = LOG_FIELD_MAX_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}…(+${text.length - max} chars)` : text;
+}
 /** Print one audit line: `[bir] <iso ts> <event> key=value …`. */
 export function logLine(event, fields = {}) {
     // The journal keeps the decision lines for `bir investigate` (journal.ts).
@@ -30,7 +41,7 @@ export function logLine(event, fields = {}) {
     for (const [key, value] of Object.entries(fields)) {
         if (value === undefined || value === null)
             continue;
-        const text = String(value);
+        const text = clipField(String(value));
         pairs.push(/[\s"]/.test(text) ? `${key}=${JSON.stringify(text)}` : `${key}=${text}`);
     }
     const line = `[bir] ${new Date().toISOString()} ${event}${pairs.length ? ` ${pairs.join(" ")}` : ""}`;
@@ -49,6 +60,22 @@ export function logOnce(key, event, fields = {}) {
     seen.add(key);
     logLine(event, fields);
 }
+/**
+ * Log at most once per `intervalMs` per `key`, saying how many were held back.
+ * For lines an outage would otherwise repeat on every tool call.
+ */
+const lastAt = new Map();
+export function logEvery(key, intervalMs, event, fields = {}) {
+    const now = Date.now();
+    const prev = lastAt.get(key);
+    if (prev && now - prev.at < intervalMs) {
+        prev.suppressed += 1;
+        return false;
+    }
+    lastAt.set(key, { at: now, suppressed: 0 });
+    logLine(event, prev?.suppressed ? { ...fields, suppressed: prev.suppressed } : fields);
+    return true;
+}
 export function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/util/off-switch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * off-switch — make the whole runner inert, instantly and reversibly.
+ *
+ * When a session misbehaves and the runner might be why — slow hooks during a
+ * service incident, a replay that did the wrong thing, support asking to rule
+ * it out — the user needs one switch that takes it out of the path *without*
+ * uninstalling, and without a restart of anything. Three spellings, checked in
+ * this order:
+ *
+ *   BIR_OFF=1                        in the environment: off (BIR_OFF=0: on,
+ *                                    whatever the files say — for debugging)
+ *   ~/.baseinstrunner/off            a file: off everywhere
+ *   ~/.baseinstrunner/off.d/<key>    a file: off for one project (`controlKey`)
+ *
+ * `bir off [--here]` and `bir on [--here]` write and remove the files.
+ *
+ * What "off" means to each part (each part owns the details):
+ *   - bir-proxy: a pure pipe to the real server — no recording, no schema
+ *     change, no control server.
+ *   - bir-hooks: every hook route answers `{}` at once, before touching the
+ *     service or the transcript. The recorder stays up so the hooks keep
+ *     getting that instant answer instead of a refused connection, which Claude
+ *     Code would show as a hook error.
+ *   - bir-scenario: lists no tools.
+ *
+ * The answer is cached for {@link CACHE_MS}, so a hook pays one `stat` a second
+ * at most, and a flip takes effect within a second.
+ */
+/** The global flag file. */
+export declare function offFlagPath(): string;
+/** The per-project flag file for `cwd`. */
+export declare function projectOffFlagPath(cwd: string): string;
+export type OffSource = "env" | "global" | "project";
+/**
+ * Why the runner is off for `cwd` (or globally, without one), or `null` when
+ * it is on. Never throws: an unreadable home directory means "on", because
+ * "off" must be something a user chose.
+ */
+export declare function offSource(cwd?: string): OffSource | null;
+/** True when the runner must stay out of the way for `cwd`. */
+export declare function isRunnerOff(cwd?: string): boolean;
+/** Write or remove a flag. `cwd` scopes it to one project. */
+export declare function setRunnerOff(off: boolean, cwd?: string): void;
+/** Tests only: forget cached answers. */
+export declare function clearOffCache(): void;
+//# sourceMappingURL=off-switch.d.ts.map

package/dist/util/off-switch.js

@@ -0,0 +1,91 @@
+/**
+ * off-switch — make the whole runner inert, instantly and reversibly.
+ *
+ * When a session misbehaves and the runner might be why — slow hooks during a
+ * service incident, a replay that did the wrong thing, support asking to rule
+ * it out — the user needs one switch that takes it out of the path *without*
+ * uninstalling, and without a restart of anything. Three spellings, checked in
+ * this order:
+ *
+ *   BIR_OFF=1                        in the environment: off (BIR_OFF=0: on,
+ *                                    whatever the files say — for debugging)
+ *   ~/.baseinstrunner/off            a file: off everywhere
+ *   ~/.baseinstrunner/off.d/<key>    a file: off for one project (`controlKey`)
+ *
+ * `bir off [--here]` and `bir on [--here]` write and remove the files.
+ *
+ * What "off" means to each part (each part owns the details):
+ *   - bir-proxy: a pure pipe to the real server — no recording, no schema
+ *     change, no control server.
+ *   - bir-hooks: every hook route answers `{}` at once, before touching the
+ *     service or the transcript. The recorder stays up so the hooks keep
+ *     getting that instant answer instead of a refused connection, which Claude
+ *     Code would show as a hook error.
+ *   - bir-scenario: lists no tools.
+ *
+ * The answer is cached for {@link CACHE_MS}, so a hook pays one `stat` a second
+ * at most, and a flip takes effect within a second.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, controlKey } from "../control/paths.js";
+const CACHE_MS = 1_000;
+/** The global flag file. */
+export function offFlagPath() {
+    return join(configDir(), "off");
+}
+/** The per-project flag file for `cwd`. */
+export function projectOffFlagPath(cwd) {
+    return join(configDir(), "off.d", controlKey(cwd));
+}
+const cache = new Map();
+/**
+ * Why the runner is off for `cwd` (or globally, without one), or `null` when
+ * it is on. Never throws: an unreadable home directory means "on", because
+ * "off" must be something a user chose.
+ */
+export function offSource(cwd) {
+    const env = process.env.BIR_OFF;
+    if (env === "1" || env === "true")
+        return "env";
+    if (env === "0" || env === "false")
+        return null;
+    const key = cwd ?? "";
+    const now = Date.now();
+    const hit = cache.get(key);
+    if (hit && now - hit.at < CACHE_MS)
+        return hit.source;
+    let source = null;
+    try {
+        if (existsSync(offFlagPath()))
+            source = "global";
+        else if (cwd && existsSync(projectOffFlagPath(cwd)))
+            source = "project";
+    }
+    catch {
+        source = null;
+    }
+    cache.set(key, { at: now, source });
+    return source;
+}
+/** True when the runner must stay out of the way for `cwd`. */
+export function isRunnerOff(cwd) {
+    return offSource(cwd) !== null;
+}
+/** Write or remove a flag. `cwd` scopes it to one project. */
+export function setRunnerOff(off, cwd) {
+    const path = cwd ? projectOffFlagPath(cwd) : offFlagPath();
+    if (off) {
+        mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${new Date().toISOString()}\n`, { mode: 0o600 });
+    }
+    else {
+        rmSync(path, { force: true });
+    }
+    cache.clear();
+}
+/** Tests only: forget cached answers. */
+export function clearOffCache() {
+    cache.clear();
+}
+//# sourceMappingURL=off-switch.js.map

package/dist/util/service-health.d.ts

@@ -0,0 +1,133 @@
+/**
+ * service-health — one process-wide answer to "is the BaseIn service answering?"
+ *
+ * The runner's first rule (§1 goal 4) is that it is never the reason a session
+ * is slow or broken. The service is the one dependency that can break that rule
+ * without anything here being wrong: a blackholed host, a captive portal, a
+ * degraded API or a 30 s gateway timeout all turn every hook that *waits* for it
+ * into seconds of dead air, on every prompt and every tool call, for as long as
+ * the incident lasts.
+ *
+ * So waiting is a privilege the service earns by answering. Every service call
+ * reports here — {@link ServiceHealth.ok} on an answer, {@link ServiceHealth.fail}
+ * on a network error, a timeout, a 5xx, a 429 or a body that is not the API's —
+ * and every hot path asks {@link ServiceHealth.canWait} before it awaits one.
+ * After a failure the answer is "no" for a cool-down that doubles on each
+ * further failure (up to {@link MAX_COOLDOWN_MS}), so a dead service costs a
+ * hook one budget per cool-down at most, and usually nothing: background sends
+ * keep reporting, and they fail first. One answer closes it again — except the
+ * late answer of a request that was already running when a hot path gave up on
+ * the service ({@link ServiceHealth.slow}): that is the slowness, arriving,
+ * not a recovery.
+ *
+ * Nothing here retries or queues. It is a verdict, not a transport.
+ */
+/** First cool-down after a failure. Doubles per consecutive failure. */
+export declare const BASE_COOLDOWN_MS = 5000;
+/** The cool-down never grows past this, so recovery is noticed within a minute. */
+export declare const MAX_COOLDOWN_MS = 60000;
+/**
+ * Default ceiling for one service request made off the hot path (a step
+ * upload, a refresh, a finish). `BIR_SERVICE_TIMEOUT_MS` overrides it.
+ *
+ * Without one, Node's fetch waits out the OS connect timeout on a blackholed
+ * host (10-20 s, 75 s on some systems) and up to 300 s on a server that accepts
+ * and never answers, holding a socket and a chain slot the whole time.
+ */
+export declare const DEFAULT_SERVICE_TIMEOUT_MS = 10000;
+export declare function serviceTimeoutMs(): number;
+export interface HealthSnapshot {
+    /** False while a cool-down is running: hot paths do not wait. */
+    healthy: boolean;
+    consecutiveFailures: number;
+    /** Epoch ms the cool-down ends, when one is running. */
+    openUntil?: number;
+    lastError?: string;
+    lastErrorAt?: number;
+    lastOkAt?: number;
+}
+export interface ServiceHealthOptions {
+    baseCooldownMs?: number;
+    maxCooldownMs?: number;
+    /** Injected by tests. */
+    now?: () => number;
+}
+export declare class ServiceHealth {
+    private failures;
+    private openUntil;
+    /** When a hot path last gave up waiting ({@link slow}); 0 = never. */
+    private slowMark;
+    private lastError?;
+    private lastErrorAt?;
+    private lastOkAt?;
+    private readonly baseCooldownMs;
+    private readonly maxCooldownMs;
+    private readonly now;
+    constructor(opts?: ServiceHealthOptions);
+    /**
+     * May a hot path (a hook the user is waiting on) wait for the service now?
+     *
+     * False during a cool-down. After one ends the service is half-open: the next
+     * request finds out, and a failure then starts a longer cool-down. Electing
+     * that one request is the caller's business: RemoteRecorder sends one probe
+     * for all its lanes, and its hook-facing calls ask for a background one
+     * rather than probing themselves.
+     */
+    canWait(): boolean;
+    /** This verdict's clock, for {@link ok}'s `startedAt`. */
+    stamp(): number;
+    /** The first cool-down, for callers that scale their own pauses to it. */
+    get baseCooldown(): number;
+    /**
+     * The service answered. Closes any cool-down — unless `startedAt` (the
+     * {@link stamp} when the request that answered was sent) is before the last
+     * {@link slow} mark: a request already in flight when a hook gave up on the
+     * service answering late is the overrun itself, and closing on it made every
+     * next hook wait again. A request sent after the mark closes it as usual, and
+     * so does any answer after a `fail()` that no `slow()` followed. Without
+     * `startedAt` the answer closes it, as before.
+     */
+    ok(startedAt?: number): void;
+    /** The service failed to answer usefully. Starts (or extends) a cool-down. */
+    fail(reason: string): void;
+    /**
+     * A hot path gave up waiting on its budget. Counts as a failure, and marks
+     * the moment: an answer to a request sent before it does not end the
+     * cool-down ({@link ok}).
+     */
+    slow(what: string): void;
+    snapshot(): HealthSnapshot;
+    /** Tests only. */
+    reset(): void;
+}
+/** The process-wide instance every service caller reports to. */
+export declare const serviceHealth: ServiceHealth;
+/**
+ * Is this HTTP status the service being unwell, rather than answering "no"?
+ * 5xx, 408 and 429 are; a 4xx such as 401 or 404 is an answer.
+ */
+export declare function isUnhealthyStatus(status: number): boolean;
+/**
+ * Wait for `pending` on a hot path, but never longer than `budgetMs`, and not
+ * at all while the service is in a cool-down.
+ *
+ * Resolves `undefined` when it did not wait or the budget ran out; `pending`
+ * keeps running in the background (its rejection is observed here, so it can
+ * never become an unhandled rejection). A budget overrun is reported to
+ * `health` as a slow call, which is what makes the *next* hook free.
+ *
+ * `pending` should itself report `ok`/`fail` when it settles (RemoteRecorder
+ * does, with the time it sent the request, so its own late answer does not
+ * undo the overrun); this only adds the verdict a caller who stopped waiting
+ * can give.
+ */
+export declare function awaitWithin<T>(pending: Promise<T>, budgetMs: number, what: string, health?: ServiceHealth): Promise<T | undefined>;
+/**
+ * An AbortSignal that fires after `ms`, or when `parent` does.
+ *
+ * `AbortSignal.any` is Node 20.3+, and `engines` says 20, so this composes the
+ * two by hand. The timer is unref'd: a pending request must never be what
+ * keeps a process alive.
+ */
+export declare function timeoutSignal(ms?: number, parent?: AbortSignal): AbortSignal;
+//# sourceMappingURL=service-health.d.ts.map

package/dist/util/service-health.js

@@ -0,0 +1,217 @@
+/**
+ * service-health — one process-wide answer to "is the BaseIn service answering?"
+ *
+ * The runner's first rule (§1 goal 4) is that it is never the reason a session
+ * is slow or broken. The service is the one dependency that can break that rule
+ * without anything here being wrong: a blackholed host, a captive portal, a
+ * degraded API or a 30 s gateway timeout all turn every hook that *waits* for it
+ * into seconds of dead air, on every prompt and every tool call, for as long as
+ * the incident lasts.
+ *
+ * So waiting is a privilege the service earns by answering. Every service call
+ * reports here — {@link ServiceHealth.ok} on an answer, {@link ServiceHealth.fail}
+ * on a network error, a timeout, a 5xx, a 429 or a body that is not the API's —
+ * and every hot path asks {@link ServiceHealth.canWait} before it awaits one.
+ * After a failure the answer is "no" for a cool-down that doubles on each
+ * further failure (up to {@link MAX_COOLDOWN_MS}), so a dead service costs a
+ * hook one budget per cool-down at most, and usually nothing: background sends
+ * keep reporting, and they fail first. One answer closes it again — except the
+ * late answer of a request that was already running when a hot path gave up on
+ * the service ({@link ServiceHealth.slow}): that is the slowness, arriving,
+ * not a recovery.
+ *
+ * Nothing here retries or queues. It is a verdict, not a transport.
+ */
+import { logLine } from "./log.js";
+/** First cool-down after a failure. Doubles per consecutive failure. */
+export const BASE_COOLDOWN_MS = 5_000;
+/** The cool-down never grows past this, so recovery is noticed within a minute. */
+export const MAX_COOLDOWN_MS = 60_000;
+/**
+ * Default ceiling for one service request made off the hot path (a step
+ * upload, a refresh, a finish). `BIR_SERVICE_TIMEOUT_MS` overrides it.
+ *
+ * Without one, Node's fetch waits out the OS connect timeout on a blackholed
+ * host (10-20 s, 75 s on some systems) and up to 300 s on a server that accepts
+ * and never answers, holding a socket and a chain slot the whole time.
+ */
+export const DEFAULT_SERVICE_TIMEOUT_MS = 10_000;
+export function serviceTimeoutMs() {
+    const n = Number(process.env.BIR_SERVICE_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SERVICE_TIMEOUT_MS;
+}
+export class ServiceHealth {
+    failures = 0;
+    openUntil = 0;
+    /** When a hot path last gave up waiting ({@link slow}); 0 = never. */
+    slowMark = 0;
+    lastError;
+    lastErrorAt;
+    lastOkAt;
+    baseCooldownMs;
+    maxCooldownMs;
+    now;
+    constructor(opts = {}) {
+        this.baseCooldownMs = opts.baseCooldownMs ?? BASE_COOLDOWN_MS;
+        this.maxCooldownMs = opts.maxCooldownMs ?? MAX_COOLDOWN_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * May a hot path (a hook the user is waiting on) wait for the service now?
+     *
+     * False during a cool-down. After one ends the service is half-open: the next
+     * request finds out, and a failure then starts a longer cool-down. Electing
+     * that one request is the caller's business: RemoteRecorder sends one probe
+     * for all its lanes, and its hook-facing calls ask for a background one
+     * rather than probing themselves.
+     */
+    canWait() {
+        return this.failures === 0 || this.now() >= this.openUntil;
+    }
+    /** This verdict's clock, for {@link ok}'s `startedAt`. */
+    stamp() {
+        return this.now();
+    }
+    /** The first cool-down, for callers that scale their own pauses to it. */
+    get baseCooldown() {
+        return this.baseCooldownMs;
+    }
+    /**
+     * The service answered. Closes any cool-down — unless `startedAt` (the
+     * {@link stamp} when the request that answered was sent) is before the last
+     * {@link slow} mark: a request already in flight when a hook gave up on the
+     * service answering late is the overrun itself, and closing on it made every
+     * next hook wait again. A request sent after the mark closes it as usual, and
+     * so does any answer after a `fail()` that no `slow()` followed. Without
+     * `startedAt` the answer closes it, as before.
+     */
+    ok(startedAt) {
+        const now = this.now();
+        if (startedAt !== undefined && this.failures > 0 && startedAt < this.slowMark) {
+            this.lastOkAt = now;
+            return;
+        }
+        if (this.failures > 0)
+            logLine("service.recovered", { after: this.failures });
+        this.failures = 0;
+        this.openUntil = 0;
+        this.lastOkAt = now;
+    }
+    /** The service failed to answer usefully. Starts (or extends) a cool-down. */
+    fail(reason) {
+        this.failures += 1;
+        const cooldown = Math.min(this.maxCooldownMs, this.baseCooldownMs * 2 ** Math.min(this.failures - 1, 16));
+        const now = this.now();
+        this.openUntil = Math.max(this.openUntil, now + cooldown);
+        this.lastError = reason.slice(0, 200);
+        this.lastErrorAt = now;
+        // Logged on the transition only: an outage must not write a line per step.
+        if (this.failures === 1)
+            logLine("service.degraded", { reason: this.lastError, cooldown_ms: cooldown });
+    }
+    /**
+     * A hot path gave up waiting on its budget. Counts as a failure, and marks
+     * the moment: an answer to a request sent before it does not end the
+     * cool-down ({@link ok}).
+     */
+    slow(what) {
+        this.slowMark = this.now();
+        this.fail(`slow:${what}`);
+    }
+    snapshot() {
+        return {
+            healthy: this.canWait(),
+            consecutiveFailures: this.failures,
+            ...(this.failures > 0 ? { openUntil: this.openUntil } : {}),
+            ...(this.lastError !== undefined ? { lastError: this.lastError, lastErrorAt: this.lastErrorAt } : {}),
+            ...(this.lastOkAt !== undefined ? { lastOkAt: this.lastOkAt } : {}),
+        };
+    }
+    /** Tests only. */
+    reset() {
+        this.failures = 0;
+        this.openUntil = 0;
+        this.slowMark = 0;
+        this.lastError = undefined;
+        this.lastErrorAt = undefined;
+        this.lastOkAt = undefined;
+    }
+}
+/** The process-wide instance every service caller reports to. */
+export const serviceHealth = new ServiceHealth();
+/**
+ * Is this HTTP status the service being unwell, rather than answering "no"?
+ * 5xx, 408 and 429 are; a 4xx such as 401 or 404 is an answer.
+ */
+export function isUnhealthyStatus(status) {
+    return status >= 500 || status === 408 || status === 429;
+}
+/**
+ * Wait for `pending` on a hot path, but never longer than `budgetMs`, and not
+ * at all while the service is in a cool-down.
+ *
+ * Resolves `undefined` when it did not wait or the budget ran out; `pending`
+ * keeps running in the background (its rejection is observed here, so it can
+ * never become an unhandled rejection). A budget overrun is reported to
+ * `health` as a slow call, which is what makes the *next* hook free.
+ *
+ * `pending` should itself report `ok`/`fail` when it settles (RemoteRecorder
+ * does, with the time it sent the request, so its own late answer does not
+ * undo the overrun); this only adds the verdict a caller who stopped waiting
+ * can give.
+ */
+export async function awaitWithin(pending, budgetMs, what, health = serviceHealth) {
+    pending.catch(() => undefined);
+    if (budgetMs <= 0 || !health.canWait())
+        return undefined;
+    let timer;
+    const timedOut = Symbol("timeout");
+    try {
+        const winner = await Promise.race([
+            pending,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(timedOut), budgetMs);
+                timer.unref?.();
+            }),
+        ]);
+        if (winner === timedOut) {
+            health.slow(what);
+            return undefined;
+        }
+        return winner;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * An AbortSignal that fires after `ms`, or when `parent` does.
+ *
+ * `AbortSignal.any` is Node 20.3+, and `engines` says 20, so this composes the
+ * two by hand. The timer is unref'd: a pending request must never be what
+ * keeps a process alive.
+ */
+export function timeoutSignal(ms = serviceTimeoutMs(), parent) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException(`timed out after ${ms} ms`, "TimeoutError")), ms);
+    timer.unref?.();
+    if (parent) {
+        if (parent.aborted) {
+            clearTimeout(timer);
+            controller.abort(parent.reason);
+        }
+        else {
+            parent.addEventListener("abort", () => {
+                clearTimeout(timer);
+                controller.abort(parent.reason);
+            }, { once: true });
+        }
+    }
+    controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+    return controller.signal;
+}
+//# sourceMappingURL=service-health.js.map