@prohost/cli 0.4.2 → 0.6.0

package/dist/agent/run.js

@@ -25,7 +25,7 @@
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import WebSocket from 'ws';
-import { completeRun, postReply } from './api.js';
+import { completeRun, describeFailure, isIdempotencyInFlight, postReply } from './api.js';
 import { MAX_SALVAGE_CHARS, claudeCommand, isClaudeExec, looksLikeResumeFailure, readClaudeStream, writeMcpConfig, } from './claude.js';
 import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBinary, codexCommand, codexMcpInventoryFlag, codexProfileName, codexShellSyntax, extraMcpEntries, isCodexExec, isolateConfiguredServers, listMcpServers, mcpServersOverride, prohostMcpEntry, looksLikeCodexResumeFailure, parseCodexOutput, } from './codex.js';
 import { EXTRA_MCP_FILENAME, loadExtraMcpServers } from './extras.js';
@@ -36,10 +36,13 @@ import { execAgent } from './exec.js';
 import { HeartbeatLoop } from './heartbeat.js';
 import { buildPrompt, replyFromStdout } from './prompt.js';
 import { RunStore } from './runstore.js';
+import { RUNTIME_STATUS_FEATURE, RuntimeStatusReporter, claudeQuotaProvider, codexConfiguredModel, codexQuotaProvider, modelFromExec, parseVersion, readCodexObservation, } from './runtime_status.js';
 import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
+import { ServerLiveness, enableTcpKeepAlive, seconds, terminateSocket } from '../liveness.js';
+import { CLI_VERSION, USER_AGENT } from '../version.js';
 /**
  * Default ceiling on one agent invocation: none.
  *
@@ -74,6 +77,14 @@ export const DEFAULT_IDLE_TIMEOUT_MS = 900_000;
 /** Reconnect backoff — full jitter between ``BASE`` and the current cap. */
 const RECONNECT_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_DELAY_MS = 30_000;
+/**
+ * Longest the websocket handshake may take before `ws` gives up on it.
+ *
+ * The liveness deadline only starts at `open`; without this, a connect that
+ * stalls mid-handshake — the same asleep-laptop shape, one step earlier —
+ * would hang with neither `open` nor `close` to move the loop along.
+ */
+const HANDSHAKE_TIMEOUT_MS = 30_000;
 /** Ack status codes reported back over the socket for each frame. */
 const ACK_ACCEPTED = 200;
 const ACK_IGNORED = 204;
@@ -88,6 +99,7 @@ function newMetrics() {
         signatureRejections: 0,
         ignored: 0,
         duplicates: 0,
+        livenessTimeouts: 0,
     };
 }
 function timestamp() {
@@ -122,20 +134,70 @@ const COMPLETION_RETRY_DELAYS_MS = [1_000, 3_000, 9_000, 30_000, 60_000, 120_000
  * sweeper reaps it. A 409 (`already_resolved`) counts as done. A 4xx other
  * than 429 is a decision, not a blip, so it isn't retried.
  */
-async function completeWithRetry(api, path, outcome, log, sleep) {
-    let result = await completeRun(api, path, outcome);
+async function completeWithRetry(api, path, outcome, log, sleep, model) {
+    let result = await completeRun(api, path, outcome, model);
     for (const delay of COMPLETION_RETRY_DELAYS_MS) {
         if (result.ok)
             return result;
         const retryable = result.status === 0 || result.status === 429 || result.status >= 500;
         if (!retryable)
             return result;
-        log(`    … completion failed (HTTP ${result.status}); retrying in ${delay / 1000}s`);
+        log(`    … completion failed (${describeFailure(result)}); retrying in ${delay / 1000}s`);
         await sleep(delay);
-        result = await completeRun(api, path, outcome);
+        result = await completeRun(api, path, outcome, model);
     }
     return result;
 }
+/**
+ * How long to wait before replaying a reply whose first attempt the server
+ * reports as still in flight. The original request is being processed at
+ * that moment; a few seconds is enough for it to finish and be cached.
+ */
+const REPLAY_IN_FLIGHT_DELAY_MS = 5_000;
+/**
+ * Post the reply, and if the request dies in transit, replay it once with
+ * the same idempotency key before believing it failed.
+ *
+ * A request abandoned at its deadline is not a request that failed — it is
+ * a request whose answer we did not wait for. On 2026-09-01 the server took
+ * 51 s to accept a reply that the CLI had given up on at 30 s; the message
+ * was in the conversation, and the CLI reported the run as failed anyway.
+ * The key (``prohost-cli-run-<run_id>``) already made the send idempotent
+ * server-side, so the correct reaction to "no answer" is to ask again with
+ * the same key and let the server say what happened:
+ *
+ * - a 2xx (fresh, or the cached response of the attempt that did land) —
+ *   the reply is durable, carry on as a success;
+ * - ``409 idempotency_key_in_flight`` — the first attempt is still being
+ *   processed; wait, then replay once more;
+ * - anything else — a real decision or a second transport failure — is the
+ *   answer, and the run is reported failed exactly once.
+ */
+async function postReplyWithReplay(api, send, label, log, sleep) {
+    let posted = await send();
+    // A real answer — success or a decision — is final. Only "no answer at all"
+    // earns a replay.
+    if (posted.ok || posted.status !== 0)
+        return posted;
+    const why = posted.failure === 'timeout'
+        ? `reply POST ${posted.error}`
+        : `reply POST failed (${describeFailure(posted)})`;
+    log(`${timestamp()} … ${label} ${why} — replaying with the same idempotency key`);
+    posted = await send();
+    if (posted.ok) {
+        log(`${timestamp()} ✓ ${label} reply confirmed on replay`);
+        return posted;
+    }
+    if (isIdempotencyInFlight(posted)) {
+        log(`${timestamp()} … ${label} first reply attempt is still in flight server-side — ` +
+            `replaying again in ${REPLAY_IN_FLIGHT_DELAY_MS / 1000}s`);
+        await sleep(REPLAY_IN_FLIGHT_DELAY_MS);
+        posted = await send();
+        if (posted.ok)
+            log(`${timestamp()} ✓ ${label} reply confirmed on replay`);
+    }
+    return posted;
+}
 /**
  * Decide where the agent command runs.
  *
@@ -179,8 +241,21 @@ function buildRuntime(options, log) {
             ? 'codex'
             : 'plain';
     const skipPermissions = options.safeTools !== true;
+    const runtimeName = runtimeNameFor(brain, options.exec);
+    // Replaced by the harness once its status reporter exists.
+    const observe = () => { };
+    const model = () => undefined;
     if (brain === 'plain') {
-        return { workdir, sessions, brain, skipPermissions, prepareMcp: () => ({ mcpWired: false }) };
+        return {
+            workdir,
+            sessions,
+            brain,
+            skipPermissions,
+            prepareMcp: () => ({ mcpWired: false }),
+            runtimeName,
+            observe,
+            model,
+        };
     }
     const mcpUrl = options.credentials.mcp_url;
     let announced = '';
@@ -235,7 +310,30 @@ function buildRuntime(options, log) {
             'access, on instructions from your workspace. Use --safe-tools to gate them.'
         : `${timestamp()} ⚙ --safe-tools: tools are permission-gated; anything needing ` +
             'approval will not run (nobody is at a terminal to approve it).');
-    return { workdir, sessions, brain, prepareMcp, skipPermissions };
+    return { workdir, sessions, brain, prepareMcp, skipPermissions, runtimeName, observe, model };
+}
+/**
+ * The `runtime` a status frame names. A plain command is `custom` unless it is
+ * recognisably goose — the one other agent CLI people pair today.
+ */
+function runtimeNameFor(brain, exec) {
+    if (brain === 'claude')
+        return 'claude_code';
+    if (brain === 'codex')
+        return 'codex';
+    const base = (exec.trim().split(/\s+/)[0] ?? '').split('/').pop() ?? '';
+    return base === 'goose' ? 'goose' : 'custom';
+}
+/**
+ * Idle capacity source for the detected brain: the agent CLI itself, asked
+ * through its own protocol so its own login answers. `plain` has none.
+ */
+function defaultQuotaProvider(brain, exec) {
+    if (brain === 'claude')
+        return claudeQuotaProvider({ binary: exec.trim().split(/\s+/)[0] ?? 'claude' });
+    if (brain === 'codex')
+        return codexQuotaProvider({ binary: codexBinary(exec), clientVersion: CLI_VERSION });
+    return undefined;
 }
 /**
  * Prepare a fresh Codex MCP override immediately before each invocation.
@@ -513,7 +611,7 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
         const reader = runtime.brain === 'claude' ? readClaudeStream() : undefined;
         stream = reader;
         tail = '';
-        return execAgent({
+        const running = execAgent({
             command,
             prompt,
             timeoutMs: capped ? Math.max(1, remainingMs()) : 0,
@@ -533,6 +631,9 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
                     }
                     : undefined,
         });
+        // Whatever the stream announced — model, version, capacity — is true of
+        // this machine whether or not the turn succeeded.
+        return reader ? running.finally(() => runtime.observe(reader.observed())) : running;
     };
     // Wall clock for the whole turn, retry included — what the operator waited,
     // rather than what the last attempt took.
@@ -643,6 +744,9 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log) {
     };
     if (codex) {
         const output = parseCodexOutput(result.stdout);
+        // Codex's `--json` stream carries neither model nor limits; its rollout
+        // file for this thread does.
+        runtime.observe(readCodexObservation(output.sessionId, { ...process.env, ...options.env }));
         reportDenials(output.denials);
         if (!output.ok) {
             return {
@@ -726,9 +830,10 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         }
         // The exact marker string, alone: the server words the thread notice from
         // it, and anything wrapped around it reads as a crash instead of a stop.
-        const closed = await completeWithRetry(api, run.completion_path, { ok: false, error: RUN_ERROR_CANCELLED_BY_USER }, log, sleep);
+        const closed = await completeWithRetry(api, run.completion_path, { ok: false, error: RUN_ERROR_CANCELLED_BY_USER }, log, sleep, runtime.model());
         if (!closed.ok) {
-            log(`    ! could not report the cancellation (HTTP ${closed.status}) ${closed.error ?? ''}`);
+            log(`    ! could not report the cancellation (${describeFailure(closed)})` +
+                `${closed.status !== 0 && closed.error ? ` ${closed.error}` : ''}`);
             return 'unreported';
         }
         return 'cancelled';
@@ -743,9 +848,10 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
             log(`    [dry-run] would report the run as failed`);
             return 'skipped';
         }
-        const completed = await completeWithRetry(api, run.completion_path, { ok: false, error: detail ? `${reason}: ${detail}` : reason }, log, sleep);
+        const completed = await completeWithRetry(api, run.completion_path, { ok: false, error: detail ? `${reason}: ${detail}` : reason }, log, sleep, runtime.model());
         if (!completed.ok) {
-            log(`    ! could not report failure (HTTP ${completed.status}) ${completed.error ?? ''}`);
+            log(`    ! could not report failure (${describeFailure(completed)})` +
+                `${completed.status !== 0 && completed.error ? ` ${completed.error}` : ''}`);
             return 'unreported';
         }
         return 'failed';
@@ -770,9 +876,9 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         log(`${timestamp()} ✓ ${label} finished in ${seconds}s (${why})`);
         for (const line of reply.split('\n'))
             log(`    │ ${line}`);
-        const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
+        const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep, runtime.model());
         if (!completed.ok) {
-            log(`    ! could not mark the run complete (HTTP ${completed.status})`);
+            log(`    ! could not mark the run complete (${describeFailure(completed)})`);
             return 'unreported';
         }
         if (result.sessionId) {
@@ -780,16 +886,20 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         }
         return 'succeeded';
     }
-    const posted = await postReply(api, run.reply_path, run.reply_body_key, reply, run.run_id, run.reply_body_extra);
+    const replyPath = run.reply_path;
+    const replyBodyKey = run.reply_body_key;
+    const posted = await postReplyWithReplay(api, () => postReply(api, replyPath, replyBodyKey, reply, run.run_id, run.reply_body_extra), label, log, sleep);
     if (!posted.ok) {
-        log(`${timestamp()} ✗ ${label} reply rejected (HTTP ${posted.status}) ${posted.error ?? ''}`);
+        const failure = describeFailure(posted);
+        const detail = posted.status === 0 ? '' : ` ${posted.error ?? ''}`;
+        log(`${timestamp()} ✗ ${label} reply rejected (${failure})${detail}`);
         // Undo the mid-run recording. The session exists and the agent's transcript
         // holds this turn, but the conversation never received its answer, so
         // continuing it would skip reasoning nobody can see — the same rule that
         // used to be expressed by simply not recording until the reply landed.
         if (result.sessionRecorded)
             runtime.sessions.forget(sessionKeyFor(run));
-        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed with HTTP ${posted.status}` }, log, sleep);
+        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed: ${failure}` }, log, sleep, runtime.model());
         return reported.ok ? 'failed' : 'unreported';
     }
     // Advance continuity only after the answer is durable on its reply surface.
@@ -798,13 +908,13 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
     if (result.sessionId) {
         runtime.sessions.remember(sessionKeyFor(run), result.sessionId);
     }
-    const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
+    const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep, runtime.model());
     if (!completed.ok) {
         // The reply is already in the conversation, so this is a bookkeeping
         // failure, not a lost answer — say so precisely. Returning false lets the
         // caller forget the run so a redelivery can retry the completion; the
         // reply's idempotency key stops that from posting twice.
-        log(`${timestamp()} ! ${label} replied, but marking it complete failed (HTTP ${completed.status})`);
+        log(`${timestamp()} ! ${label} replied, but marking it complete failed (${describeFailure(completed)})`);
         return 'unreported';
     }
     log(`${timestamp()} ✓ ${label} replied in ${seconds}s (${reply.length} chars)`);
@@ -847,6 +957,44 @@ export async function runAgentHarness(options) {
     /** Accepted, not yet reported — the executing run and everything queued. */
     const accepted = new Map();
     const heartbeats = new HeartbeatLoop({ api, log, intervalMs: options.heartbeatIntervalMs });
+    const status = new RuntimeStatusReporter({
+        runtime: runtime.runtimeName,
+        provider: options.quotaProvider === undefined
+            ? defaultQuotaProvider(runtime.brain, options.exec)
+            : (options.quotaProvider ?? undefined),
+        // A run in flight reports fresh numbers when it ends; don't probe beside it.
+        isBusy: () => [...accepted.values()].some((entry) => entry.executing),
+        log,
+    });
+    runtime.observe = (observation) => status.observe(observation);
+    runtime.model = () => (runtime.brain === 'plain' ? undefined : status.model());
+    let statusPrimed = false;
+    /**
+     * First-connect facts that need no run: the CLI's version and any model the
+     * exec string or Codex config pins. Done lazily — only once a server has
+     * asked for status — so nothing is probed for a server that can't use it.
+     */
+    const primeStatus = () => {
+        if (statusPrimed || runtime.brain === 'plain')
+            return;
+        statusPrimed = true;
+        const binary = runtime.brain === 'codex'
+            ? codexBinary(options.exec)
+            : (options.exec.trim().split(/\s+/)[0] ?? 'claude');
+        const probe = options.probeImpl ?? defaultProbe;
+        let version;
+        try {
+            version = parseVersion(probe(`${binary} --version`, runtime.workdir).stdout);
+        }
+        catch {
+            version = undefined;
+        }
+        status.observe({
+            runtime_version: version,
+            model: modelFromExec(options.exec) ??
+                (runtime.brain === 'codex' ? codexConfiguredModel({ ...process.env, ...options.env }) : undefined),
+        });
+    };
     let queue = Promise.resolve();
     let fatal;
     let attempt = 0;
@@ -934,6 +1082,7 @@ export async function runAgentHarness(options) {
     // any cancellation the heartbeat loop started and deliberately did not wait
     // for, so the harness never exits with a run half-closed.
     await queue;
+    status.detach();
     // Stopped first, so no further tick can start work after the wait below has
     // taken its snapshot of `background`.
     heartbeats.stop();
@@ -945,7 +1094,11 @@ export async function runAgentHarness(options) {
     return metrics;
     /** One socket lifetime. Resolves ``true`` when the session ever authed. */
     function connectOnce() {
-        const ws = new Ctor(url);
+        // The `User-Agent` names the build server-side, the same as every HTTP
+        // call this CLI makes; `client_version` in the auth frame is the copy the
+        // server reads, because a header on an upgrade request is easy to lose in
+        // proxies and logs and a frame field is not.
+        const ws = new Ctor(url, { headers: { 'User-Agent': USER_AGENT }, handshakeTimeout: HANDSHAKE_TIMEOUT_MS });
         let authed = false;
         return new Promise((resolve) => {
             const close = () => {
@@ -962,7 +1115,33 @@ export async function runAgentHarness(options) {
                 else
                     options.signal.addEventListener('abort', close, { once: true });
             }
+            // The server pings every 30 s and reaps after 60 s without a pong — but
+            // that close never reaches a client whose kernel still believes the
+            // connection is up (a laptop that slept through the FIN). Keep our own
+            // deadline: no frame of any kind for the window means the socket is
+            // dead, and tearing it down here is what makes the reconnect loop run.
+            const liveness = new ServerLiveness({
+                timeoutMs: options.livenessTimeoutMs,
+                heartbeatIntervalMs: options.heartbeatLogIntervalMs,
+                onSilence: (silentMs) => {
+                    metrics.livenessTimeouts += 1;
+                    log(`${timestamp()} … no server ping for ${seconds(silentMs)}s — reconnecting`);
+                    terminateSocket(ws);
+                },
+                onHeartbeat: (state) => {
+                    if (!authed)
+                        return;
+                    const since = state.sinceLastPingMs === undefined
+                        ? `no server ping yet (connected ${seconds(state.sinceLastFrameMs)}s ago)`
+                        : `last server ping ${seconds(state.sinceLastPingMs)}s ago`;
+                    log(`${timestamp()} ● connected — ${since}`);
+                },
+            });
             ws.on('open', () => {
+                // Kernel-level probe underneath the application-level one: a dead
+                // peer is detected by the TCP stack even while the socket is idle.
+                enableTcpKeepAlive(ws);
+                liveness.start();
                 // `subscription_id` is a presence signal, not a scoping one: the server
                 // derives which subscription's events this socket receives from the
                 // connection itself. Sending it stamps `connected_from` with this
@@ -972,6 +1151,7 @@ export async function runAgentHarness(options) {
                     type: 'auth',
                     api_key: options.credentials.api_key,
                     machine,
+                    client_version: CLI_VERSION,
                     ...(options.credentials.subscription_id
                         ? { subscription_id: options.credentials.subscription_id }
                         : {}),
@@ -983,11 +1163,16 @@ export async function runAgentHarness(options) {
                     frame = JSON.parse(data.toString());
                 }
                 catch {
+                    // Unparseable, but the server sent it: still proof it is there.
+                    liveness.observe(undefined);
                     return;
                 }
-                if (!frame || typeof frame !== 'object')
+                if (!frame || typeof frame !== 'object') {
+                    liveness.observe(undefined);
                     return;
+                }
                 const f = frame;
+                liveness.observe(f.type);
                 if (f.type === 'auth_ok') {
                     authed = true;
                     const name = options.credentials.agent?.name ?? 'agent';
@@ -999,6 +1184,12 @@ export async function runAgentHarness(options) {
                     // read mention code instead of the run dispatcher.
                     log(`${timestamp()} ● connected as "${name}" — waiting for ` +
                         `${EVENT_AGENT_RUN_REQUESTED} (exec: ${options.exec})`);
+                    // Only a server that says it understands the frame gets one; an
+                    // older server may treat an unknown frame type as a protocol error.
+                    if (Array.isArray(f.features) && f.features.includes(RUNTIME_STATUS_FEATURE)) {
+                        primeStatus();
+                        status.attach((frame) => ws.send(JSON.stringify(frame)));
+                    }
                     return;
                 }
                 if (f.type === 'auth_error') {
@@ -1161,6 +1352,8 @@ export async function runAgentHarness(options) {
                 });
             });
             ws.on('close', () => {
+                liveness.stop();
+                status.detach();
                 if (options.signal)
                     options.signal.removeEventListener('abort', close);
                 resolve(authed);

package/dist/agent/runtime_status.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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';
+/** Feature name the server lists in `auth_ok.features` when it accepts the frame. */
+export declare const RUNTIME_STATUS_FEATURE = "runtime_status";
+/** Routine report cadence while connected. */
+export declare const STATUS_INTERVAL_MS: number;
+/**
+ * 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 declare const MIN_FRAME_SPACING_MS = 31000;
+/** Ask the agent CLI for fresh numbers when the last ones are this old. */
+export declare const QUOTA_REFRESH_AFTER_MS: number;
+/** Ceiling on one idle quota probe. */
+export declare const PROVIDER_TIMEOUT_MS = 10000;
+export type QuotaKind = 'session' | 'weekly';
+export interface QuotaWindow {
+    kind: QuotaKind;
+    /** 0–100. */
+    used_percent: number;
+    /** ISO-8601. */
+    resets_at: string;
+}
+/** What one source managed to learn. Every field is optional; absent means "didn't learn it". */
+export interface RuntimeObservation {
+    runtime_version?: string;
+    model?: string;
+    plan_label?: string;
+    quota_windows?: QuotaWindow[];
+}
+/** A percentage on a 0–``scale`` scale, as 0–100 rounded to one decimal. */
+export declare function percent(value: unknown, scale: 1 | 100): number | undefined;
+/** Epoch seconds or an ISO string, as ISO-8601; anything else is `undefined`. */
+export declare function isoTime(value: unknown): string | undefined;
+/** First `X.Y.Z…` in a `--version` line, e.g. `2.1.282 (Claude Code)` or `codex-cli 0.146.0`. */
+export declare function parseVersion(stdout: string): string | undefined;
+/**
+ * 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 declare function fromClaudeRateLimitInfo(info: unknown): QuotaWindow[];
+/** Windows from a `get_usage` control response (0–100, ISO strings). */
+export declare function fromClaudeGetUsage(usage: unknown): QuotaWindow[];
+/** `get_usage.subscription_type` → display label; `undefined` for anything else. */
+export declare function claudePlanLabel(subscriptionType: unknown): string | undefined;
+/**
+ * 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 declare function fromCodexRateLimits(rateLimits: unknown, lineTimestamp?: string): QuotaWindow[];
+/** `plan_type` / `planType` → `ChatGPT Pro`; `undefined` when there is no plan. */
+export declare function codexPlanLabel(planType: unknown): string | undefined;
+/** Model named in the exec string itself (`-m gpt-5` / `--model gpt-5` / `--model=gpt-5`). */
+export declare function modelFromExec(exec: string): string | undefined;
+/** `$CODEX_HOME`, defaulting to `~/.codex` exactly as Codex does. */
+export declare function codexHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * 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 declare function codexConfiguredModel(env?: NodeJS.ProcessEnv): string | 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 declare function findCodexRollout(threadId: string, env?: NodeJS.ProcessEnv): string | 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 declare function parseCodexRollout(content: string): RuntimeObservation;
+/** Read the rollout for a finished Codex thread, if it can be found. */
+export declare function readCodexObservation(threadId: string | undefined, env?: NodeJS.ProcessEnv): RuntimeObservation | undefined;
+/**
+ * Where fresh numbers come from when no run has produced any lately.
+ *
+ * Implementations ask the unmodified agent CLI through its own protocol, so
+ * the CLI answers with its own login and this process never holds a
+ * credential. Resolve `undefined` on any failure — the reporter keeps what it
+ * had and omits what it doesn't know.
+ */
+export interface QuotaProvider {
+    refresh(): Promise<RuntimeObservation | undefined>;
+}
+type SpawnFn = typeof nodeSpawn;
+/**
+ * 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 declare function claudeQuotaProvider(options: {
+    binary: string;
+    spawnImpl?: SpawnFn;
+    timeoutMs?: number;
+}): QuotaProvider;
+/** Codex's `account/rateLimits/read` over `codex app-server` stdio JSON-RPC. */
+export declare function codexQuotaProvider(options: {
+    binary: string;
+    clientVersion: string;
+    spawnImpl?: SpawnFn;
+    timeoutMs?: number;
+}): QuotaProvider;
+export interface RuntimeStatusReporterOptions {
+    /** `claude_code` | `codex` | `goose` | `custom`. */
+    runtime: string;
+    /** Idle quota source; omit for a runtime that has none. */
+    provider?: QuotaProvider;
+    /** A run is executing — it will bring fresh numbers, so don't probe beside it. */
+    isBusy?: () => boolean;
+    now?: () => number;
+    /** Timer seam for tests. Returns a cancel function. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+    intervalMs?: number;
+    log?: (line: string) => void;
+}
+/**
+ * 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 declare class RuntimeStatusReporter {
+    private readonly options;
+    private readonly now;
+    private readonly schedule;
+    private state;
+    private quotaObservedAt;
+    private send;
+    private lastSentAt;
+    private cancelPending;
+    private cancelTick;
+    private refreshing;
+    constructor(options: RuntimeStatusReporterOptions);
+    /** Merge what a source learned. Absent fields keep their previous value. */
+    observe(observation: RuntimeObservation | undefined): void;
+    /** The model to report on a run's completion, when nothing more specific is known. */
+    model(): string | undefined;
+    /** Start reporting on a socket that advertised the feature. */
+    attach(send: (frame: Record<string, unknown>) => void): void;
+    /** Stop reporting — the socket is gone. */
+    detach(): void;
+    /** The frame as it would be sent now. */
+    frame(): Record<string, unknown>;
+    /** Routine tick: refresh idle quota if it is stale, send, and re-arm. */
+    private tick;
+    private refresh;
+    /** Send now if spacing allows, else once it does. Coalesces. */
+    private sendSoon;
+    private flush;
+}
+export {};