@bridge4dev/runner 0.41.0 → 0.42.0

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

@@ -0,0 +1,34 @@
+import type { AgentRateLimitWindow } from './types.js';
+export interface UsageRow {
+    key: 'five_hour' | 'seven_day';
+    /** «Weekly · Fable» for a per-model row; absent for the plain ones. */
+    label: string | null;
+    percent: number;
+}
+/**
+ * Every percentage `/usage` printed, in the order it printed them.
+ *
+ * The per-model weekly rows («Current week (Fable): 0% used») are kept rather
+ * than dropped — owner's call, 2026-08-15: on a plan where one model has its
+ * own weekly allowance, «50% of the week» is only half the answer.
+ *
+ * Deliberately forgiving: a line we cannot read is skipped, never thrown over.
+ */
+export declare function parseUsageText(text: string): UsageRow[];
+/**
+ * Merge fresh percentages into the windows we already know about.
+ *
+ * The RESET TIME is never taken from here — whatever the event said stays. A
+ * window the event has not mentioned yet is created so the first probe is not
+ * wasted, with no clock on it until the event supplies one.
+ */
+export declare function applyUsagePercentages(windows: AgentRateLimitWindow[], rows: UsageRow[]): AgentRateLimitWindow[];
+/**
+ * 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.
+ */
+export declare function probeUsageText(binary: string, cwd: string, timeoutMs?: number): Promise<string | null>;
+//# sourceMappingURL=claude-usage.d.ts.map

package/dist/adapters/claude-usage.js

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { log } from '../log.js';
+/**
+ * How much of the plan is spent — read from the CLI's own `/usage` (#279).
+ *
+ * The machine-readable event (`rate_limit_event`) is the source of truth for
+ * WHEN a window resets, and the auto-pause clock is built on it alone. What it
+ * almost never carries is the PERCENTAGE, and that is the number the owner
+ * actually asked to see. `/usage` has it.
+ *
+ * Two things make this worth doing despite being text:
+ *
+ *  - it is FREE. Probed 2026-08-15: `total_cost_usd: 0`, `num_turns: 0`,
+ *    0 input and 0 output tokens, ~3.7s. It is a local command, not a request —
+ *    measuring the limit does not spend it.
+ *  - it can only ever affect a NUMBER ON A SCREEN. The reset time we schedule a
+ *    wake-up from never comes from here, so a wording change in a future CLI
+ *    costs us the percentage and nothing else. That is the exact failure #258
+ *    refused to accept for the clock, and the exact risk it is fine to take for
+ *    a label.
+ *
+ * The text, as of 2026-08-15:
+ *
+ *   Current session: 63% used · resets Aug 15, 10:39pm (Europe/Berlin)
+ *   Current week (all models): 50% used · resets Aug 19, 3:59pm (Europe/Berlin)
+ *   Current week (Fable): 0% used
+ */
+/** «Current session» is the five-hour window; every «Current week» is a weekly one. */
+const SESSION_LINE = /current session:\s*(\d+(?:\.\d+)?)%\s*used/i;
+const WEEK_LINE = /current week(?:\s*\(([^)]+)\))?:\s*(\d+(?:\.\d+)?)%\s*used/gi;
+const clamp = (raw) => {
+    if (raw === undefined)
+        return null;
+    const value = Number(raw);
+    return Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : null;
+};
+/**
+ * Every percentage `/usage` printed, in the order it printed them.
+ *
+ * The per-model weekly rows («Current week (Fable): 0% used») are kept rather
+ * than dropped — owner's call, 2026-08-15: on a plan where one model has its
+ * own weekly allowance, «50% of the week» is only half the answer.
+ *
+ * Deliberately forgiving: a line we cannot read is skipped, never thrown over.
+ */
+export function parseUsageText(text) {
+    const rows = [];
+    const session = clamp(SESSION_LINE.exec(text)?.[1]);
+    if (session !== null)
+        rows.push({ key: 'five_hour', label: null, percent: session });
+    WEEK_LINE.lastIndex = 0;
+    for (let match = WEEK_LINE.exec(text); match !== null; match = WEEK_LINE.exec(text)) {
+        const percent = clamp(match[2]);
+        if (percent === null)
+            continue;
+        const scope = (match[1] ?? '').trim();
+        // «all models» IS the weekly window; anything else is that model's own.
+        const isAll = scope === '' || /^all models$/i.test(scope);
+        rows.push({ key: 'seven_day', label: isAll ? null : `Weekly · ${scope}`, percent });
+    }
+    return rows;
+}
+/**
+ * Merge fresh percentages into the windows we already know about.
+ *
+ * The RESET TIME is never taken from here — whatever the event said stays. A
+ * window the event has not mentioned yet is created so the first probe is not
+ * wasted, with no clock on it until the event supplies one.
+ */
+export function applyUsagePercentages(windows, rows) {
+    // 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 ?? ''}`;
+    const merged = new Map(windows.map((window) => [id(window), { ...window }]));
+    for (const row of rows) {
+        const key = `${row.key}:${row.label ?? ''}`;
+        const existing = merged.get(key);
+        merged.set(key, {
+            key: row.key,
+            windowMinutes: existing?.windowMinutes ?? (row.key === 'five_hour' ? 300 : 10_080),
+            usedPercent: row.percent,
+            // The clock stays whatever the machine-readable event said — this file
+            // never sets it, so a wording change here can never move a wake-up.
+            resetsAt: existing?.resetsAt ?? null,
+            ...(existing?.status ? { status: existing.status } : {}),
+            ...(row.label ? { label: row.label } : {}),
+        });
+    }
+    return [...merged.values()].sort((a, b) => (a.windowMinutes ?? Number.MAX_SAFE_INTEGER) - (b.windowMinutes ?? Number.MAX_SAFE_INTEGER) ||
+        (a.label ?? '').localeCompare(b.label ?? ''));
+}
+/**
+ * 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.
+ */
+export function probeUsageText(binary, cwd, timeoutMs = 20_000) {
+    return new Promise((resolve) => {
+        execFile(binary, ['-p', '/usage', '--output-format', 'text'], { cwd, timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+            if (error) {
+                log.debug('claude: /usage probe failed', { error: String(error) });
+                resolve(null);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+//# sourceMappingURL=claude-usage.js.map

package/dist/adapters/claude.js

@@ -7,6 +7,10 @@ import { mcpConfigPath } from '../paths.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, } from './types.js';
 import { clampPercent, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
+import { applyUsagePercentages, parseUsageText, probeUsageText } from './claude-usage.js';
+import { claudeCliPath } from '../agent-binary.js';
+/** How often `/usage` may be read. Free, but still a process. */
+const USAGE_PROBE_INTERVAL_MS = 3 * 60 * 1000;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Claude adapter over the Agent SDK. Three live-verified gotchas (plan §2):
 //  1. Bare tool names in `allowedTools` auto-approve BEFORE canUseTool — we
@@ -695,6 +699,44 @@ 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;
+    /**
+     * Read the percentages out of the CLI's own `/usage` (#279).
+     *
+     * 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.
+     */
+    refreshUsage() {
+        if (this.stopped)
+            return;
+        if (this.usageProbedAt !== 0 && Date.now() - this.usageProbedAt < USAGE_PROBE_INTERVAL_MS) {
+            return;
+        }
+        const binary = claudeCliPath();
+        if (!binary)
+            return;
+        this.usageProbedAt = Date.now();
+        void probeUsageText(binary, this.spec.cwd)
+            .then((text) => {
+            if (!text || 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(`${window.key}:${window.label ?? ''}`, window);
+            }
+            this.emitRateLimits();
+        })
+            .catch((error) => log.debug('claude: usage probe failed', { error: String(error) }));
+    }
     /** Read the flag and clear it: one refusal marks exactly one turn end. */
     consumeLimitBlock() {
         const blocked = this.limitBlockPending;
@@ -719,6 +761,16 @@ class ClaudeSession {
     }
     emitRateLimitsFromInit(msg) {
         const init = msg;
+        // Probe against the installed CLI, 2026-08-15: `system:init` carries none of
+        // these keys at all — not `false`, ABSENT. The fields exist in the SDK's own
+        // typings, which is what this code trusted first, and the result was a panel
+        // stating «лимитов подписки нет» to an owner who has a subscription. Absence
+        // is «we do not know yet», and only a `rate_limit_event` can settle it.
+        if (init.rate_limits_available === undefined) {
+            if (typeof init.subscription_type === 'string')
+                this.ratePlanType = init.subscription_type;
+            return;
+        }
         this.rateLimitsAvailable = init.rate_limits_available === true;
         this.ratePlanType = typeof init.subscription_type === 'string' ? init.subscription_type : null;
         this.rateLimitWindows.clear();
@@ -747,25 +799,32 @@ class ClaudeSession {
         // without a percentage: the refusal is the fact, the number is decoration.
         // `allowed_warning` is NOT a refusal — the turn ran.
         const refused = info['status'] === 'rejected';
-        if (typeof utilization !== 'number' && !refused)
-            return;
-        // A live event proves there IS a plan: the SDK only emits this for
-        // claude.ai subscriptions. An account that reached `system:init` before
-        // its profile scope resolved would otherwise stay `available: false`.
+        // NOT gated on the percentage. Probe against the installed CLI, 2026-08-15:
+        // every request emits this event, and `utilization` is usually absent —
+        //   {status:'allowed', resetsAt:1786826400, rateLimitType:'five_hour', …}
+        // Requiring the number threw the whole event away, so the one source that
+        // does work was silently discarded and the panel had nothing to show. What
+        // the event always carries is WHICH window and WHEN it resets, and that is
+        // worth drawing on its own.
+        // A live event also proves there IS a plan: the SDK emits it only for
+        // claude.ai subscriptions.
         this.rateLimitsAvailable = true;
         const name = typeof info['rateLimitType'] === 'string' ? info['rateLimitType'] : 'five_hour';
         const key = rateWindowKey(name);
         // `resetsAt` here is epoch SECONDS, unlike `resets_at` on init which is
         // already ISO. Same fact, two encodings, one place that knows it.
         const resetsAt = typeof info['resetsAt'] === 'number' ? new Date(info['resetsAt'] * 1000).toISOString() : null;
-        if (typeof utilization === 'number') {
-            this.rateLimitWindows.set(name, {
-                key,
-                windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
-                usedPercent: clampPercent(utilization),
-                resetsAt,
-            });
-        }
+        // Keep whatever the previous event said about the percentage: the field
+        // comes and goes between events about the same window, and dropping it on
+        // the next silent one would make a number that was true flicker away.
+        const known = this.rateLimitWindows.get(name);
+        this.rateLimitWindows.set(name, {
+            key,
+            windowMinutes: RATE_WINDOW_MINUTES[key] ?? null,
+            usedPercent: typeof utilization === 'number' ? clampPercent(utilization) : (known?.usedPercent ?? null),
+            resetsAt: resetsAt ?? known?.resetsAt ?? null,
+            status: typeof info['status'] === 'string' ? info['status'] : null,
+        });
         if (refused)
             this.limitBlockPending = true;
         this.emitRateLimits(refused ? { key, resetsAt } : null);
@@ -1885,6 +1944,8 @@ class ClaudeSession {
                             // account has none — «this organization runs on its own key» is an
                             // answer the popup has to be able to give.
                             this.emitRateLimitsFromInit(msg);
+                            // #279: the percentages the event does not carry.
+                            this.refreshUsage();
                         }
                         else if (msg.subtype === 'status') {
                             const status = msg.status;
@@ -2040,6 +2101,9 @@ class ClaudeSession {
                                 // refused is not a turn that ran.
                                 ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
                             });
+                            // #279: a turn just moved the plan, so the percentages are worth
+                            // re-reading — throttled inside, and free either way.
+                            this.refreshUsage();
                         }
                         else {
                             this.emit({
@@ -2048,6 +2112,7 @@ class ClaudeSession {
                                 errorMessage: failure,
                                 ...(this.consumeLimitBlock() ? { limitBlocked: true } : {}),
                             });
+                            this.refreshUsage();
                         }
                         break;
                     }

package/dist/adapters/codex.js

@@ -1385,8 +1385,22 @@ class CodexSession {
             if (usedPercent === undefined)
                 continue;
             const minutes = num(window['windowMinutes'] ?? window['window_minutes']) ?? null;
+            // Live 2026-08-15: Codex sent a percentage with NO length, so the label
+            // fell back to «Limit window» — true but useless. The slot itself carries
+            // the answer on every ChatGPT plan: `primary` is the short window,
+            // `secondary` the weekly one. Used only when the minutes are missing, so
+            // a provider that does state them still wins.
+            // Only when the length is ABSENT. A stated length we do not recognise is
+            // information — 43 200 minutes is a monthly window, and calling it «5
+            // hours» because it arrived first would be worse than admitting we have
+            // no name for it.
+            const key = minutes === null
+                ? slot === 'primary'
+                    ? 'five_hour'
+                    : 'seven_day'
+                : rateWindowKeyFromMinutes(minutes);
             windows.push({
-                key: rateWindowKeyFromMinutes(minutes),
+                key,
                 windowMinutes: minutes,
                 usedPercent: clampPercent(usedPercent),
                 resetsAt: str(window['resetsAt'] ?? window['resets_at']) ?? null,
@@ -1432,7 +1446,7 @@ class CodexSession {
             haystack.includes('usagelimitreached');
         if (!refused)
             return null;
-        const fullest = this.rateLimitWindows.reduce((worst, window) => worst === null || window.usedPercent > worst.usedPercent ? window : worst, null);
+        const fullest = this.rateLimitWindows.reduce((worst, window) => worst === null || (window.usedPercent ?? 0) > (worst.usedPercent ?? 0) ? window : worst, null);
         return { key: fullest?.key ?? 'other', resetsAt: fullest?.resetsAt ?? null };
     }
     onTurnCompleted(params) {

package/dist/adapters/types.d.ts

@@ -149,10 +149,24 @@ export interface AgentRateLimitWindow {
     key: 'five_hour' | 'seven_day' | 'other';
     /** Length of the window, when the provider states it. */
     windowMinutes: number | null;
-    /** 0–100. What is SPENT, not what is left — both CLIs report it that way. */
-    usedPercent: number;
+    /**
+     * 0–100, SPENT rather than left — and **nullable**.
+     *
+     * Claude's live event carries the window and its reset time on every request
+     * but usually omits the percentage (probe, 2026-08-15). A window we can date
+     * but not measure is still worth showing; requiring the number here is what
+     * made the panel say «no plan» to an account that has one.
+     */
+    usedPercent: number | null;
     /** Absolute moment, ISO 8601. Null when the provider did not say. */
     resetsAt: string | null;
+    /** `allowed` · `allowed_warning` · `rejected`, when the provider says. */
+    status?: string | null;
+    /**
+     * What to call this row when our own vocabulary is not enough — «Weekly ·
+     * Fable» for a model with its own weekly allowance (owner's call, #279).
+     */
+    label?: string | null;
 }
 /**
  * The account's plan usage, as one snapshot (#279, #258).

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.41.0";
+export declare const RUNNER_VERSION = "0.42.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.41.0';
+export const RUNNER_VERSION = '0.42.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",