@bridge4dev/runner 0.55.1 → 0.57.0

package/dist/adapters/claude-usage.d.ts

@@ -53,13 +53,134 @@ export declare function parseUsageText(text: string, now?: Date): UsageRow[];
  * reworded CLI must never be able to move a wake-up — therefore still holds.
  * `claude-usage.test.ts` pins it.
  */
-export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[]): AgentRateLimitWindow[];
+export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[], options?: {
+    onlyFillGaps?: boolean;
+}): AgentRateLimitWindow[];
+/**
+ * How long the probe may run before it is written off (#390).
+ *
+ * Ninety seconds, and the number is measured rather than chosen. `/usage` was
+ * 3.7s when the old ceiling of 20s was set on 2026-08-15; it is not that
+ * command any more. Since then the CLI prints «What's contributing to your
+ * limits usage?», computed from the machine's OWN session history — 1.4 GB and
+ * ~4900 files on the busiest dev server — so the work grows with the history
+ * and the load rather than with anything we ask for. It is also CPU-bound, not
+ * network-bound: 23.7s wall against 32s of CPU.
+ *
+ * Measured 2026-09-07 on a six-core box under load 4-15:
+ *
+ *   plain, /tmp                 17.7s
+ *   plain, a project checkout   19.0 20.8 22.2 24.0 27.5s
+ *   in the reporter's own runs  15.0 15.3 16.5 17.1 20.8 23.7 28.3s
+ *
+ * So 20s was not a margin, it was the middle of the distribution, and a failed
+ * probe was an ordinary event rather than an exception. The cost of waiting is
+ * nil — the probe is free (0 tokens, 0 turns, 0 dollars, verified 2026-08-15),
+ * runs in the background, and since #390 there is at most ONE of it per
+ * machine. The cost of NOT waiting was the panel losing two of its three rows.
+ */
+export declare const USAGE_PROBE_TIMEOUT_MS = 20000;
+/**
+ * How long a successful reading is believed — the throttle for the whole box.
+ *
+ * Three minutes, unchanged from when this was a per-session throttle. What
+ * changed is the scope: five sessions used to keep five independent clocks and
+ * run five copies of a 20-second process, all of them measuring the same
+ * account. The windows on screen are five hours and a week; three minutes is
+ * already far finer than they move.
+ */
+export declare const USAGE_CACHE_MS: number;
+/**
+ * How long we wait before retrying after a probe that produced nothing.
+ *
+ * Shorter than the success interval, because a machine that has just failed
+ * once is the machine most worth asking again — but not so short that a box
+ * with no subscription at all (own API key, Bedrock, Vertex) spends its life
+ * spawning CLIs. One at a time is guaranteed by the in-flight join below, so
+ * the worst case is a single ~90s process a minute apart, not a pile.
+ */
+export declare const USAGE_FAILURE_COOLDOWN_MS: number;
+export type UsageProbeRunner = (binary: string, cwd: string) => Promise<string | null>;
 /**
  * Run `/usage` in a throwaway process and return what it printed.
  *
  * `--output-format text` rather than the stream: we want the rendering, and the
  * JSON wrapper would only have to be unwrapped again. Never throws — a probe
  * that fails is a percentage we do not show, not a session that breaks.
+ *
+ * Three things about HOW it is run, all of them measured (#390):
+ *
+ *  - `--strict-mcp-config` stops the CLI starting the project's MCP servers,
+ *    which a question about the plan has no use for. Measured in a project
+ *    checkout: 13.8 and 18.5s with the flag against 20.8 and 22.2s without, and
+ *    the output is identical — the same three rows. It narrows the spread; it
+ *    does not remove it, which is why the ceiling above moved as well.
+ *  - the process is niced like every other thing we spawn for an agent. It used
+ *    to be the one child of the runner that was neither caged nor renice'd, and
+ *    at a 90-second ceiling that would have made it a real neighbour on a busy
+ *    box (#387 is the same lesson from the other side).
+ *  - stdin is closed. `-p` does not read it, but `agent-versions.ts` was bitten
+ *    by a CLI that did, and a probe that hangs on an open pipe would now hang
+ *    for a minute and a half. (Not the cause of the slowness here: measured
+ *    with and without, the times overlap.)
+ *
+ * `--bare` was measured too and rejected: it finishes in 2.5s and prints no
+ * usage at all, because it reads neither OAuth nor the keychain — on the
+ * subscription this whole file exists to report, it has nothing to say.
  */
 export declare function probeUsageText(binary: string, cwd: string, timeoutMs?: number): Promise<string | null>;
+/** A reading of the machine's plan, with the moment it was taken. */
+export interface UsageReading {
+    rows: UsageRow[];
+    measuredAtMs: number;
+}
+export declare function setUsageProbeRunner(run: UsageProbeRunner | null): void;
+/** Forget everything measured. For tests, and for a re-login that changes account. */
+export declare function invalidateUsageCache(): void;
+/**
+ * What the machine last read, WITHOUT starting a measurement.
+ *
+ * The reason this exists is the defect #390 was actually about. A session's
+ * window map starts empty, and its first `rate_limit_event` arrives 12-28
+ * seconds before any probe of its own could answer. That event describes ONE
+ * window, the snapshot built from it therefore has one row, and the API stores
+ * the newest snapshot as the state of the whole machine — so a session that had
+ * only just started would overwrite three good rows with one, every time, on a
+ * machine with a single session as much as on a busy one.
+ *
+ * Seeding from the box's last reading closes that: a new session publishes what
+ * the machine already knows in its very first snapshot, and the probe that
+ * follows only refreshes it.
+ */
+export declare function lastUsageRows(): UsageReading | null;
+export interface ReadUsageOptions {
+    binary: string;
+    /**
+     * Where to run it. Defaults to {@link probeDir} — a directory of the runner's
+     * own, never a shared one and never a session's working copy. The reading is
+     * identical in every directory (verified), so the choice is made entirely on
+     * safety and tidiness: see `probeDir` for why a shared directory is a hole,
+     * and note that `-p` leaves a transcript behind, which in a checkout would
+     * grow the very local history that makes `/usage` slow.
+     */
+    cwd?: string;
+    /** Fixed clock for tests; both the throttle and the stamp read it. */
+    now?: number;
+}
+/**
+ * The machine's plan percentages — measured at most once per {@link USAGE_CACHE_MS}.
+ *
+ * Two guards, and they answer different questions. The throttle stops us
+ * measuring again too SOON; the in-flight join stops us measuring twice AT
+ * ONCE. Only the second one fixes the pile-up this change is about: five
+ * sessions reaching a turn end together used to start five copies of a
+ * 20-second CPU-bound process, each of which made the others slower — the same
+ * self-sustaining shape `gitops.ts` writes about for `git_status`.
+ *
+ * Always resolves to the best reading we have, never to «nothing» just because
+ * this attempt failed. A stale true number beats an empty panel — and the
+ * reading carries the moment it was TAKEN, so the caller can tell a fresh
+ * measurement from the one it already folded in (see {@link measuredAtMs}).
+ */
+export declare function readUsageRows(options: ReadUsageOptions): Promise<UsageReading | null>;
 //# sourceMappingURL=claude-usage.d.ts.map

package/dist/adapters/claude-usage.js

@@ -1,5 +1,9 @@
 import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { log } from '../log.js';
+import { stateDir } from '../paths.js';
+import { lowerPriority } from '../process-priority.js';
 /**
  * How much of the plan is spent — read from the CLI's own `/usage` (#279).
  *
@@ -191,7 +195,7 @@ export function parseUsageText(text, now = new Date()) {
  * reworded CLI must never be able to move a wake-up — therefore still holds.
  * `claude-usage.test.ts` pins it.
  */
-export function applyUsagePercentages(windows, rows) {
+export function applyUsagePercentages(windows, rows, options = {}) {
     // Keyed by window AND label: a per-model weekly row is its own line, not an
     // overwrite of the plan-wide one.
     const id = (window) => `${window.key}:${window.label ?? ''}`;
@@ -202,7 +206,19 @@ export function applyUsagePercentages(windows, rows) {
         merged.set(key, {
             key: row.key,
             windowMinutes: existing?.windowMinutes ?? (row.key === 'five_hour' ? 300 : 10_080),
-            usedPercent: row.percent,
+            // `onlyFillGaps` is what a STALE reading gets (#390, QA MAJOR). The
+            // reading belongs to the machine and is handed to a session at the end of
+            // every turn; meanwhile a `rate_limit_event` may have put a newer
+            // percentage into this very window. Overwriting it rolled 95% back to the
+            // 60% measured three minutes earlier, once per turn, in both directions
+            // (too low inside a window, too high just after it resets). A fresh
+            // measurement still wins outright — it is the authority for percentages,
+            // which is the whole premise of #279.
+            usedPercent: options.onlyFillGaps &&
+                existing?.usedPercent !== null &&
+                existing?.usedPercent !== undefined
+                ? existing.usedPercent
+                : row.percent,
             // Event first, text second, nothing third. See the docblock above for why
             // this ordering is the whole safety argument.
             resetsAt: existing?.resetsAt ?? row.resetsAt ?? null,
@@ -213,23 +229,310 @@ export function applyUsagePercentages(windows, rows) {
     return [...merged.values()].sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER) ||
         (a.label ?? '').localeCompare(b.label ?? ''));
 }
+/**
+ * How long the probe may run before it is written off (#390).
+ *
+ * Ninety seconds, and the number is measured rather than chosen. `/usage` was
+ * 3.7s when the old ceiling of 20s was set on 2026-08-15; it is not that
+ * command any more. Since then the CLI prints «What's contributing to your
+ * limits usage?», computed from the machine's OWN session history — 1.4 GB and
+ * ~4900 files on the busiest dev server — so the work grows with the history
+ * and the load rather than with anything we ask for. It is also CPU-bound, not
+ * network-bound: 23.7s wall against 32s of CPU.
+ *
+ * Measured 2026-09-07 on a six-core box under load 4-15:
+ *
+ *   plain, /tmp                 17.7s
+ *   plain, a project checkout   19.0 20.8 22.2 24.0 27.5s
+ *   in the reporter's own runs  15.0 15.3 16.5 17.1 20.8 23.7 28.3s
+ *
+ * So 20s was not a margin, it was the middle of the distribution, and a failed
+ * probe was an ordinary event rather than an exception. The cost of waiting is
+ * nil — the probe is free (0 tokens, 0 turns, 0 dollars, verified 2026-08-15),
+ * runs in the background, and since #390 there is at most ONE of it per
+ * machine. The cost of NOT waiting was the panel losing two of its three rows.
+ */
+export const USAGE_PROBE_TIMEOUT_MS = 20_000;
+/**
+ * How long a successful reading is believed — the throttle for the whole box.
+ *
+ * Three minutes, unchanged from when this was a per-session throttle. What
+ * changed is the scope: five sessions used to keep five independent clocks and
+ * run five copies of a 20-second process, all of them measuring the same
+ * account. The windows on screen are five hours and a week; three minutes is
+ * already far finer than they move.
+ */
+export const USAGE_CACHE_MS = 3 * 60 * 1_000;
+/**
+ * How long we wait before retrying after a probe that produced nothing.
+ *
+ * Shorter than the success interval, because a machine that has just failed
+ * once is the machine most worth asking again — but not so short that a box
+ * with no subscription at all (own API key, Bedrock, Vertex) spends its life
+ * spawning CLIs. One at a time is guaranteed by the in-flight join below, so
+ * the worst case is a single ~90s process a minute apart, not a pile.
+ */
+export const USAGE_FAILURE_COOLDOWN_MS = 60 * 1_000;
+/** At most one line per reason per this long. See `warnProbeFailure`. */
+const WARN_THROTTLE_MS = 15 * 60 * 1_000;
+/**
+ * A probe that failed is worth SAYING (#390).
+ *
+ * It used to be `log.debug` while the runner logs at `info`, so the one thing
+ * that explains a panel losing two of its three rows was invisible from
+ * outside: the percentages simply stopped, and every other signal said the
+ * machine was healthy.
+ *
+ * Throttled per reason rather than said every time, because the failure that
+ * repeats forever is the boring one — a machine with no subscription probes,
+ * fails, and would otherwise write a line into journald every minute until the
+ * log is useless. The first line of a new failure is the one that carries the
+ * information; the hundredth only buries it.
+ */
+const warnedAtMs = new Map();
+function warnProbeFailure(error, timeoutMs, now) {
+    const killed = typeof error === 'object' &&
+        error !== null &&
+        'killed' in error &&
+        error.killed === true;
+    const reason = killed ? 'timeout' : 'error';
+    const last = warnedAtMs.get(reason);
+    if (last !== undefined && now - last < WARN_THROTTLE_MS) {
+        log.debug('claude: /usage probe failed again', { reason, error: String(error) });
+        return;
+    }
+    warnedAtMs.set(reason, now);
+    log.warn(killed
+        ? 'claude: /usage did not finish in time — plan percentages will go stale'
+        : 'claude: /usage could not be read — plan percentages will go stale', { reason, timeoutMs, error: String(error) });
+}
 /**
  * Run `/usage` in a throwaway process and return what it printed.
  *
  * `--output-format text` rather than the stream: we want the rendering, and the
  * JSON wrapper would only have to be unwrapped again. Never throws — a probe
  * that fails is a percentage we do not show, not a session that breaks.
+ *
+ * Three things about HOW it is run, all of them measured (#390):
+ *
+ *  - `--strict-mcp-config` stops the CLI starting the project's MCP servers,
+ *    which a question about the plan has no use for. Measured in a project
+ *    checkout: 13.8 and 18.5s with the flag against 20.8 and 22.2s without, and
+ *    the output is identical — the same three rows. It narrows the spread; it
+ *    does not remove it, which is why the ceiling above moved as well.
+ *  - the process is niced like every other thing we spawn for an agent. It used
+ *    to be the one child of the runner that was neither caged nor renice'd, and
+ *    at a 90-second ceiling that would have made it a real neighbour on a busy
+ *    box (#387 is the same lesson from the other side).
+ *  - stdin is closed. `-p` does not read it, but `agent-versions.ts` was bitten
+ *    by a CLI that did, and a probe that hangs on an open pipe would now hang
+ *    for a minute and a half. (Not the cause of the slowness here: measured
+ *    with and without, the times overlap.)
+ *
+ * `--bare` was measured too and rejected: it finishes in 2.5s and prints no
+ * usage at all, because it reads neither OAuth nor the keychain — on the
+ * subscription this whole file exists to report, it has nothing to say.
  */
-export function probeUsageText(binary, cwd, timeoutMs = 20_000) {
+export function probeUsageText(binary, cwd, timeoutMs = USAGE_PROBE_TIMEOUT_MS) {
     return new Promise((resolve) => {
-        execFile(binary, ['-p', '/usage', '--output-format', 'text'], { cwd, timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        let settled = false;
+        const finish = (text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(watchdog);
+            resolve(text);
+        };
+        const child = execFile(binary, ['--strict-mcp-config', '-p', '/usage', '--output-format', 'text'], {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer: 1024 * 1024,
+            // SIGTERM can be trapped, SIGKILL cannot. A probe that ignored the
+            // polite signal would never call this callback, and since the cache
+            // above clears its in-flight slot only when the callback runs, ONE such
+            // process would stop the machine ever measuring again (QA-390 MINOR).
+            // Nothing here needs a graceful exit: it reads and prints.
+            killSignal: 'SIGKILL',
+        }, (error, stdout) => {
             if (error) {
-                log.debug('claude: /usage probe failed', { error: String(error) });
-                resolve(null);
+                warnProbeFailure(error, timeoutMs, Date.now());
+                finish(null);
                 return;
             }
-            resolve(stdout);
+            finish(stdout);
         });
+        // Belt as well as braces: the callback also waits for the output streams to
+        // close, and a grandchild holding the pipe can keep them open after the CLI
+        // itself is gone. This promise must settle no matter what, because the
+        // in-flight slot is released from it.
+        const watchdog = setTimeout(() => {
+            log.warn('claude: /usage probe left its pipes open — giving up on it', { timeoutMs });
+            finish(null);
+        }, timeoutMs + 15_000);
+        watchdog.unref?.();
+        child.stdin?.end();
+        lowerPriority(child.pid);
+    });
+}
+/**
+ * Where the probe runs — a directory only this runner can write to.
+ *
+ * NOT a shared directory, and this is a security property rather than a
+ * preference (QA-390 BLOCKER). For Claude Code the working directory is the
+ * root of a project's SETTINGS: it reads `<cwd>/.claude/settings.json`, and
+ * that file may define hooks — commands the CLI then runs. `-p` asks for no
+ * trust confirmation at all, verified live. The runner is root by default
+ * (`--user <name>` is opt-in), so a world-writable `cwd` means any local user
+ * can drop `/tmp/.claude/settings.json` and have it executed as root within
+ * three minutes. Demonstrated end to end during review: a non-root user's hook
+ * wrote `uid=0(root)`.
+ *
+ * Before this ticket the probe inherited the session's own working copy, which
+ * is inside the project's trust boundary; `os.tmpdir()` was the accident that
+ * this comment exists to prevent someone re-introducing.
+ *
+ * Second, smaller reason for a directory of our own: with `cwd` on a busy
+ * `/tmp` the CLI walks it (`rg --files --hidden`) — 162,595 files and 1.16s on
+ * this machine, spent for nothing.
+ */
+function probeDir() {
+    const dir = path.join(stateDir(), 'usage-probe');
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return dir;
+    }
+    catch (error) {
+        // No private directory, no probe. Falling back to a shared one is exactly
+        // the hole above, and a missing percentage is a far smaller loss.
+        log.warn('claude: no private directory for the /usage probe — skipping it', {
+            dir,
+            error: String(error),
+        });
+        return null;
+    }
+}
+/**
+ * The last reading that SUCCEEDED. A failed probe never clears it.
+ *
+ * This is the whole difference between «we could not measure just now» and «we
+ * know nothing»: the first must keep showing the last true numbers, and only
+ * the second is allowed to leave the panel empty.
+ */
+let lastRows = null;
+/**
+ * When {@link lastRows} was MEASURED — not when it was last handed out.
+ *
+ * Load-bearing rather than diagnostic (QA-390 MAJOR). A reading may be up to
+ * {@link USAGE_CACHE_MS} old, and it is handed to a session at the end of every
+ * turn. Meanwhile a `rate_limit_event` can have put a NEWER percentage into
+ * that session's window, and `applyUsagePercentages` overwrites percentages
+ * without asking how old they are — so an unqualified reading rolled 95% back
+ * to the 60% the machine measured three minutes ago, on every turn. The stamp
+ * is what lets the adapter tell «this is news» from «this is what you already
+ * folded in».
+ */
+let measuredAtMs = 0;
+/** When the last attempt FINISHED, successful or not — the throttle's clock. */
+let attemptedAtMs = 0;
+/** Did that attempt produce rows? Decides which of the two intervals applies. */
+let lastAttemptOk = false;
+/** The probe currently running, so overlapping callers share it. */
+let inFlight = null;
+/**
+ * The probe the cache runs. Replaced only by tests.
+ *
+ * A module-level seat rather than an argument, because the caller that needs it
+ * is a session buried inside the adapter and threading a test-only parameter
+ * through 126 constructions of `ClaudeAdapter` would put it on the product's
+ * own seam. It has to exist at all for a sharper reason than tidiness: until
+ * #390 the only thing keeping the adapter's own test file from spawning a real
+ * `claude` on this machine — which also hosts production — was that its fake
+ * `cwd` did not exist, and this change stopped the probe using the session's
+ * `cwd` at all.
+ */
+let probeRunner = (binary, cwd) => probeUsageText(binary, cwd);
+export function setUsageProbeRunner(run) {
+    probeRunner = run ?? ((binary, cwd) => probeUsageText(binary, cwd));
+}
+/** Forget everything measured. For tests, and for a re-login that changes account. */
+export function invalidateUsageCache() {
+    lastRows = null;
+    measuredAtMs = 0;
+    attemptedAtMs = 0;
+    lastAttemptOk = false;
+    inFlight = null;
+    warnedAtMs.clear();
+}
+/**
+ * What the machine last read, WITHOUT starting a measurement.
+ *
+ * The reason this exists is the defect #390 was actually about. A session's
+ * window map starts empty, and its first `rate_limit_event` arrives 12-28
+ * seconds before any probe of its own could answer. That event describes ONE
+ * window, the snapshot built from it therefore has one row, and the API stores
+ * the newest snapshot as the state of the whole machine — so a session that had
+ * only just started would overwrite three good rows with one, every time, on a
+ * machine with a single session as much as on a busy one.
+ *
+ * Seeding from the box's last reading closes that: a new session publishes what
+ * the machine already knows in its very first snapshot, and the probe that
+ * follows only refreshes it.
+ */
+export function lastUsageRows() {
+    return lastRows ? { rows: lastRows, measuredAtMs } : null;
+}
+/**
+ * The machine's plan percentages — measured at most once per {@link USAGE_CACHE_MS}.
+ *
+ * Two guards, and they answer different questions. The throttle stops us
+ * measuring again too SOON; the in-flight join stops us measuring twice AT
+ * ONCE. Only the second one fixes the pile-up this change is about: five
+ * sessions reaching a turn end together used to start five copies of a
+ * 20-second CPU-bound process, each of which made the others slower — the same
+ * self-sustaining shape `gitops.ts` writes about for `git_status`.
+ *
+ * Always resolves to the best reading we have, never to «nothing» just because
+ * this attempt failed. A stale true number beats an empty panel — and the
+ * reading carries the moment it was TAKEN, so the caller can tell a fresh
+ * measurement from the one it already folded in (see {@link measuredAtMs}).
+ */
+export function readUsageRows(options) {
+    const now = options.now ?? Date.now();
+    const interval = lastAttemptOk ? USAGE_CACHE_MS : USAGE_FAILURE_COOLDOWN_MS;
+    if (attemptedAtMs !== 0 && now - attemptedAtMs < interval) {
+        return Promise.resolve(lastUsageRows());
+    }
+    if (inFlight)
+        return inFlight;
+    const cwd = options.cwd ?? probeDir();
+    if (cwd === null)
+        return Promise.resolve(lastUsageRows());
+    const pending = probeRunner(options.binary, cwd)
+        .then((text) => {
+        const rows = text ? parseUsageText(text) : [];
+        attemptedAtMs = options.now ?? Date.now();
+        lastAttemptOk = rows.length > 0;
+        // Zero rows is not an answer worth keeping: it means the wording moved or
+        // the CLI said nothing, and the previous true reading is still the best
+        // thing we have to show.
+        if (rows.length > 0) {
+            lastRows = rows;
+            measuredAtMs = attemptedAtMs;
+        }
+        return lastUsageRows();
+    })
+        .catch((error) => {
+        // `probeUsageText` resolves rather than rejects, so this is a seat that
+        // threw or a parser that did — either way the reading is unchanged.
+        log.debug('claude: /usage probe threw', { error: String(error) });
+        attemptedAtMs = options.now ?? Date.now();
+        lastAttemptOk = false;
+        return lastUsageRows();
+    })
+        .finally(() => {
+        inFlight = null;
     });
+    inFlight = pending;
+    return pending;
 }
 //# sourceMappingURL=claude-usage.js.map

package/dist/adapters/claude.js

@@ -10,10 +10,8 @@ import { cageSpawn, memoryDeathSentence, releaseSessionScope } from '../session-
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
-import { applyUsagePercentages, parseUsageText, probeUsageText } from './claude-usage.js';
+import { applyUsagePercentages, lastUsageRows, readUsageRows } from './claude-usage.js';
 import { claudeExecutableOption, sessionClaudePath } from '../agent-binary.js';
-/** How often `/usage` may be read. Free, but still a process. */
-const USAGE_PROBE_INTERVAL_MS = 3 * 60 * 1000;
 /** Same 2KB the SDK keeps: enough for the CLI's last words, not a log sink. */
 const STDERR_TAIL_LIMIT = 2048;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -832,8 +830,6 @@ class ClaudeSession {
     rateLimitsAvailable = false;
     /** A refusal seen since the last turn ended, waiting to be reported with it. */
     limitBlockPending = false;
-    /** When `/usage` was last read, so a busy session does not spawn a process a second. */
-    usageProbedAt = 0;
     /**
      * The one key the window map is written under, from every source.
      *
@@ -870,41 +866,85 @@ class ClaudeSession {
         return providerName === 'five_hour' || providerName === 'seven_day';
     }
     /**
-     * Read the percentages out of the CLI's own `/usage` (#279).
+     * Read the percentages out of the CLI's own `/usage` (#279, #390).
      *
-     * Fire-and-forget, throttled, and free — a local command, not a request
-     * (probe 2026-08-15: zero tokens, zero turns, zero dollars). The live event
-     * gives us the clock and almost never the number; this gives the number and
-     * never touches the clock.
+     * Fire-and-forget and free — a local command, not a request (probe
+     * 2026-08-15: zero tokens, zero turns, zero dollars). The live event gives us
+     * the clock and almost never the number; this gives the number and never
+     * touches the clock.
+     *
+     * Two steps, and the FIRST one is the fix for #390. The reading belongs to
+     * the machine, not to this session — one account, one set of numbers — so
+     * before anything is measured we take what the box already knows. Without it
+     * a session that started thirty seconds ago publishes a snapshot built from
+     * its single `rate_limit_event`, and because the API stores the newest
+     * snapshot as the state of the whole server, that one row replaced three good
+     * ones. Seeding costs nothing, needs no binary, and is why raising the
+     * timeout alone would not have fixed the report.
+     *
+     * The second step refreshes it. The throttle, the ceiling and the guarantee
+     * that only one probe runs per machine all live in `readUsageRows`.
      */
     refreshUsage() {
         if (this.stopped)
             return;
-        if (this.usageProbedAt !== 0 && Date.now() - this.usageProbedAt < USAGE_PROBE_INTERVAL_MS) {
-            return;
-        }
+        if (this.absorbUsageReading(lastUsageRows()))
+            this.emitRateLimits();
         const binary = sessionClaudePath();
         if (!binary)
             return;
-        this.usageProbedAt = Date.now();
-        void probeUsageText(binary, this.spec.cwd)
-            .then((text) => {
-            if (!text || this.stopped)
+        void readUsageRows({ binary })
+            .then((reading) => {
+            if (this.stopped)
                 return;
-            const rows = parseUsageText(text);
-            if (rows.length === 0)
-                return;
-            // A percentage proves a plan as surely as the event does.
-            this.rateLimitsAvailable = true;
-            const merged = applyUsagePercentages([...this.rateLimitWindows.values()], rows);
-            this.rateLimitWindows.clear();
-            for (const window of merged) {
-                this.rateLimitWindows.set(ClaudeSession.windowKey(window.key, window.label), window);
-            }
-            this.emitRateLimits();
+            if (this.absorbUsageReading(reading))
+                this.emitRateLimits();
         })
             .catch((error) => log.debug('claude: usage probe failed', { error: String(error) }));
     }
+    /** The measurement already folded in, so an older one cannot undo a newer event. */
+    usageAppliedAtMs = 0;
+    /**
+     * Fold a `/usage` reading into this session's window map.
+     *
+     * The reading belongs to the MACHINE and arrives at both ends of every turn,
+     * so most of the time it is something this session has already applied. That
+     * distinction is load-bearing rather than an optimisation (found by review):
+     * between two turns a `rate_limit_event` can put a NEWER percentage into a
+     * window, and re-applying a three-minute-old measurement over it rolled 95%
+     * back to 60% — every turn, and in both directions, because usage only climbs
+     * inside a window and drops to nothing when it resets. The warning badge is
+     * driven off that number.
+     *
+     * So a reading we have not seen before is applied outright — it is the
+     * authority for percentages, which is #279's whole premise — and one we have
+     * only FILLS what is still missing.
+     *
+     * Returns whether anything actually moved, so a repeat costs no frame. The
+     * supervisor's level gate would drop the duplicate anyway, but the cheapest
+     * frame is the one never built.
+     */
+    absorbUsageReading(reading) {
+        if (!reading || reading.rows.length === 0)
+            return false;
+        const fresh = reading.measuredAtMs > this.usageAppliedAtMs;
+        const before = this.rateLimitsFingerprint();
+        // A percentage proves a plan as surely as the event does.
+        this.rateLimitsAvailable = true;
+        const merged = applyUsagePercentages([...this.rateLimitWindows.values()], reading.rows, {
+            onlyFillGaps: !fresh,
+        });
+        this.rateLimitWindows.clear();
+        for (const window of merged) {
+            this.rateLimitWindows.set(ClaudeSession.windowKey(window.key, window.label), window);
+        }
+        if (fresh)
+            this.usageAppliedAtMs = reading.measuredAtMs;
+        return this.rateLimitsFingerprint() !== before;
+    }
+    rateLimitsFingerprint() {
+        return JSON.stringify([this.rateLimitsAvailable, [...this.rateLimitWindows.values()]]);
+    }
     /** Read the flag and clear it: one refusal marks exactly one turn end. */
     consumeLimitBlock() {
         const blocked = this.limitBlockPending;

package/dist/adapters/questions.d.ts

@@ -28,6 +28,21 @@ export declare function mirrorOptions(questions: AgentQuestion[]): string[];
 export declare function answerValue(answer: AgentQuestionAnswer): string;
 /** One short line for the resolved card: «Postgres · Auth, Search». */
 export declare function answerSummary(answers: AgentQuestionAnswer[]): string;
+/**
+ * The same answer as something to SAY, when the card that asked is gone (#401).
+ *
+ * Not `answerSummary`: that one is a label for a resolved card, so it is
+ * clipped to an option's width and drops the notes. This is the person's reply
+ * being handed to the agent as an ordinary message, and nothing they typed may
+ * be shortened away on the path. The questions themselves cannot be named —
+ * their text lived in the process that asked and is gone with it — so the
+ * answer is given as the words it was made of, which is what the person
+ * actually chose.
+ *
+ * Empty when there is nothing in it: the caller uses that to tell «the reply
+ * was lost» from «there was no reply to lose».
+ */
+export declare function answersAsMessage(answers: AgentQuestionAnswer[]): string;
 /**
  * The «discuss instead» exit.
  *