@prohost/cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.6.0
+
+ProhostAI can now show which runtime, model and machine a paired AI employee
+runs on, and how much of the operator's Claude or Codex subscription is left.
+
+- **A `runtime_status` frame.** When — and only when — the server lists
+  `runtime_status` in `auth_ok.features`, `agent run` reports its runtime
+  (`claude_code`, `codex`, `goose` or `custom`), the agent CLI's version, the
+  model, the plan (`Claude Max`, `ChatGPT Pro`, …) and the 5-hour and weekly
+  capacity windows as percentages with reset times. It is sent on connect,
+  every five minutes, and promptly when the model or plan changes or capacity
+  crosses 75% / 100% — never more than once per 31 s. An older server gets
+  nothing new.
+- **Your login never leaves this machine, and the CLI never reads it.** The
+  numbers come from the agent CLI answering with its own credentials: Claude
+  Code's own `stream-json` output (`system/init`, `rate_limit_event`) and, when
+  idle, its `get_usage` control request (no model turn, no quota spent); Codex's
+  per-thread rollout file under `$CODEX_HOME/sessions` and, when idle,
+  `codex app-server`'s `account/rateLimits/read`. The Claude Code keychain item
+  and `~/.codex/auth.json` are never opened, and account ids, emails and org
+  names are never forwarded. Anything unknown is omitted, never sent as zero.
+- **The model on completion.** `POST /v1/agent-runs/{id}/complete` now carries
+  `model` when the harness knows it (Claude Code's `system/init.model`, Codex's
+  rollout `turn_context.model`), so a reply can say which model wrote it. A
+  plain `--exec` command's completion body is unchanged.
+
 ## 0.5.0
 
 A paired agent can no longer sit on a dead socket believing it is connected.

package/README.md

@@ -428,6 +428,20 @@ your agent a second time. That matters because your agent holds a credential:
 a second execution could file the same task or send the same email again, which
 no amount of message deduplication would undo.
 
+### What ProhostAI sees about your runtime
+
+When the server supports it, `agent run` reports which runtime it drives
+(Claude Code, Codex, goose or a custom command), that CLI's version, the model,
+your plan's name, and how much of your 5-hour and weekly capacity is used, as
+percentages with reset times. ProhostAI shows this next to the AI employee.
+
+Your Claude or Codex login never leaves your machine, and `prohost` never reads
+it: the numbers come from the agent CLI's own output (Claude Code's
+`stream-json` events, Codex's session rollout files) or from asking the
+unmodified CLI through its own protocol (`get_usage`,
+`codex app-server`), which answers with its own login. Account ids, emails and
+org names are never sent.
+
 ### The trust model — read this once
 
 `agent run` is a standing instruction to execute a command on your machine when

package/dist/agent/api.d.ts

@@ -129,10 +129,13 @@ export declare function heartbeatRun(options: ApiOptions, path: string, progress
  * A ``409`` is reported as success: it means the run already reached a terminal
  * state (a redelivery we raced, or the 2h stale-run sweeper got there first).
  * Treating that as a failure would only produce noise about work that is done.
+ *
+ * ``model`` is the model id the run used, when the harness knows it. Omitted
+ * otherwise, so a plain ``--exec`` command's completion body is unchanged.
  */
 export declare function completeRun(options: ApiOptions, path: string, outcome: {
     ok: true;
 } | {
     ok: false;
     error: string;
-}): Promise<ApiResult>;
+}, model?: string): Promise<ApiResult>;

package/dist/agent/api.js

@@ -10,7 +10,7 @@
  * `completion.path`), which is why these take a path rather than building one.
  */
 import { USER_AGENT } from '../version.js';
-import { MAX_ERROR_CHARS, MAX_PROGRESS_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
+import { MAX_ERROR_CHARS, MAX_MODEL_CHARS, MAX_PROGRESS_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
 /** Deadline for the cheap calls — a heartbeat answers in milliseconds. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 /**
@@ -170,11 +170,16 @@ export async function heartbeatRun(options, path, progress) {
  * A ``409`` is reported as success: it means the run already reached a terminal
  * state (a redelivery we raced, or the 2h stale-run sweeper got there first).
  * Treating that as a failure would only produce noise about work that is done.
+ *
+ * ``model`` is the model id the run used, when the harness knows it. Omitted
+ * otherwise, so a plain ``--exec`` command's completion body is unchanged.
  */
-export async function completeRun(options, path, outcome) {
+export async function completeRun(options, path, outcome, model) {
     const body = outcome.ok
         ? { status: RUN_STATUS_SUCCEEDED }
         : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
+    if (model)
+        body.model = model.slice(0, MAX_MODEL_CHARS);
     const result = await post(options, path, body, undefined, false, SEND_TIMEOUT_MS);
     if (result.status === 409)
         return { ...result, ok: true };

package/dist/agent/claude.d.ts

@@ -15,6 +15,7 @@
  * happens and still completes. These are enhancements that must fail soft.
  */
 import { MCP_SERVER_NAME } from './mcp.js';
+import type { RuntimeObservation } from './runtime_status.js';
 export { MCP_SERVER_NAME };
 /**
  * What goes to `--allowedTools` so the ProhostAI tools are callable.
@@ -151,6 +152,12 @@ export interface ClaudeStream {
     activity(): string | undefined;
     /** The tail of the last thing the agent wrote, for a run that was killed. */
     salvage(): string | undefined;
+    /**
+     * Model, Claude Code version and capacity windows the stream announced —
+     * `system/init.{model, claude_code_version}` and the last
+     * `rate_limit_event`. Fields the stream never mentioned are absent.
+     */
+    observed(): RuntimeObservation;
     /**
      * The turn's outcome. ``stdout`` is the complete captured output, used only
      * when the stream held no `result` event — a crashed binary, a login prompt,

package/dist/agent/claude.js

@@ -18,6 +18,7 @@ import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { prohostHome } from './credentials.js';
 import { MCP_SERVER_NAME } from './mcp.js';
+import { fromClaudeRateLimitInfo } from './runtime_status.js';
 import { SHELL_CONTROL_OPERATORS, shellQuote } from './shell.js';
 export { MCP_SERVER_NAME };
 /**
@@ -315,10 +316,21 @@ export function readClaudeStream() {
     let lastActivity;
     let lastText;
     let result;
+    const observed = {};
     const handle = (line) => {
         const event = asObject(line);
         if (!event)
             return;
+        if (event.type === 'system' && event.subtype === 'init') {
+            observed.model = text(event.model) ?? observed.model;
+            observed.runtime_version = text(event.claude_code_version) ?? observed.runtime_version;
+        }
+        else if (event.type === 'rate_limit_event') {
+            // Last one wins; absent for API-key / Bedrock / Vertex sessions.
+            const windows = fromClaudeRateLimitInfo(event.rate_limit_info);
+            if (windows.length > 0)
+                observed.quota_windows = windows;
+        }
         // Present on the `system`/`init` event, and repeated on most others. Taken
         // from whichever arrives first — they all name the same session.
         if (!session)
@@ -359,6 +371,7 @@ export function readClaudeStream() {
         },
         sessionId: () => session,
         activity: () => lastActivity,
+        observed: () => ({ ...observed }),
         salvage: () => {
             const trimmed = lastText?.trim();
             if (!trimmed)

package/dist/agent/contract.d.ts

@@ -29,6 +29,8 @@ export declare const RUN_STATUS_SUCCEEDED = "succeeded";
 export declare const RUN_STATUS_FAILED = "failed";
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export declare const MAX_ERROR_CHARS = 1000;
+/** Server-side cap on the `model` field of a completion (`MAX_MODEL_CHARS`). */
+export declare const MAX_MODEL_CHARS = 100;
 /**
  * The completion `error` that means "a person asked for this run to stop".
  *

package/dist/agent/contract.js

@@ -29,6 +29,8 @@ export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export const RUN_STATUS_FAILED = 'failed';
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
+/** Server-side cap on the `model` field of a completion (`MAX_MODEL_CHARS`). */
+export const MAX_MODEL_CHARS = 100;
 /**
  * The completion `error` that means "a person asked for this run to stop".
  *

package/dist/agent/run.d.ts

@@ -25,6 +25,7 @@
 import type { spawn } from 'node:child_process';
 import WebSocket from 'ws';
 import type { AgentCredentials } from './credentials.js';
+import type { QuotaProvider } from './runtime_status.js';
 /**
  * Default ceiling on one agent invocation: none.
  *
@@ -131,6 +132,12 @@ export interface AgentRunOptions {
      * to {@link HEARTBEAT_LOG_INTERVAL_MS}; tests shorten it.
      */
     heartbeatLogIntervalMs?: number;
+    /**
+     * Where idle capacity numbers come from (see `runtime_status.ts`). Defaults
+     * to asking the detected agent CLI itself; `null` disables idle refresh.
+     * Tests inject a fake so no real `claude` / `codex` is spawned.
+     */
+    quotaProvider?: QuotaProvider | null;
 }
 export interface AgentRunMetrics {
     connections: number;

package/dist/agent/run.js

@@ -36,6 +36,7 @@ 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';
@@ -133,8 +134,8 @@ 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;
@@ -143,7 +144,7 @@ async function completeWithRetry(api, path, outcome, log, sleep) {
             return result;
         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;
 }
@@ -240,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 = '';
@@ -296,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.
@@ -574,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,
@@ -594,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.
@@ -704,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 {
@@ -787,7 +830,7 @@ 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 (${describeFailure(closed)})` +
                 `${closed.status !== 0 && closed.error ? ` ${closed.error}` : ''}`);
@@ -805,7 +848,7 @@ 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 (${describeFailure(completed)})` +
                 `${completed.status !== 0 && completed.error ? ` ${completed.error}` : ''}`);
@@ -833,7 +876,7 @@ 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 (${describeFailure(completed)})`);
             return 'unreported';
@@ -856,7 +899,7 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // 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: ${failure}` }, 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.
@@ -865,7 +908,7 @@ 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
@@ -914,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;
@@ -1001,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();
@@ -1102,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') {
@@ -1265,6 +1353,7 @@ 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 {};

package/dist/agent/runtime_status.js

@@ -0,0 +1,556 @@
+/**
+ * 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'],
+];
+/**
+ * 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 window = asObject(windows[key]);
+        const used = percent(window?.utilization, 1);
+        const at = isoTime(window?.resetsAt);
+        return used !== undefined && at ? [{ kind, used_percent: used, resets_at: at }] : [];
+    });
+}
+/** Windows from a `get_usage` control response (0–100, ISO strings). */
+export function fromClaudeGetUsage(usage) {
+    const record = asObject(usage);
+    if (record?.rate_limits_available !== true)
+        return [];
+    const limits = asObject(record.rate_limits) ?? {};
+    return CLAUDE_WINDOWS.flatMap(([key, kind]) => {
+        const window = asObject(limits[key]);
+        const used = percent(window?.utilization, 100);
+        const at = isoTime(window?.resets_at);
+        return used !== undefined && at ? [{ kind, used_percent: used, resets_at: at }] : [];
+    });
+}
+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 && used !== undefined && at ? [{ kind, used_percent: used, resets_at: 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) {
+    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 {
+            child = spawnImpl(command, args, { stdio: ['pipe', 'pipe', 'ignore'] });
+        }
+        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),
+    };
+}
+/** 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),
+    };
+}
+// ── 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;
+}
+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;
+    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 = 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();
+    }
+    /** 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();
+        // A window whose reset has passed describes a period that is over.
+        const windows = (this.state.quota_windows ?? []).filter((w) => Date.parse(w.resets_at) > 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(),
+        };
+    }
+    /** 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;
+        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;
+            this.refreshing = (provider ? provider.refresh() : Promise.resolve(undefined))
+                .then((observed) => {
+                // `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(() => {
+                this.refreshing = undefined;
+            });
+        }
+        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)}`);
+        }
+    }
+}

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.5.0";
+export declare const CLI_VERSION = "0.6.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.5.0";
+export declare const USER_AGENT = "prohost-cli/0.6.0";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.5.0';
+export const CLI_VERSION = '0.6.0';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",