@basein/runner 0.2.11 → 0.3.0

package/dist/control/recorder-keeper.js

@@ -0,0 +1,721 @@
+/**
+ * recorder-keeper — the background recorder's sign-in, kept current without
+ * ever standing between Claude Code and a hook.
+ *
+ * WHAT WAS WRONG. `bir-hooks` used to settle its sign-in *before* it listened:
+ * a `GET /health` to check the address, then — whenever the access token had
+ * expired, which is every first session of the day — a `POST /auth/refresh`,
+ * neither with a timeout. A service that was slow, blackholed, or behind a
+ * proxy that accepts and never answers held the port closed for 10-300 s, and
+ * every hook of every session in that window was refused (Claude Code shows
+ * each as a hook error). Worse, a refresh that failed for *any* reason — the
+ * Wi-Fi not up yet after a wake — was read as "not signed in": the recorder
+ * built a `NullRecorder`, logged "run `bir login`", and recorded nothing for
+ * the rest of its life, which is days. Following that advice changed nothing.
+ *
+ * WHAT IT DOES NOW. The recorder is decided from disk alone — the stored
+ * address and credentials.json — so it exists before the port is bound, with
+ * no network at all. An expired access token is not a reason to stop: the
+ * `RemoteRecorder` refreshes on its first 401 and adopts a sibling's refresh.
+ * Then, in the background and bounded by timeouts, this keeper:
+ *
+ *   - refreshes the token a little before it expires (and right away when it
+ *     already has), so the first prompt of the day does not pay for it;
+ *   - notices a sign-in appearing, changing or being removed on disk — `bir
+ *     login`, `bir setup`, `bir logout`, a sibling's refresh — and swaps the
+ *     backend of the {@link SwitchableRecorder} the control server holds. No
+ *     restart. A signed-out recorder checks again the moment a prompt arrives,
+ *     so the prompt after `bir login` is already recorded;
+ *   - tells a *rejected* sign-in (the API answered 400/401/403 with its own
+ *     JSON error) from a *missing* service (no answer, a timeout, 5xx, 429, or
+ *     a page that is not the API — a WAF's or a captive portal's HTML 403 is
+ *     not a verdict on the sign-in). Only the first stops recording and says
+ *     "run `bir login`", and even then the refusal is asked once more half an
+ *     hour later before it is final; the second keeps the saved sign-in,
+ *     retries with backoff, and says so.
+ *
+ * NOTHING HERE IS ON A HOT PATH. Every network call is in a timer or behind a
+ * hook's answer, has a timeout, and reports to `serviceHealth`, so a hook that
+ * *does* wait for the service (a prompt match) knows not to while it is down.
+ * While the runner is switched off (`bir off`) the keeper makes no calls.
+ */
+import { existsSync, statSync } from "node:fs";
+import { credentialsPath, loadCredentials, normalizeAuthUrl, resolveAuthUrl, saveCredentials, } from "../auth/client.js";
+import { NullRecorder } from "../record/recorder.js";
+import { RemoteRecorder } from "../record/remote-recorder.js";
+import { SwitchableRecorder } from "../record/switchable-recorder.js";
+import { configPath } from "./paths.js";
+import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
+import { isRunnerOff } from "../util/off-switch.js";
+import { errText, logDetail, logLine } from "../util/log.js";
+/** What `authenticate()` hands out under `BIR_AUTH_DISABLE=1` (auth/client.ts). */
+const LOCAL_DEV_SESSION = {
+    accessToken: "local-dev",
+    refreshToken: "local-dev",
+    accessExpiresAt: Number.MAX_SAFE_INTEGER,
+    user: { id: "local", email: "local@baseinstrunner.dev", name: "Local Dev" },
+};
+/** Same margin as auth/client.ts: a token this close to expiry is treated as expired. */
+const EXPIRY_SKEW_MS = 30_000;
+/** How long the http→https check may take. One small GET. */
+const SETTLE_TIMEOUT_MS = 4_000;
+/** Longest wait between refresh attempts while the service does not answer. */
+const MAX_REFRESH_BACKOFF_MS = 10 * 60 * 1000;
+/** After a refusal, when the refresh is tried once more before the refusal is final. */
+const REJECT_RETRY_MS = 30 * 60 * 1000;
+/** The most of a 4xx body read to tell the API's refusal from somebody else's page. */
+const MAX_REFUSAL_BODY = 16 * 1024;
+function trimUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+function isValid(session, now) {
+    return session.accessExpiresAt - EXPIRY_SKEW_MS > now;
+}
+/**
+ * True for a plain-http address that is not this machine. Such an address may
+ * sit behind a TLS proxy that answers `308 → https`, and following that drops
+ * the bearer token (auth/client.ts, normalizeAuthUrl) — so nothing is sent to
+ * it until that has been checked. https needs no check, and a loopback address
+ * is neither redirected by a TLS front nor readable on the network.
+ */
+export function needsSettling(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:")
+        return false;
+    const host = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return !(host === "localhost" || host.endsWith(".localhost") || host === "::1" || /^127\./.test(host));
+}
+/**
+ * The address to use `session` against when `configured` is set, or undefined
+ * when it was issued by another service. `bir login` stores the address it
+ * settled, so an `http://host` configuration with an `https://host` session is
+ * the same service, already upgraded.
+ */
+function baseFor(configured, session) {
+    const base = trimUrl(configured);
+    if (!session.authUrl)
+        return base; // written before sessions were bound: trusted as before
+    const issuer = trimUrl(session.authUrl);
+    if (issuer === base)
+        return base;
+    try {
+        const from = new URL(base);
+        const to = new URL(issuer);
+        if (from.protocol === "http:" && to.protocol === "https:" && from.host === to.host)
+            return issuer;
+    }
+    catch {
+        /* not URLs: not the same service */
+    }
+    return undefined;
+}
+/**
+ * What the files on disk say the recorder should be. No network.
+ *
+ * `settled` maps a configured plain-http address to what its check found.
+ */
+export function decideFromDisk(settled = new Map()) {
+    const configured = resolveAuthUrl();
+    if (!configured)
+        return { state: "no_address" };
+    const effective = settled.get(configured) ?? configured;
+    if (process.env.BIR_AUTH_DISABLE === "1") {
+        return { state: "recording", baseUrl: effective, session: LOCAL_DEV_SESSION };
+    }
+    const cached = loadCredentials();
+    if (!cached)
+        return { state: "signed_out", baseUrl: effective };
+    const base = baseFor(effective, cached);
+    if (!base)
+        return { state: "other_service", baseUrl: effective, issuer: cached.authUrl };
+    return { state: "recording", baseUrl: base, session: cached };
+}
+/**
+ * Whether a 400/401/403 is the API refusing the token, rather than something
+ * in front of it (a WAF, a CDN's bot check, a hotel's captive portal, a
+ * corporate proxy) answering for it. The API answers with a JSON error object
+ * (`{"error":"invalid_grant"}`, docs/loginWeb.md); those others answer with an
+ * HTML page. Only a JSON object counts: taking a portal's "403 Forbidden"
+ * page for a refusal stopped recording for the recorder's whole life.
+ */
+async function isApiRefusal(res) {
+    const type = (res.headers.get("content-type") ?? "").toLowerCase();
+    if (type.includes("html")) {
+        await res.body?.cancel().catch(() => undefined);
+        return false;
+    }
+    let text;
+    try {
+        text = await res.text();
+    }
+    catch {
+        return false;
+    }
+    if (text.length > MAX_REFUSAL_BODY)
+        return false;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+function causeText(err) {
+    const e = err;
+    if (e?.name === "TimeoutError" || e?.name === "AbortError")
+        return "timed out";
+    return e?.cause?.code ?? e?.cause?.message ?? errText(err);
+}
+/**
+ * One `POST /auth/refresh`, bounded, reported to `serviceHealth`.
+ *
+ * `authenticate()` answers "no session" for every failure alike, which is what
+ * turned a network blip into "run `bir login`". This one says which it was.
+ */
+export async function refreshSession(baseUrl, session, fetchImpl = fetch, timeoutMs = serviceTimeoutMs(), now = Date.now) {
+    // When this attempt was sent: a late answer to a request that started before
+    // a hot path gave up on the service must not close that cool-down.
+    const started = serviceHealth.stamp();
+    let res;
+    try {
+        res = await fetchImpl(`${trimUrl(baseUrl)}/auth/refresh`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refreshToken: session.refreshToken }),
+            signal: timeoutSignal(timeoutMs),
+        });
+    }
+    catch (err) {
+        const reason = causeText(err);
+        serviceHealth.fail(`refresh: ${reason}`);
+        return { kind: "unreachable", reason };
+    }
+    if (isUnhealthyStatus(res.status)) {
+        await res.body?.cancel().catch(() => undefined);
+        serviceHealth.fail(`refresh: HTTP ${res.status}`);
+        return { kind: "unreachable", reason: `HTTP ${res.status}` };
+    }
+    if (res.status === 400 || res.status === 401 || res.status === 403) {
+        if (await isApiRefusal(res)) {
+            serviceHealth.ok(started);
+            return { kind: "rejected", status: res.status };
+        }
+        // Somebody else's page in the API's place: the service is not reachable
+        // from here right now, which says nothing about the saved sign-in.
+        serviceHealth.fail(`refresh: HTTP ${res.status} that is not the API's answer`);
+        return { kind: "unreachable", reason: `HTTP ${res.status}, not from the API` };
+    }
+    if (!res.ok) {
+        // A 404 or the like: an answer, but not the API's. Not a verdict on the sign-in.
+        await res.body?.cancel().catch(() => undefined);
+        serviceHealth.ok(started);
+        return { kind: "unreachable", reason: `HTTP ${res.status}` };
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch (err) {
+        serviceHealth.fail("refresh: the answer was not JSON");
+        return { kind: "unreachable", reason: `not JSON (${causeText(err)})` };
+    }
+    if (typeof body?.accessToken !== "string" ||
+        typeof body.refreshToken !== "string" ||
+        typeof body.expiresIn !== "number" ||
+        typeof body.user?.id !== "string") {
+        serviceHealth.fail("refresh: unexpected answer");
+        return { kind: "unreachable", reason: "unexpected answer" };
+    }
+    serviceHealth.ok(started);
+    return {
+        kind: "ok",
+        session: {
+            accessToken: body.accessToken,
+            refreshToken: body.refreshToken,
+            accessExpiresAt: now() + body.expiresIn * 1000,
+            user: body.user,
+            authUrl: trimUrl(baseUrl),
+        },
+    };
+}
+function fileStamp(path) {
+    try {
+        const s = statSync(path);
+        return `${s.mtimeMs}:${s.size}`;
+    }
+    catch {
+        return "-";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        t.unref?.();
+    });
+}
+export class RecorderKeeper {
+    recorder;
+    /**
+     * The one backend used whenever nothing is recorded. One per process, not
+     * one per sign-out: a `NullRecorder` numbers its runs itself, and a fresh
+     * one after every logout or settle handed out `run_local_1` again — two
+     * runs under one id in the journal `bir investigate` reads.
+     */
+    idle = new NullRecorder();
+    opts;
+    now;
+    fetchImpl;
+    stateNow;
+    /** The address and session the current backend was built from (when recording). */
+    baseUrl;
+    session;
+    /** The decision waiting for its plain-http address to be checked. */
+    pending;
+    /** configured http address → what the check found. */
+    settled = new Map();
+    settling;
+    diskStamp = "";
+    /** A refresh token the service refused; a file still holding it is not a sign-in. */
+    rejectedRefreshToken;
+    /** The refusal waiting for its one more try (see {@link RecorderKeeperOptions.rejectRetryMs}). */
+    refused;
+    nextRefreshAt = 0;
+    refreshFailures = 0;
+    lastRunStartedAt = 0;
+    ticking = false;
+    timers = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? Date.now;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.recorder = new SwitchableRecorder(this.idle, {
+            // Two `stat`s per prompt while nothing is recorded: the prompt right
+            // after `bir login` is the one that should be recorded.
+            beforeStartRunWhileIdle: () => this.checkDisk(),
+            onStartRun: () => {
+                this.lastRunStartedAt = this.now();
+            },
+            // Why nothing is sent, for `recorderHealth()` while the backend is idle.
+            // Settling has a sign-in and records from the moment the address
+            // answers, as `recording` below says too.
+            idleHealthState: () => this.stateNow === "rejected"
+                ? "auth_rejected"
+                : this.stateNow === "other_service"
+                    ? "other_service"
+                    : this.stateNow === "settling" || this.stateNow === "recording"
+                        ? "recording"
+                        : "signed_out",
+        });
+        this.stateNow = "no_address";
+        this.diskStamp = this.stamp();
+        const first = decideFromDisk(this.settled);
+        // Said once at start either way: which of the states this recorder is in.
+        if (first.state === "recording")
+            this.apply(first, "start");
+        else
+            this.goIdle(first, "start");
+    }
+    /** Why the recorder is or is not recording. */
+    get state() {
+        return this.stateNow;
+    }
+    /**
+     * What `/health` reports as `recording`. True while a plain-http address is
+     * being checked too: there is a sign-in, and recording starts the moment the
+     * address answers — a "no session" there would send people to `bir login`
+     * for nothing.
+     */
+    get recording() {
+        return this.stateNow === "recording" || this.stateNow === "settling";
+    }
+    /** The account recordings land in, for `/health`. */
+    get account() {
+        return this.recording ? (this.session ?? this.pending?.session)?.user.email : undefined;
+    }
+    /** The service address replay should call, while there is a session for it. */
+    get authUrl() {
+        return this.stateNow === "recording" ? this.baseUrl : undefined;
+    }
+    /** The live access token (C5): read on every use, never kept. */
+    currentAccessToken() {
+        return this.stateNow === "recording" ? this.recorder.currentAccessToken() : undefined;
+    }
+    /** Start the background checks. Timers are unref'd: they never keep the process up. */
+    start() {
+        const first = setTimeout(() => void this.tick(), this.opts.firstTickMs ?? 250);
+        first.unref?.();
+        const every = setInterval(() => void this.tick(), this.opts.tickMs ?? 60_000);
+        every.unref?.();
+        this.timers.push(first, every);
+    }
+    stop() {
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers = [];
+    }
+    /**
+     * One background pass: look at the files, check a plain-http address,
+     * refresh a token that is due. Never throws; never overlaps itself.
+     */
+    async tick() {
+        if (this.ticking)
+            return;
+        this.ticking = true;
+        try {
+            this.checkDisk();
+            if (isRunnerOff(this.opts.cwd))
+                return;
+            await this.settle();
+            await this.maybeRefresh();
+            await this.maybeRetryRefused();
+        }
+        catch (err) {
+            logLine("recorder.keeper_failed", { error: errText(err), why: "recording carries on as it was" });
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    /**
+     * Re-read the sign-in and the address if either file changed. Local and
+     * cheap: two `stat`s, and a read only when one of them moved.
+     */
+    checkDisk() {
+        const stamp = this.stamp();
+        if (stamp === this.diskStamp)
+            return;
+        // Present but unreadable is a write in progress (credentials are saved
+        // with a plain write) or a broken file: decide nothing now, look again.
+        if (existsSync(credentialsPath()) && !loadCredentials())
+            return;
+        this.diskStamp = stamp;
+        this.apply(decideFromDisk(this.settled), "disk");
+    }
+    // ── internals ───────────────────────────────────────────────────────────
+    stamp() {
+        return `${fileStamp(credentialsPath())}|${fileStamp(configPath())}`;
+    }
+    makeRemote(baseUrl, session) {
+        return this.opts.makeRemote
+            ? this.opts.makeRemote(baseUrl, session)
+            : new RemoteRecorder({ baseUrl, session });
+    }
+    /** Act on a decision: swap the backend when it changes what is recorded where. */
+    apply(d, cause) {
+        // A file that still holds the refresh token the service refused is not a
+        // sign-in to go back to; a new `bir login` writes a new one.
+        if (d.state === "recording" &&
+            d.session &&
+            this.rejectedRefreshToken !== undefined &&
+            d.session.refreshToken === this.rejectedRefreshToken &&
+            !isValid(d.session, this.now())) {
+            if (this.stateNow !== "rejected")
+                this.goIdle({ state: "rejected", baseUrl: d.baseUrl }, cause);
+            return;
+        }
+        if (d.state === "recording" && d.baseUrl && d.session) {
+            if (needsSettling(d.baseUrl) && !this.settled.has(d.baseUrl)) {
+                this.pending = d;
+                if (this.stateNow !== "settling") {
+                    this.recorder.switchTo(this.idle);
+                    this.stateNow = "settling";
+                    this.baseUrl = undefined;
+                    this.session = undefined;
+                    logLine("auth.settling", {
+                        service: d.baseUrl,
+                        user: d.session.user.email,
+                        why: "a plain-http address: checking it does not redirect to https before any token is sent to it",
+                    });
+                }
+                if (!isRunnerOff(this.opts.cwd))
+                    void this.settle();
+                return;
+            }
+            this.pending = undefined;
+            const same = this.stateNow === "recording" &&
+                this.baseUrl === d.baseUrl &&
+                this.session?.user.id === d.session.user.id;
+            if (same) {
+                const holding = this.recorder.currentAccessToken();
+                if (d.session.accessToken === holding) {
+                    this.session = d.session; // our own save, or the backend's: now we know its expiry
+                    return;
+                }
+                // A sibling (or `bir login` as the same person) wrote a newer token.
+                // Take it only if it is usable; the backend adopts on its own anyway.
+                if (!isValid(d.session, this.now()))
+                    return;
+                this.install(d.baseUrl, d.session);
+                logDetail("auth.adopted", { why: "a newer sign-in was saved by another process" });
+                return;
+            }
+            const was = this.stateNow;
+            this.install(d.baseUrl, d.session);
+            const expired = !isValid(d.session, this.now());
+            if (cause === "start" || was === "settling") {
+                logLine("auth.ok", {
+                    user: d.session.user.email,
+                    service: d.baseUrl,
+                    token: expired ? "expired — refreshed in the background, no wait" : "valid",
+                });
+            }
+            else {
+                logLine("recorder.enabled", {
+                    user: d.session.user.email,
+                    service: d.baseUrl,
+                    why: was === "recording"
+                        ? "the saved sign-in changed — recording goes to it from the next prompt"
+                        : "a sign-in appeared — recording from the next prompt, no restart needed",
+                });
+            }
+            return;
+        }
+        this.pending = undefined;
+        if (d.state === this.stateNow && this.stateNow !== "recording")
+            return;
+        this.goIdle(d, cause);
+    }
+    install(baseUrl, session) {
+        this.recorder.switchTo(this.makeRemote(baseUrl, session));
+        this.stateNow = "recording";
+        this.baseUrl = baseUrl;
+        this.session = session;
+        this.rejectedRefreshToken = undefined;
+        this.refused = undefined;
+        this.nextRefreshAt = 0;
+        this.refreshFailures = 0;
+    }
+    goIdle(d, cause) {
+        const was = this.stateNow;
+        this.recorder.switchTo(this.idle);
+        this.stateNow = d.state;
+        if (d.state !== "rejected")
+            this.refused = undefined;
+        this.baseUrl = undefined;
+        this.session = undefined;
+        const why = this.explain(d);
+        if (was === "recording" && cause !== "start") {
+            logLine("recorder.signed_out", { why });
+        }
+        else {
+            logLine("recorder.disabled", { why });
+        }
+    }
+    explain(d) {
+        const later = "recording starts by itself after that — no restart needed";
+        switch (d.state) {
+            case "no_address":
+                return `no service address — run \`bir setup\` (or set BIR_AUTH_URL); ${later}`;
+            case "signed_out":
+                return `not signed in — run \`bir login\`; ${later}`;
+            case "other_service":
+                return `the saved sign-in was issued by ${d.issuer ?? "another service"}, not ${d.baseUrl ?? "this one"} — run \`bir setup\` (or \`bir login\`) here; ${later}`;
+            case "rejected":
+                return `the service refused the saved sign-in — run \`bir login\`; ${later}`;
+            default:
+                return "not recording";
+        }
+    }
+    /**
+     * Check a plain-http address for an https redirect, once it answers. Until
+     * then nothing is sent to it: a token sent before the check could go out in
+     * the clear to a host that would have redirected it.
+     */
+    settle() {
+        const d = this.pending;
+        if (!d?.baseUrl || this.settled.has(d.baseUrl))
+            return Promise.resolve();
+        if (this.settling)
+            return this.settling;
+        const configured = d.baseUrl;
+        this.settling = (async () => {
+            let answered = false;
+            const probe = async (input, init) => {
+                const res = await this.fetchImpl(input, { ...init, signal: timeoutSignal(SETTLE_TIMEOUT_MS) });
+                answered = true;
+                return res;
+            };
+            const upgraded = await normalizeAuthUrl(configured, probe);
+            if (!answered) {
+                logDetail("auth.settle_deferred", { service: configured, why: "no answer yet; checking again later" });
+                return;
+            }
+            this.settled.set(configured, upgraded);
+            this.apply(decideFromDisk(this.settled), "settled");
+        })()
+            .catch((err) => logDetail("auth.settle_failed", { error: errText(err) }))
+            .finally(() => {
+            this.settling = undefined;
+        });
+        return this.settling;
+    }
+    /** Refresh the access token when it is due, telling a refusal from an outage. */
+    async maybeRefresh() {
+        if (this.stateNow !== "recording" || !this.baseUrl || !this.session)
+            return;
+        if (process.env.BIR_AUTH_DISABLE === "1")
+            return;
+        const now = this.now();
+        if (now < this.nextRefreshAt)
+            return;
+        // Which token does the backend hold, and when does it expire? Ours — or
+        // the file's, when the backend refreshed on its own and saved it.
+        let session = this.session;
+        const holding = this.recorder.currentAccessToken();
+        if (holding !== session.accessToken) {
+            const file = loadCredentials();
+            if (!file || file.accessToken !== holding)
+                return; // it manages its own
+            session = file;
+            this.session = file;
+        }
+        if (session.accessExpiresAt - (this.opts.refreshAheadMs ?? 10 * 60 * 1000) > now)
+            return;
+        const expired = !isValid(session, now);
+        if (expired && now - this.lastRunStartedAt < (this.opts.quietMs ?? 20_000))
+            return;
+        const baseUrl = this.baseUrl;
+        const outcome = await refreshSession(baseUrl, session, this.fetchImpl, serviceTimeoutMs(), this.now);
+        if (outcome.kind === "ok") {
+            // The service has rotated the refresh token: the one on disk is dead now.
+            const saved = this.saveRefreshed(session, outcome.session);
+            // The world may have moved while we waited (a logout, a new sign-in).
+            if (this.stateNow !== "recording" || this.baseUrl !== baseUrl)
+                return;
+            if (saved === "not_ours") {
+                // The file no longer holds the token this refresh spent: `bir logout`
+                // removed it, or `bir login` (as anyone) replaced it, while the
+                // request was out. What is on disk decides, not this answer — installing
+                // it recorded the next prompts to the account just left.
+                this.decideFromDiskNow();
+                return;
+            }
+            if (this.refreshFailures > 0)
+                logLine("auth.recovered", { after: this.refreshFailures });
+            this.install(baseUrl, outcome.session);
+            logDetail("auth.refreshed", { user: outcome.session.user.email });
+            return;
+        }
+        if (this.stateNow !== "recording" || this.baseUrl !== baseUrl)
+            return;
+        if (outcome.kind === "rejected") {
+            // Rotating refresh tokens: the process that beat us to it has already
+            // written a good one. Look before concluding anything.
+            await sleep(this.opts.rejectRecheckMs ?? 1_000);
+            const fresh = decideFromDisk(this.settled);
+            if (fresh.state === "recording" &&
+                fresh.baseUrl &&
+                fresh.session &&
+                fresh.session.refreshToken !== session.refreshToken) {
+                this.install(fresh.baseUrl, fresh.session);
+                this.diskStamp = this.stamp();
+                logDetail("auth.adopted", { why: "another process refreshed first" });
+                return;
+            }
+            if (isValid(session, this.now())) {
+                // Still usable for a while; ask again when it expires rather than stop now.
+                this.nextRefreshAt = session.accessExpiresAt - EXPIRY_SKEW_MS;
+                logLine("auth.refresh_refused", {
+                    status: outcome.status,
+                    why: "the service refused the refresh; recording continues until the current token expires",
+                });
+                return;
+            }
+            this.rejectedRefreshToken = session.refreshToken;
+            this.goIdle({ state: "rejected", baseUrl }, "refresh");
+            this.refused = { baseUrl, session, at: this.now(), final: false };
+            return;
+        }
+        // No answer. Not a verdict on the sign-in: keep it and try again later.
+        this.refreshFailures += 1;
+        const backoff = Math.min(MAX_REFRESH_BACKOFF_MS, 30_000 * 2 ** Math.min(this.refreshFailures - 1, 10));
+        this.nextRefreshAt = this.now() + backoff;
+        if (this.refreshFailures === 1) {
+            logLine("auth.refresh_deferred", {
+                reason: outcome.reason,
+                retry_s: Math.round(backoff / 1000),
+                why: "the service did not answer — still recording with the saved sign-in, and retrying; nothing to do",
+            });
+        }
+    }
+    /**
+     * Save a rotated session whatever happened meanwhile — the service has spent
+     * the refresh token on disk — unless the file no longer holds the one spent
+     * (a logout removed it, or a new sign-in replaced it), which is not ours to
+     * overwrite.
+     */
+    saveRefreshed(spent, fresh) {
+        const onDisk = loadCredentials();
+        if (!onDisk || onDisk.refreshToken !== spent.refreshToken)
+            return "not_ours";
+        try {
+            saveCredentials(fresh); // so the proxies and the next process reuse it
+        }
+        catch (err) {
+            logLine("auth.save_failed", { error: errText(err), why: "the token still works in this process" });
+            this.diskStamp = this.stamp();
+            return "save_failed";
+        }
+        this.diskStamp = this.stamp();
+        return "saved";
+    }
+    /**
+     * Decide from the files as they are now, whatever the last stamp said: after
+     * a logout this goes idle, after a sign-in as someone else it records to
+     * them, and after a sibling's refresh of the same sign-in it adopts the
+     * sibling's token (the `same` branch of {@link apply}).
+     */
+    decideFromDiskNow() {
+        this.diskStamp = "";
+        this.checkDisk();
+        logDetail("auth.refresh_superseded", {
+            why: "the sign-in on disk changed while a refresh was out; what is on disk now decides",
+        });
+    }
+    /**
+     * A refusal is asked once more, {@link REJECT_RETRY_MS} later, before it is
+     * final: whatever stands in front of the API can answer for it in JSON too,
+     * and a sign-in that was never really refused should not cost more than
+     * that half hour. A second refusal is final until the file changes (`bir
+     * login`); no answer at all is asked again after another interval.
+     */
+    async maybeRetryRefused() {
+        const r = this.refused;
+        if (this.stateNow !== "rejected" || !r || r.final)
+            return;
+        if (this.now() - r.at < (this.opts.rejectRetryMs ?? REJECT_RETRY_MS))
+            return;
+        const outcome = await refreshSession(r.baseUrl, r.session, this.fetchImpl, serviceTimeoutMs(), this.now);
+        // A sign-in or sign-out while it ran decides instead.
+        if (this.stateNow !== "rejected" || this.refused !== r)
+            return;
+        if (outcome.kind === "ok") {
+            if (this.saveRefreshed(r.session, outcome.session) === "not_ours") {
+                // Signed out or in again meanwhile: the files decide, not this answer.
+                this.decideFromDiskNow();
+                return;
+            }
+            this.install(r.baseUrl, outcome.session);
+            logLine("recorder.enabled", {
+                user: outcome.session.user.email,
+                service: r.baseUrl,
+                why: "the service accepted the saved sign-in when asked again — recording from the next prompt",
+            });
+            return;
+        }
+        if (outcome.kind === "rejected") {
+            r.final = true;
+            logDetail("auth.refresh_refused_again", { status: outcome.status });
+            return;
+        }
+        r.at = this.now();
+    }
+}
+//# sourceMappingURL=recorder-keeper.js.map