@prohost/cli 0.5.0 → 0.7.0

package/dist/agent/runtime_status.js

@@ -0,0 +1,681 @@
+/**
+ * Runtime, model and remaining capacity — what `agent run` tells ProhostAI about itself.
+ *
+ * ProhostAI shows every paired AI employee with its runtime ("Claude Code"),
+ * model ("Opus 5.5"), machine and how much of the operator's Claude or Codex
+ * subscription is left. Only this machine can see those things, so the harness
+ * reports them in a `runtime_status` frame on the socket it already holds.
+ *
+ * **Credentials never leave this machine, and this module never reads them.**
+ * Every number comes from the agent CLI answering with its own login:
+ *
+ * - Claude Code: the `rate_limit_event` and `system/init` lines of a run's own
+ *   `stream-json` output, and — when idle — the `get_usage` control request to
+ *   an unmodified `claude -p --input-format stream-json` (no model turn).
+ * - Codex: the rollout file Codex writes for each run under
+ *   `$CODEX_HOME/sessions`, and — when idle — `account/rateLimits/read` on
+ *   `codex app-server`.
+ *
+ * Nothing here opens the Claude Code keychain item or `~/.codex/auth.json`, and
+ * nothing forwards an account id, email or org. Only labels, percentages and
+ * reset times go on the wire. Unknown or missing data is omitted, never sent as
+ * zero.
+ *
+ * Every parser here fails soft, in the same spirit as `readClaudeStream`: the
+ * shapes belong to other tools and grow without asking us.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Feature name the server lists in `auth_ok.features` when it accepts the frame. */
+export const RUNTIME_STATUS_FEATURE = 'runtime_status';
+/** Routine report cadence while connected. */
+export const STATUS_INTERVAL_MS = 5 * 60_000;
+/**
+ * Minimum spacing between frames. The server accepts one per 30 s per socket
+ * and drops the rest; a second of margin keeps clock jitter from costing us
+ * the frame that carried a change.
+ */
+export const MIN_FRAME_SPACING_MS = 31_000;
+/** Ask the agent CLI for fresh numbers when the last ones are this old. */
+export const QUOTA_REFRESH_AFTER_MS = 15 * 60_000;
+/** Ceiling on one idle quota probe. */
+export const PROVIDER_TIMEOUT_MS = 10_000;
+/** Percent at or above which a window counts as running low / used up. */
+const LOW_PERCENT = 75;
+const EXHAUSTED_PERCENT = 100;
+// ── Small, defensive readers ───────────────────────────────────────────────
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        return asObject(JSON.parse(trimmed));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A percentage on a 0–``scale`` scale, as 0–100 rounded to one decimal. */
+export function percent(value, scale) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    const pct = value * (100 / scale);
+    return Math.min(100, Math.max(0, Math.round(pct * 10) / 10));
+}
+/** Epoch seconds or an ISO string, as ISO-8601; anything else is `undefined`. */
+export function isoTime(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 1e9) {
+        return new Date(value * 1000).toISOString();
+    }
+    if (typeof value === 'string' && !Number.isNaN(Date.parse(value))) {
+        return new Date(value).toISOString();
+    }
+    return undefined;
+}
+/** First `X.Y.Z…` in a `--version` line, e.g. `2.1.282 (Claude Code)` or `codex-cli 0.146.0`. */
+export function parseVersion(stdout) {
+    return /\b(\d+\.\d+\.\d+[0-9A-Za-z.+-]*)/.exec(stdout)?.[1];
+}
+// ── Claude Code ────────────────────────────────────────────────────────────
+const CLAUDE_WINDOWS = [
+    ['five_hour', 'session'],
+    ['seven_day', 'weekly'],
+];
+/** One window, or nothing when the usage itself is unknown. */
+function quotaWindow(kind, used, resets) {
+    return used === undefined ? [] : [{ kind, used_percent: used, resets_at: resets ?? null }];
+}
+/**
+ * Windows from a stream `rate_limit_event.rate_limit_info`.
+ *
+ * `unifiedWindows.*.utilization` is a FRACTION (0–1, and it can exceed 1) with
+ * epoch-second resets — unlike `get_usage`, which is 0–100 with ISO strings.
+ * The field is marked internal upstream, so an unexpected shape yields nothing.
+ */
+export function fromClaudeRateLimitInfo(info) {
+    const windows = asObject(asObject(info)?.unifiedWindows) ?? {};
+    return CLAUDE_WINDOWS.flatMap(([key, kind]) => {
+        const entry = asObject(windows[key]);
+        const used = percent(entry?.utilization, 1);
+        const at = isoTime(entry?.resetsAt);
+        // The event's schema requires `resetsAt` on every window it sends (it
+        // omits a rolled-over window instead), so one without it is malformed.
+        return at ? quotaWindow(kind, used, at) : [];
+    });
+}
+/**
+ * Windows from a `get_usage` control response (0–100, ISO strings).
+ *
+ * A window with a usage but a `null` reset is kept, with `resets_at: null` —
+ * that is how an idle account's 5-hour window reads, and dropping it is what
+ * left paired agents showing a weekly window and nothing else (B3).
+ *
+ * Per-model weekly windows come from `rate_limits.limits[]` rows of kind
+ * `weekly_scoped` (classified on `kind`, as the schema asks, never on a
+ * label), falling back to `model_scoped[]`.
+ */
+export function fromClaudeGetUsage(usage) {
+    const record = asObject(usage);
+    if (record?.rate_limits_available !== true)
+        return [];
+    const limits = asObject(record.rate_limits) ?? {};
+    const windows = CLAUDE_WINDOWS.flatMap(([key, kind]) => {
+        const entry = asObject(limits[key]);
+        return quotaWindow(kind, percent(entry?.utilization, 100), isoTime(entry?.resets_at));
+    });
+    const perModel = new Map();
+    const rows = Array.isArray(limits.limits) ? limits.limits : [];
+    for (const raw of rows) {
+        const row = asObject(raw);
+        if (row?.kind !== 'weekly_scoped')
+            continue;
+        const model = text(asObject(asObject(row.scope)?.model)?.display_name);
+        const used = percent(row.percent, 100);
+        if (!model || used === undefined || perModel.has(model))
+            continue;
+        perModel.set(model, { kind: 'weekly_model', used_percent: used, resets_at: isoTime(row.resets_at) ?? null, model_label: model });
+    }
+    if (perModel.size === 0 && Array.isArray(limits.model_scoped)) {
+        for (const raw of limits.model_scoped) {
+            const row = asObject(raw);
+            const model = text(row?.display_name);
+            const used = percent(row?.utilization, 100);
+            if (!model || used === undefined || perModel.has(model))
+                continue;
+            perModel.set(model, { kind: 'weekly_model', used_percent: used, resets_at: isoTime(row?.resets_at) ?? null, model_label: model });
+        }
+    }
+    return [...windows, ...perModel.values()];
+}
+const CLAUDE_PLANS = {
+    pro: 'Claude Pro',
+    max: 'Claude Max',
+    team: 'Claude Team',
+    enterprise: 'Claude Enterprise',
+};
+/** `get_usage.subscription_type` → display label; `undefined` for anything else. */
+export function claudePlanLabel(subscriptionType) {
+    const key = text(subscriptionType)?.toLowerCase();
+    return key ? CLAUDE_PLANS[key] : undefined;
+}
+// ── Codex ──────────────────────────────────────────────────────────────────
+/**
+ * Windows from Codex `rate_limits` (rollout, snake_case) or `rateLimits`
+ * (app-server, camelCase).
+ *
+ * Classified by window LENGTH, never by slot: on some plans `primary` is the
+ * weekly window and there is no 5-hour one at all.
+ */
+export function fromCodexRateLimits(rateLimits, lineTimestamp) {
+    const record = asObject(rateLimits);
+    if (!record)
+        return [];
+    return [record.primary, record.secondary].flatMap((raw) => {
+        const window = asObject(raw);
+        if (!window)
+            return [];
+        const minutes = window.window_minutes ?? window.windowDurationMins;
+        const kind = typeof minutes !== 'number'
+            ? undefined
+            : minutes > 0 && minutes <= 360
+                ? 'session'
+                : minutes >= 8_640 && minutes <= 11_520
+                    ? 'weekly'
+                    : undefined;
+        const used = percent(window.used_percent ?? window.usedPercent, 100);
+        let at = isoTime(window.resets_at ?? window.resetsAt);
+        // Older Codex builds said "in N seconds", relative to the line it was on.
+        if (!at && typeof window.resets_in_seconds === 'number' && lineTimestamp) {
+            const base = Date.parse(lineTimestamp);
+            if (!Number.isNaN(base))
+                at = new Date(base + window.resets_in_seconds * 1000).toISOString();
+        }
+        return kind ? quotaWindow(kind, used, at) : [];
+    });
+}
+/** `plan_type` / `planType` → `ChatGPT Pro`; `undefined` when there is no plan. */
+export function codexPlanLabel(planType) {
+    const plan = text(planType);
+    if (!plan)
+        return undefined;
+    return `ChatGPT ${plan.charAt(0).toUpperCase()}${plan.slice(1).toLowerCase()}`;
+}
+/** Model named in the exec string itself (`-m gpt-5` / `--model gpt-5` / `--model=gpt-5`). */
+export function modelFromExec(exec) {
+    const words = exec.trim().split(/\s+/);
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i] ?? '';
+        if (word === '-m' || word === '--model')
+            return text(words[i + 1]?.replace(/^['"]|['"]$/g, ''));
+        if (word.startsWith('--model='))
+            return text(word.slice('--model='.length).replace(/^['"]|['"]$/g, ''));
+    }
+    return undefined;
+}
+/** `$CODEX_HOME`, defaulting to `~/.codex` exactly as Codex does. */
+export function codexHome(env = process.env) {
+    return env.CODEX_HOME || path.join(env.HOME || os.homedir(), '.codex');
+}
+/**
+ * The top-level `model = "…"` in `$CODEX_HOME/config.toml` — Codex's default.
+ *
+ * Only the top level, before the first `[table]`: a `model` inside a profile
+ * table is not the default. A first guess only; the rollout's `turn_context`
+ * replaces it after the first run.
+ */
+export function codexConfiguredModel(env = process.env) {
+    let content;
+    try {
+        content = readFileSync(path.join(codexHome(env), 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('['))
+            return undefined;
+        const match = /^model\s*=\s*["']([^"']+)["']/.exec(trimmed);
+        if (match)
+            return text(match[1]);
+    }
+    return undefined;
+}
+/**
+ * Locate the rollout for one thread: `sessions/YYYY/MM/DD/rollout-*-<thread_id>.jsonl`.
+ *
+ * The date directory is local time and a resumed thread lives under the day it
+ * started, so the date is never guessed — days are scanned newest first.
+ */
+export function findCodexRollout(threadId, env = process.env) {
+    if (!/^[0-9A-Za-z-]+$/.test(threadId))
+        return undefined;
+    const suffix = `-${threadId}.jsonl`;
+    const root = path.join(codexHome(env), 'sessions');
+    const children = (dir) => {
+        try {
+            return readdirSync(dir).sort().reverse();
+        }
+        catch {
+            return [];
+        }
+    };
+    for (const year of children(root)) {
+        for (const month of children(path.join(root, year))) {
+            for (const day of children(path.join(root, year, month))) {
+                const dir = path.join(root, year, month, day);
+                const hit = children(dir).find((name) => name.startsWith('rollout-') && name.endsWith(suffix));
+                if (hit)
+                    return path.join(dir, hit);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * What a Codex rollout says: the model the turn really used (after `-m`,
+ * profiles and `-c`), the CLI version, and the last rate-limit snapshot.
+ */
+export function parseCodexRollout(content) {
+    const observed = {};
+    for (const line of content.split('\n')) {
+        const entry = parseLine(line);
+        if (!entry)
+            continue;
+        const payload = asObject(entry.payload);
+        if (!payload)
+            continue;
+        if (entry.type === 'session_meta') {
+            observed.runtime_version = text(payload.cli_version) ?? observed.runtime_version;
+        }
+        else if (entry.type === 'turn_context') {
+            observed.model = text(payload.model) ?? observed.model;
+        }
+        else if (entry.type === 'event_msg' && payload.type === 'token_count' && payload.rate_limits) {
+            // One per model response — the last one is the freshest.
+            observed.quota_windows = fromCodexRateLimits(payload.rate_limits, typeof entry.timestamp === 'string' ? entry.timestamp : undefined);
+            observed.plan_label = codexPlanLabel(asObject(payload.rate_limits)?.plan_type) ?? observed.plan_label;
+        }
+    }
+    return observed;
+}
+/** Read the rollout for a finished Codex thread, if it can be found. */
+export function readCodexObservation(threadId, env = process.env) {
+    if (!threadId)
+        return undefined;
+    const file = findCodexRollout(threadId, env);
+    if (!file || !existsSync(file))
+        return undefined;
+    try {
+        return parseCodexRollout(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Spawn ``command args``, write ``lines`` as JSONL, and resolve with the first
+ * stdout line ``pick`` accepts. Kills the child on answer, error or timeout.
+ */
+function exchangeJsonLines(spawnImpl, command, args, lines, pick, timeoutMs, env) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let buffer = '';
+        let child;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child?.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(undefined), timeoutMs);
+        timer.unref?.();
+        try {
+            // `env` selects the account (CLAUDE_CONFIG_DIR / CODEX_HOME) — the
+            // probe must ask the login the agent actually runs on.
+            child = spawnImpl(command, args, {
+                stdio: ['pipe', 'pipe', 'ignore'],
+                ...(env ? { env: { ...process.env, ...env } } : {}),
+            });
+        }
+        catch {
+            finish(undefined);
+            return;
+        }
+        child.on('error', () => finish(undefined));
+        child.on('close', () => finish(undefined));
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            buffer += chunk;
+            if (buffer.length > 1024 * 1024)
+                buffer = buffer.slice(-64 * 1024);
+            const parts = buffer.split('\n');
+            buffer = parts.pop() ?? '';
+            for (const part of parts) {
+                const parsed = parseLine(part);
+                if (!parsed)
+                    continue;
+                const value = pick(parsed);
+                if (value !== undefined) {
+                    finish(value);
+                    return;
+                }
+            }
+        });
+        child.stdin?.on('error', () => {
+            /* child exited before reading; `close` settles */
+        });
+        child.stdin?.write(lines.map((line) => JSON.stringify(line)).join('\n') + '\n');
+    });
+}
+/**
+ * Claude Code's `get_usage` control request. No model turn is made, so no
+ * quota is spent. The `initialize` response carries account identity; it is
+ * never read.
+ */
+export function claudeQuotaProvider(options) {
+    return {
+        refresh: () => exchangeJsonLines(options.spawnImpl ?? nodeSpawn, options.binary, ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'], [
+            { type: 'control_request', request_id: 'prohost-init', request: { subtype: 'initialize' } },
+            {
+                type: 'control_request',
+                request_id: 'prohost-usage',
+                request: { subtype: 'get_usage', skip_behaviors: true },
+            },
+        ], (line) => {
+            if (line.type !== 'control_response')
+                return undefined;
+            const response = asObject(line.response);
+            if (response?.request_id !== 'prohost-usage')
+                return undefined;
+            if (response.subtype !== 'success')
+                return {};
+            const usage = asObject(response.response) ?? response;
+            const windows = fromClaudeGetUsage(usage);
+            return {
+                plan_label: claudePlanLabel(usage.subscription_type),
+                ...(windows.length > 0 ? { quota_windows: windows } : {}),
+            };
+        }, options.timeoutMs ?? PROVIDER_TIMEOUT_MS, options.env?.()),
+    };
+}
+/** Codex's `account/rateLimits/read` over `codex app-server` stdio JSON-RPC. */
+export function codexQuotaProvider(options) {
+    return {
+        refresh: () => exchangeJsonLines(options.spawnImpl ?? nodeSpawn, options.binary, ['app-server'], [
+            {
+                id: 1,
+                method: 'initialize',
+                params: { clientInfo: { name: 'prohost-cli', version: options.clientVersion } },
+            },
+            { method: 'initialized' },
+            { id: 2, method: 'account/rateLimits/read' },
+        ], (line) => {
+            if (line.id !== 2)
+                return undefined;
+            const rateLimits = asObject(asObject(line.result)?.rateLimits);
+            if (!rateLimits)
+                return {};
+            const windows = fromCodexRateLimits(rateLimits);
+            return {
+                plan_label: codexPlanLabel(rateLimits.planType),
+                ...(windows.length > 0 ? { quota_windows: windows } : {}),
+            };
+        }, options.timeoutMs ?? PROVIDER_TIMEOUT_MS, options.env?.()),
+    };
+}
+// ── The reporter ───────────────────────────────────────────────────────────
+/** Coarse capacity band: a change of band is worth a frame straight away. */
+function band(windows) {
+    const top = Math.max(0, ...(windows ?? []).map((w) => w.used_percent));
+    return top >= EXHAUSTED_PERCENT ? 2 : top >= LOW_PERCENT ? 1 : 0;
+}
+/**
+ * Fold new windows into the ones already known, one KIND at a time.
+ *
+ * Sources see different slices: a run's `rate_limit_event` carries only the
+ * 5-hour and weekly windows (and omits one whose reset has passed), while the
+ * idle `get_usage` probe also carries the per-model weekly ones. Replacing the
+ * whole list with whatever arrived last is how a stream event used to erase
+ * the windows it simply didn't mention. A kind the observation names replaces
+ * every window of that kind; a kind it doesn't name is kept.
+ */
+export function mergeWindows(known, observed) {
+    const kinds = new Set(observed.map((w) => w.kind));
+    return [...(known ?? []).filter((w) => !kinds.has(w.kind)), ...observed];
+}
+/**
+ * A window as of ``nowMs``: one whose reset has passed has rolled over, so it
+ * is reported as a fresh window — 0%, not started — rather than dropped. The
+ * agent CLI omits a rolled-over window from its own events, so this is the
+ * only place that knows it exists.
+ */
+function asOf(window, nowMs) {
+    if (window.resets_at === null || Date.parse(window.resets_at) > nowMs)
+        return window;
+    return { ...window, used_percent: 0, resets_at: null };
+}
+function defaultSchedule(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+/**
+ * Holds the latest runtime snapshot and decides when to send it.
+ *
+ * Sends only while attached — i.e. only on a socket whose server advertised
+ * {@link RUNTIME_STATUS_FEATURE}. Cadence: once on attach, every
+ * {@link STATUS_INTERVAL_MS}, and promptly when the model, plan or runtime
+ * version changes or capacity crosses a band — but never closer together than
+ * {@link MIN_FRAME_SPACING_MS}.
+ */
+export class RuntimeStatusReporter {
+    options;
+    now;
+    schedule;
+    state = {};
+    quotaObservedAt;
+    send;
+    lastSentAt;
+    cancelPending;
+    cancelTick;
+    refreshing;
+    accountGeneration = 0;
+    accounts;
+    accountsObservedAt;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.schedule = options.schedule ?? defaultSchedule;
+    }
+    /** Merge what a source learned. Absent fields keep their previous value. */
+    observe(observation) {
+        if (!observation)
+            return;
+        const before = this.state;
+        const next = { ...before };
+        if (observation.runtime_version)
+            next.runtime_version = observation.runtime_version;
+        if (observation.model)
+            next.model = observation.model;
+        if (observation.plan_label)
+            next.plan_label = observation.plan_label;
+        if (observation.quota_windows && observation.quota_windows.length > 0) {
+            next.quota_windows = mergeWindows(before.quota_windows, observation.quota_windows);
+            this.quotaObservedAt = this.now();
+        }
+        this.state = next;
+        const changed = next.runtime_version !== before.runtime_version ||
+            next.model !== before.model ||
+            next.plan_label !== before.plan_label ||
+            band(next.quota_windows) !== band(before.quota_windows);
+        if (changed)
+            this.sendSoon();
+    }
+    /**
+     * Record the accounts snapshot. Moving to another account drops what was
+     * known about the previous one's capacity and plan — they describe a
+     * different subscription — and asks for fresh numbers straight away.
+     */
+    setAccounts(snapshot, options = {}) {
+        const before = this.accounts;
+        this.accounts = snapshot;
+        this.accountsObservedAt = this.now();
+        const switched = before?.current?.key !== snapshot?.current?.key;
+        if (switched) {
+            this.accountGeneration += 1;
+            // A probe belongs to the login it started with. Let the new login
+            // refresh immediately even while an older probe is still finishing.
+            this.refreshing = undefined;
+            const { quota_windows: _windows, plan_label: _plan, ...rest } = this.state;
+            this.state = rest;
+            this.quotaObservedAt = undefined;
+        }
+        if (!options.quiet && JSON.stringify(before) !== JSON.stringify(snapshot))
+            this.sendSoon();
+    }
+    /**
+     * The account choice changed (an operator picked one in ProhostAI): re-read
+     * accounts and capacity on the next tick rather than in fifteen minutes.
+     */
+    accountsChanged() {
+        this.accountsObservedAt = undefined;
+        this.quotaObservedAt = undefined;
+        if (!this.send)
+            return;
+        this.cancelTick?.();
+        this.cancelTick = undefined;
+        void this.tick();
+    }
+    /** The model to report on a run's completion, when nothing more specific is known. */
+    model() {
+        return this.state.model;
+    }
+    /** Start reporting on a socket that advertised the feature. */
+    attach(send) {
+        this.detach();
+        this.send = send;
+        this.lastSentAt = undefined;
+        void this.tick();
+    }
+    /** Stop reporting — the socket is gone. */
+    detach() {
+        this.send = undefined;
+        this.cancelPending?.();
+        this.cancelPending = undefined;
+        this.cancelTick?.();
+        this.cancelTick = undefined;
+    }
+    /** The frame as it would be sent now. */
+    frame() {
+        const nowMs = this.now();
+        const windows = (this.state.quota_windows ?? []).map((w) => asOf(w, nowMs));
+        return {
+            type: 'runtime_status',
+            runtime: this.options.runtime,
+            runtime_version: this.state.runtime_version ?? null,
+            model: this.state.model ?? null,
+            plan_label: this.state.plan_label ?? null,
+            quota_windows: windows,
+            observed_at: new Date(nowMs).toISOString(),
+            // Optional additions: an older server ignores keys it doesn't know.
+            ...(this.accounts?.current ? { account: this.accounts.current } : {}),
+            ...(this.accounts?.all ? { machine_accounts: this.accounts.all } : {}),
+        };
+    }
+    /** Routine tick: refresh idle quota if it is stale, send, and re-arm. */
+    async tick() {
+        if (!this.send)
+            return;
+        const stale = this.quotaObservedAt === undefined || this.now() - this.quotaObservedAt >= QUOTA_REFRESH_AFTER_MS;
+        const sentBefore = this.lastSentAt;
+        const accountsStale = this.accountsObservedAt === undefined || this.now() - this.accountsObservedAt >= QUOTA_REFRESH_AFTER_MS;
+        if (accountsStale && this.options.accounts) {
+            // Before the quota probe: after a switch it must ask the new login.
+            try {
+                // Quiet: the tick sends one frame once the quota probe below is in.
+                this.setAccounts(await this.options.accounts(), { quiet: true });
+            }
+            catch {
+                /* fail soft — keep what we had */
+            }
+            if (!this.send)
+                return;
+        }
+        if (stale && this.options.provider && !this.options.isBusy?.()) {
+            await this.refresh();
+        }
+        if (!this.send)
+            return;
+        // A refresh that changed something has already sent (or queued) a frame.
+        if (this.lastSentAt === sentBefore)
+            this.sendSoon();
+        this.cancelTick?.();
+        this.cancelTick = this.schedule(() => void this.tick(), this.options.intervalMs ?? STATUS_INTERVAL_MS);
+    }
+    refresh() {
+        if (!this.refreshing) {
+            const provider = this.options.provider;
+            const generation = this.accountGeneration;
+            const refreshing = (provider ? provider.refresh() : Promise.resolve(undefined))
+                .then((observed) => {
+                if (generation !== this.accountGeneration)
+                    return;
+                // `observe` would itself schedule a send on a change; the caller
+                // sends right after, which the spacing rule coalesces.
+                this.observe(observed);
+            })
+                .catch(() => {
+                /* fail soft — keep what we had */
+            })
+                .finally(() => {
+                if (this.refreshing === refreshing)
+                    this.refreshing = undefined;
+            });
+            this.refreshing = refreshing;
+        }
+        return this.refreshing;
+    }
+    /** Send now if spacing allows, else once it does. Coalesces. */
+    sendSoon() {
+        if (!this.send || this.cancelPending)
+            return;
+        const wait = this.lastSentAt === undefined ? 0 : this.lastSentAt + MIN_FRAME_SPACING_MS - this.now();
+        if (wait <= 0) {
+            this.flush();
+            return;
+        }
+        this.cancelPending = this.schedule(() => {
+            this.cancelPending = undefined;
+            this.flush();
+        }, wait);
+    }
+    flush() {
+        if (!this.send)
+            return;
+        try {
+            this.send(this.frame());
+            this.lastSentAt = this.now();
+        }
+        catch (err) {
+            this.options.log?.(`runtime status not sent: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}