@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/tmux/session.d.ts

@@ -9,6 +9,22 @@
  * pure provenance — `listSessions()` always reconciles them against
  * `tmux list-sessions` and prunes stale entries on the fly.
  */
+/**
+ * Ten times tmux's 2,000-line default, while keeping per-pane memory bounded:
+ * history storage scales with pane width, so a 200-column pane retains at most
+ * four million grid cells rather than an unbounded agent transcript.
+ */
+export declare const AGENTS_TMUX_HISTORY_LIMIT = 20000;
+/**
+ * Bump when the generated startup config changes, so an ALREADY-RUNNING server
+ * picks the new settings up. tmux reads `-f` only when it actually starts a
+ * server: a second `new-session -f other.conf` against a live server exits 0
+ * and silently applies nothing (verified against tmux 3.4). Since agents-cli
+ * uses one long-lived shared socket, the normal state at upgrade is a running
+ * server — so without this reconcile every existing machine would get none of
+ * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
+ */
+export declare const AGENTS_TMUX_CONFIG_SCHEMA = 1;
 /** Provenance written alongside each live tmux session. */
 export interface SessionMeta {
     name: string;
@@ -62,6 +78,8 @@ export interface ListedSession {
     attached: boolean;
     meta?: SessionMeta;
 }
+/** Build the atomic server-configuration + session-creation command. */
+export declare function buildCreateSessionArgs(opts: CreateSessionOptions, startupConfig: string): string[];
 export declare class TmuxSessionError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
@@ -213,21 +231,36 @@ export declare function setSessionHook(name: string, hook: string, command: stri
  *        variant could stall the hook on a loaded CI runner, letting the dead
  *        split survive until the test's wait timeout expired (flake in CI shard
  *        3: pane-guarded pane-died hook / user split exit).
+ *   v6 — the agent-pane branch is now `session_attached`-aware: with a client
+ *        attached it `detach-client`s (the interactive path, so runInTmux's
+ *        attach returns and reads the exit status, EXEC-23b unchanged); with NO
+ *        client it `kill-session`s outright. A `remain-on-exit` pane with no
+ *        attach client to reap it otherwise lingers as a dead husk until the
+ *        daemon's periodic `reapDeadTmuxPanes` sweep — so a run whose terminal
+ *        was closed, or a `/exit` after the user detached, left an idle-looking
+ *        dead session on the socket. Killing it the instant the agent exits is
+ *        the "one close tears down every layer" contract (#5a).
  */
-export declare const AGENT_HOOK_SCHEMA = 5;
+export declare const AGENT_HOOK_SCHEMA = 6;
 /**
- * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
- * (so the blocking attach in runInTmux returns and the exit status can be read);
- * a user split's death runs the else-branch, closing just that split. The
- * else-branch goes through `run-shell -b -C` with an explicit `-t #{hook_pane}`
- * target: tmux format-expands the command at fire time and executes it inside
- * the server command queue in the background, so the event pane is always the
- * one killed without launching a second tmux client against the same socket and
- * without stalling the hook on a loaded runner. A bare `kill-pane` relied on
- * the hook context supplying a "current pane", while an external self-client
- * could race the server under load. Single source of truth: both the
- * spawn-wrap (exec.ts) and the daemon reconcile build the hook here, so the
- * two can never drift.
+ * The guarded `pane-died` hook. When the AGENT pane dies, tear the whole session
+ * down — but HOW depends on whether a client is attached:
+ *   - attached (`#{session_attached}`): `detach-client` so the blocking attach in
+ *     runInTmux returns and `resolveAfterAttach` reads the exit status off the
+ *     still-`remain-on-exit` dead pane, then kills the session (EXEC-23b, unchanged);
+ *   - no client: `kill-session` outright. Without this the dead pane sits under
+ *     `remain-on-exit` as an idle-looking husk until the daemon's periodic
+ *     `reapDeadTmuxPanes` sweep — the "second exit" / orphaned-idle session bug
+ *     when a wrapped agent exits with nobody attached (a closed terminal, or a
+ *     `/exit` after the user detached). `detach-client` on an unattached session
+ *     is a no-op, so the old hook left the husk; `kill-session` ends it at once.
+ * A user split's death still runs the else-branch, closing just that split via
+ * `run-shell -b -C` with an explicit `-t #{hook_pane}` target: tmux format-expands
+ * the command at fire time and executes it inside the server command queue in the
+ * background, so the event pane is always the one killed without launching a second
+ * tmux client against the same socket and without stalling the hook on a loaded
+ * runner. Single source of truth: both the spawn-wrap (exec.ts) and the daemon
+ * reconcile build the hook here, so the two can never drift.
  */
 export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
 /** Stamp a session's hook-schema marker to the current version. */

package/dist/lib/tmux/session.js

@@ -10,10 +10,94 @@
  * `tmux list-sessions` and prunes stale entries on the fly.
  */
 import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { runTmux, TmuxCommandError } from './binary.js';
 import { ensureTmuxDir, getDefaultSocketPath, getSessionMetaPath } from './paths.js';
 /** Tmux session names must not contain `.` or `:` — those are reserved for window/pane addressing. */
 const VALID_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Ten times tmux's 2,000-line default, while keeping per-pane memory bounded:
+ * history storage scales with pane width, so a 200-column pane retains at most
+ * four million grid cells rather than an unbounded agent transcript.
+ */
+export const AGENTS_TMUX_HISTORY_LIMIT = 20_000;
+/**
+ * Bump when the generated startup config changes, so an ALREADY-RUNNING server
+ * picks the new settings up. tmux reads `-f` only when it actually starts a
+ * server: a second `new-session -f other.conf` against a live server exits 0
+ * and silently applies nothing (verified against tmux 3.4). Since agents-cli
+ * uses one long-lived shared socket, the normal state at upgrade is a running
+ * server — so without this reconcile every existing machine would get none of
+ * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
+ */
+export const AGENTS_TMUX_CONFIG_SCHEMA = 1;
+/** Server-scoped user-option recording which AGENTS_TMUX_CONFIG_SCHEMA is applied. */
+const CONFIG_SCHEMA_OPTION = '@ag_tmux_config_schema';
+let startupConfigSequence = 0;
+function tmuxConfigArgument(value) {
+    return `"${value.replace(/([\\"$])/g, '\\$1')}"`;
+}
+/**
+ * tmux loads `-f` instead of its normal user config, so put agents-cli's
+ * defaults first and explicitly source the first user config tmux would have
+ * selected afterward. Configuration files execute in order; this makes these
+ * settings defaults while preserving every option or binding the user sets.
+ */
+function writeStartupConfig(env) {
+    const effectiveEnv = env ?? process.env;
+    const home = effectiveEnv.HOME ?? os.homedir();
+    const candidates = [
+        path.join(home, '.tmux.conf'),
+        ...(effectiveEnv.XDG_CONFIG_HOME
+            ? [path.join(effectiveEnv.XDG_CONFIG_HOME, 'tmux', 'tmux.conf')]
+            : []),
+        path.join(home, '.config', 'tmux', 'tmux.conf'),
+    ];
+    // tmux's own start_cfg() sources EVERY entry of TMUX_CONF that exists, not
+    // just the first — a user with both ~/.tmux.conf and ~/.config/tmux/tmux.conf
+    // gets both. Sourcing only the first would silently drop the second and break
+    // the "never override a user-set value" contract this file exists to keep.
+    const userConfigs = candidates.filter((candidate) => fs.existsSync(candidate));
+    const startupConfig = path.join(ensureTmuxDir(), `startup-${process.pid}-${startupConfigSequence++}.conf`);
+    const lines = [
+        // Stamp the schema HERE as well as in reconcileServerConfig. Without it a
+        // cold start leaves the option unset, the post-new-session check sees a
+        // stale stamp, and the reconcile re-sources the user's config a second time
+        // on launch #1 — firing any run-shell side effect (TPM) twice.
+        `set-option -g ${CONFIG_SCHEMA_OPTION} ${AGENTS_TMUX_CONFIG_SCHEMA}`,
+        'set-option -g mouse on',
+        'set-option -s set-clipboard on',
+        `set-option -g history-limit ${AGENTS_TMUX_HISTORY_LIMIT}`,
+        'bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-selection-no-clear',
+        'bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-selection-no-clear',
+    ];
+    for (const userConfig of userConfigs) {
+        lines.push(`source-file -q ${tmuxConfigArgument(userConfig)}`);
+    }
+    fs.writeFileSync(startupConfig, `${lines.join('\n')}\n`, { mode: 0o600 });
+    return startupConfig;
+}
+/** Build the atomic server-configuration + session-creation command. */
+export function buildCreateSessionArgs(opts, startupConfig) {
+    const args = [
+        '-f', startupConfig,
+        'set-option', '-g', 'remain-on-exit', 'on', ';',
+        'new-session', '-d', '-s', opts.name, '-P', '-F', '#{pane_id}',
+    ];
+    if (opts.width)
+        args.push('-x', String(opts.width));
+    if (opts.height)
+        args.push('-y', String(opts.height));
+    if (opts.cwd)
+        args.push('-c', opts.cwd);
+    // Separator + child command. tmux passes the rest verbatim to exec, so no
+    // shell escaping is required — array args end-to-end.
+    if (opts.cmd) {
+        args.push('--', 'sh', '-c', opts.cmd);
+    }
+    return args;
+}
 export class TmuxSessionError extends Error {
     cause;
     constructor(message, cause) {
@@ -44,6 +128,41 @@ export async function hasSession(name, socket) {
     });
     return res.code === 0;
 }
+/** Which AGENTS_TMUX_CONFIG_SCHEMA a live server has applied; undefined when none. */
+async function appliedConfigSchema(socket) {
+    const res = await runTmux({
+        socket,
+        args: ['show-options', '-gv', CONFIG_SCHEMA_OPTION],
+        throwOnError: false,
+    }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const n = Number(res.stdout.trim());
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Apply the generated startup config to an already-running server and stamp it.
+ * Failure is surfaced, not swallowed: a server left without these settings is
+ * the silent no-op this exists to prevent.
+ */
+async function reconcileServerConfig(socket, env) {
+    const conf = writeStartupConfig(env);
+    try {
+        const res = await runTmux({ socket, args: ['source-file', conf], throwOnError: false, env });
+        if (res.code !== 0) {
+            throw new TmuxSessionError(`could not apply agents-cli tmux settings to the running server (${res.stderr.trim() || `exit ${res.code}`})`);
+        }
+        await runTmux({
+            socket,
+            args: ['set-option', '-g', CONFIG_SCHEMA_OPTION, String(AGENTS_TMUX_CONFIG_SCHEMA)],
+            throwOnError: false,
+            env,
+        }).catch(() => { });
+    }
+    finally {
+        fs.rmSync(conf, { force: true });
+    }
+}
 /**
  * Create a new detached session. Throws when the name is already taken unless
  * `replace` or `attachExisting` is set.
@@ -58,6 +177,13 @@ export async function createSession(opts) {
     const existed = await hasSession(opts.name, socket);
     if (existed) {
         if (opts.attachExisting) {
+            // Reuse of a live session is precisely the already-running-server case,
+            // so it needs the same reconcile the create path gets — otherwise
+            // `agents tmux new --attach-existing` silently keeps a pre-fix server
+            // with none of these settings.
+            if ((await appliedConfigSchema(socket)) !== AGENTS_TMUX_CONFIG_SCHEMA) {
+                await reconcileServerConfig(socket, opts.env);
+            }
             const meta = readSessionMeta(opts.name);
             return meta ?? {
                 name: opts.name,
@@ -71,28 +197,32 @@ export async function createSession(opts) {
         }
         await killSession(opts.name, socket);
     }
-    // Set remain-on-exit BEFORE the child command can finish — a fast-exiting
+    // Configure the agents-cli tmux server BEFORE the child command can finish — a fast-exiting
     // cmd (e.g. `echo BRIEF && true`) would otherwise collapse the only session,
     // exit the server, and the follow-up `set-option` would race with "no
     // server running". Server-wide (`-g`) is applied in the same tmux
     // invocation as new-session so they share one server lifetime.
     // `-P -F '#{pane_id}'` prints the new session's first pane id on stdout so we
     // can record the exact `%N` handle without a follow-up `list-panes`.
-    const args = ['set-option', '-g', 'remain-on-exit', 'on', ';', 'new-session', '-d', '-s', opts.name, '-P', '-F', '#{pane_id}'];
-    if (opts.width)
-        args.push('-x', String(opts.width));
-    if (opts.height)
-        args.push('-y', String(opts.height));
-    if (opts.cwd)
-        args.push('-c', opts.cwd);
-    // Separator + child command. tmux passes the rest verbatim to exec, so no
-    // shell escaping is required — array args end-to-end.
-    if (opts.cmd) {
-        args.push('--', 'sh', '-c', opts.cmd);
+    const startupConfig = writeStartupConfig(opts.env);
+    const args = buildCreateSessionArgs(opts, startupConfig);
+    let res;
+    try {
+        res = await runTmux({ socket, args, env: opts.env });
+    }
+    finally {
+        fs.rmSync(startupConfig, { force: true });
     }
-    const res = await runTmux({ socket, args, env: opts.env });
     // Only the new-session command in the `;`-chained invocation emits output.
     const pane = /^%\d+$/.test(res.stdout.trim()) ? res.stdout.trim() : undefined;
+    // If the server was ALREADY running, its `-f` was ignored, so the config above
+    // never applied. Re-source it — the generated file ends by sourcing the user's
+    // own tmux.conf, so re-applying preserves the same precedence a cold start
+    // gives. Gated on a generation stamp so a user config with side effects (tpm's
+    // run-shell, for one) is not re-executed on every single launch.
+    if (existed || (await appliedConfigSchema(socket)) !== AGENTS_TMUX_CONFIG_SCHEMA) {
+        await reconcileServerConfig(socket, opts.env);
+    }
     // Keep the agent pane around after its process exits (so runInTmux can read
     // the exit status and capture the final error), but do NOT keep that behavior
     // for user-created splits. Apply remain-on-exit to the agent pane only, then
@@ -402,8 +532,17 @@ export async function setSessionHook(name, hook, command, socket, timeoutMs) {
  *        variant could stall the hook on a loaded CI runner, letting the dead
  *        split survive until the test's wait timeout expired (flake in CI shard
  *        3: pane-guarded pane-died hook / user split exit).
+ *   v6 — the agent-pane branch is now `session_attached`-aware: with a client
+ *        attached it `detach-client`s (the interactive path, so runInTmux's
+ *        attach returns and reads the exit status, EXEC-23b unchanged); with NO
+ *        client it `kill-session`s outright. A `remain-on-exit` pane with no
+ *        attach client to reap it otherwise lingers as a dead husk until the
+ *        daemon's periodic `reapDeadTmuxPanes` sweep — so a run whose terminal
+ *        was closed, or a `/exit` after the user detached, left an idle-looking
+ *        dead session on the socket. Killing it the instant the agent exits is
+ *        the "one close tears down every layer" contract (#5a).
  */
-export const AGENT_HOOK_SCHEMA = 5;
+export const AGENT_HOOK_SCHEMA = 6;
 /** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
 const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
 /**
@@ -416,21 +555,28 @@ const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
  */
 const TMUX_HOOK_REPAIR_TIMEOUT_MS = 5_000;
 /**
- * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
- * (so the blocking attach in runInTmux returns and the exit status can be read);
- * a user split's death runs the else-branch, closing just that split. The
- * else-branch goes through `run-shell -b -C` with an explicit `-t #{hook_pane}`
- * target: tmux format-expands the command at fire time and executes it inside
- * the server command queue in the background, so the event pane is always the
- * one killed without launching a second tmux client against the same socket and
- * without stalling the hook on a loaded runner. A bare `kill-pane` relied on
- * the hook context supplying a "current pane", while an external self-client
- * could race the server under load. Single source of truth: both the
- * spawn-wrap (exec.ts) and the daemon reconcile build the hook here, so the
- * two can never drift.
+ * The guarded `pane-died` hook. When the AGENT pane dies, tear the whole session
+ * down — but HOW depends on whether a client is attached:
+ *   - attached (`#{session_attached}`): `detach-client` so the blocking attach in
+ *     runInTmux returns and `resolveAfterAttach` reads the exit status off the
+ *     still-`remain-on-exit` dead pane, then kills the session (EXEC-23b, unchanged);
+ *   - no client: `kill-session` outright. Without this the dead pane sits under
+ *     `remain-on-exit` as an idle-looking husk until the daemon's periodic
+ *     `reapDeadTmuxPanes` sweep — the "second exit" / orphaned-idle session bug
+ *     when a wrapped agent exits with nobody attached (a closed terminal, or a
+ *     `/exit` after the user detached). `detach-client` on an unattached session
+ *     is a no-op, so the old hook left the husk; `kill-session` ends it at once.
+ * A user split's death still runs the else-branch, closing just that split via
+ * `run-shell -b -C` with an explicit `-t #{hook_pane}` target: tmux format-expands
+ * the command at fire time and executes it inside the server command queue in the
+ * background, so the event pane is always the one killed without launching a second
+ * tmux client against the same socket and without stalling the hook on a loaded
+ * runner. Single source of truth: both the spawn-wrap (exec.ts) and the daemon
+ * reconcile build the hook here, so the two can never drift.
  */
 export function agentPaneDiedHook(sessionName, agentPane) {
-    return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
+    const agentPaneAction = `if -F '#{session_attached}' 'detach-client -s =${sessionName}' 'kill-session -t =${sessionName}'`;
+    return `if -F '#{==:#{hook_pane},${agentPane}}' "${agentPaneAction}" 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
 }
 /** Stamp a session's hook-schema marker to the current version. */
 export async function markSessionHookSchema(name, socket, timeoutMs) {

package/dist/lib/types.d.ts

@@ -277,6 +277,22 @@ export interface HookMatches {
     git_dirty?: boolean;
     cwd_includes?: string | string[];
     project_has?: string;
+    /**
+     * Permission modes the hook fires in (e.g. `plan`). Unlike the other
+     * predicates this one is fail-open on absence: an input that carries no
+     * permission_mode/permissionMode field passes, because only some harnesses
+     * (Claude Code) report the live mode — an explicit non-listed value skips.
+     */
+    permission_mode?: string | string[];
+    /**
+     * Permission modes the hook must NOT fire in (e.g. `plan`). The inverse of
+     * `permission_mode`, and the correct predicate for gating a guard off in one
+     * mode: expressing that with the allowlist means enumerating every other
+     * mode, which silently stops firing when a harness adds or renames one. Same
+     * fail-open-on-absence rule — an input with no mode field still fires — so an
+     * unknown mode errs toward running the hook, never toward skipping it.
+     */
+    permission_mode_not?: string | string[];
 }
 /**
  * Cache scoping. Determines which cache file a hook invocation reads/writes:

package/dist/lib/usage-backoff.d.ts

@@ -15,6 +15,7 @@ export declare function parseRetryAfterMs(header: string | null | undefined, now
 export declare function noteUsageRateLimited(agent: AgentId, retryAfter: string | null | undefined, opts?: {
     now?: number;
     fallbackMs?: number;
+    account?: string | null;
 }): void;
 /**
  * Epoch ms until which `agent`'s usage endpoint should not be called, or null
@@ -24,6 +25,6 @@ export declare function noteUsageRateLimited(agent: AgentId, retryAfter: string
  * Sweeps elapsed files while it is here: they can only accumulate at the rate
  * penalties are issued, and this is the one place that already lists them.
  */
-export declare function usageRateLimitedUntil(agent: AgentId, now?: number): number | null;
+export declare function usageRateLimitedUntil(agent: AgentId, now?: number, account?: string | null): number | null;
 /** Human-readable remaining backoff, for the error a skipped read returns. */
 export declare function formatBackoffRemaining(untilMs: number, now?: number): string;

package/dist/lib/usage-backoff.js

@@ -39,9 +39,15 @@
  * one — monotonicity is structural rather than argued, and there is no lock to
  * go stale on a path every usage read touches. Elapsed files are swept on read.
  *
- * Deliberately per-provider, not per-account: the endpoint throttles the caller,
- * and the observed 429 hit all five accounts on the box at once. Backing off one
- * account while the others keep firing would not clear the penalty.
+ * Scoped per ACCOUNT when the caller knows one, per provider otherwise
+ * (RUSH-3036). The first cut was deliberately provider-wide — the 2026-08-03
+ * incident 429'd every account on the box at once, so per-provider looked
+ * sufficient. It was not: the quotas proved per-account, and a provider-wide
+ * park let the first throttled account in a refresh pass starve every account
+ * after it in the loop's fixed iteration order — the same four accounts read
+ * 'usage unavailable' across passes while their siblings refreshed. An
+ * account-scoped penalty parks only that account; a penalty recorded with no
+ * account identity stays provider-wide and still parks everything.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -84,8 +90,26 @@ export function parseRetryAfterMs(header, now = Date.now()) {
     const ms = at - now;
     return ms > 0 ? Math.min(ms, MAX_BACKOFF_MS) : null;
 }
-/** Every recorded deadline for `agent`, newest-first. Never throws. */
-function deadlinesFor(agent) {
+/**
+ * File-name scope for a penalty. Provider-wide penalties are `<agent>`;
+ * account-scoped ones are `<agent>@<slug>` (RUSH-3036), where the slug is the
+ * account's usage key with path separators neutralized (usage keys carry `:`,
+ * `=`, `.` and `@` freely — all filename-safe on the platforms we run on).
+ * `@` cannot collide with the provider scope because provider files are always
+ * `<agent>.<digits>` and agent ids never contain `@`.
+ */
+function backoffScope(agent, account) {
+    if (!account)
+        return agent;
+    return `${agent}@${account.replace(/[/\\]/g, '_')}`;
+}
+/**
+ * Every recorded deadline for `scope`. A file belongs to the scope only when
+ * everything after `<scope>.` is pure digits — account slugs contain dots
+ * (emails inside usage keys), so a bare prefix match would let scope
+ * `claude@a` swallow `claude@a.b`'s files.
+ */
+function deadlinesFor(scope) {
     let names;
     try {
         names = fs.readdirSync(backoffDir());
@@ -94,12 +118,15 @@ function deadlinesFor(agent) {
         // No directory yet: nothing is throttled.
         return [];
     }
-    const prefix = `${agent}.`;
+    const prefix = `${scope}.`;
     const out = [];
     for (const name of names) {
         if (!name.startsWith(prefix))
             continue;
-        const at = Number(name.slice(prefix.length));
+        const rest = name.slice(prefix.length);
+        if (!/^\d+$/.test(rest))
+            continue;
+        const at = Number(rest);
         if (Number.isFinite(at))
             out.push(at);
     }
@@ -120,7 +147,14 @@ export function noteUsageRateLimited(agent, retryAfter, opts) {
         fs.mkdirSync(backoffDir(), { recursive: true });
         // Empty file: the name carries the whole value, so there is no content a
         // concurrent reader could catch half-written, and no document to merge.
-        fs.writeFileSync(path.join(backoffDir(), `${agent}.${deadline}`), '');
+        //
+        // With an account, the penalty is scoped to THAT account (RUSH-3036): the
+        // observed 429s are per-account quotas, and a provider-wide park let the
+        // first throttled account starve every account after it in the refresh
+        // loop's fixed order — the same 4 accounts stayed 'usage unavailable'
+        // across passes while their siblings refreshed. Callers with no account
+        // identity still record provider-wide, which continues to park everything.
+        fs.writeFileSync(path.join(backoffDir(), `${backoffScope(agent, opts?.account)}.${deadline}`), '');
     }
     catch {
         // Best-effort. An unwritable cache dir costs the cross-process backoff, not
@@ -135,19 +169,26 @@ export function noteUsageRateLimited(agent, retryAfter, opts) {
  * Sweeps elapsed files while it is here: they can only accumulate at the rate
  * penalties are issued, and this is the one place that already lists them.
  */
-export function usageRateLimitedUntil(agent, now = Date.now()) {
+export function usageRateLimitedUntil(agent, now = Date.now(), account) {
+    // A provider-wide penalty parks every account; an account-scoped read also
+    // honors that account's own penalties. A bare (no-account) read deliberately
+    // ignores account-scoped penalties — one pinned account must not park its
+    // siblings (RUSH-3036).
+    const scopes = account ? [backoffScope(agent, null), backoffScope(agent, account)] : [backoffScope(agent, null)];
     let latest = null;
-    for (const at of deadlinesFor(agent)) {
-        if (at > now) {
-            if (latest === null || at > latest)
-                latest = at;
-        }
-        else {
-            try {
-                fs.rmSync(path.join(backoffDir(), `${agent}.${at}`), { force: true });
+    for (const scope of scopes) {
+        for (const at of deadlinesFor(scope)) {
+            if (at > now) {
+                if (latest === null || at > latest)
+                    latest = at;
             }
-            catch {
-                /* another process may have swept it already */
+            else {
+                try {
+                    fs.rmSync(path.join(backoffDir(), `${scope}.${at}`), { force: true });
+                }
+                catch {
+                    /* another process may have swept it already */
+                }
             }
         }
     }

package/dist/lib/usage-refresh.d.ts

@@ -18,6 +18,10 @@ export declare const REFRESH_BURN_DIVISOR = 4;
 export declare const HOURLY_CALL_CAP = 12;
 /** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
 export declare const USAGE_REFRESH_TICK_MS: number;
+/** Consecutive failed live reads before one broken account is quarantined. */
+export declare const FAILURE_QUARANTINE_THRESHOLD = 3;
+/** A chronic offender waits this long while healthy siblings keep their cadence. */
+export declare const FAILURE_QUARANTINE_MS: number;
 /**
  * One account's refresh state + published headroom. `sessionUsedPercent` /
  * `capturedAt` are the prior sample the NEXT tick projects the burn rate from;
@@ -36,6 +40,8 @@ export interface HeadroomEntry {
     callTimestamps: number[];
     /** Epoch ms this entry was written. */
     computedAt: number;
+    /** Consecutive live-fetch misses; absent on entries written before this field. */
+    consecutiveFailures?: number;
 }
 export declare function setHeadroomCachePathForTest(cachePath: string | null): string | null;
 /** Read the whole headroom cache (best-effort; missing/corrupt → empty map). */
@@ -79,6 +85,8 @@ export interface LocalUsageAccount {
     /** Live-fetch this account's usage; the daemon passes the real network fetch. */
     fetch: () => Promise<UsageInfo>;
 }
+/** Cold accounts lead each pass; both cold and cached groups rotate every tick. */
+export declare function orderUsageAccounts(accounts: LocalUsageAccount[], cache: Record<string, HeadroomEntry>, tick: number): LocalUsageAccount[];
 /**
  * Enumerate the usage accounts whose credentials live on THIS host — one
  * per unique usage key, deduped to the most-recently-active version (the same
@@ -95,8 +103,14 @@ export interface UsageRefreshDeps {
     listAccounts: () => Promise<LocalUsageAccount[]>;
     /** Persist a fresh snapshot to the usage cache (writeClaudeUsageCache). */
     writeUsageCache: (usageKey: string, snapshot: UsageSnapshot) => void;
-    /** Epoch ms a provider is backed off until, or null when free (usageRateLimitedUntil). */
-    backoffUntil: (agentId: AgentId) => number | null;
+    /**
+     * Epoch ms this provider — or, when `usageKey` is given, this specific
+     * account — is backed off until; null when free (usageRateLimitedUntil).
+     * Per-account scope (RUSH-3036): one throttled account must not park its
+     * siblings, which previously starved every account after the first 429 in
+     * this loop's fixed iteration order.
+     */
+    backoffUntil: (agentId: AgentId, usageKey?: string) => number | null;
 }
 export interface UsageRefreshResult {
     refreshed: number;
@@ -107,7 +121,7 @@ export interface UsageRefreshResult {
 }
 /**
  * One refresher tick: for each local account that is due, under its hourly cap,
- * and not provider-backed-off, live-fetch its usage, update the cache, and
+ * and not backed off, live-fetch its usage, update the cache, and
  * reschedule from the new burn projection. Never throws — a single account's
  * failed fetch leaves its cache untouched and counts as `failed`.
  */