@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/devices/registry.d.ts

@@ -1,3 +1,5 @@
+import type { Meta } from '../types.js';
+import type { IgnoredDeviceEntry } from '../fleet/types.js';
 /** Operating-system family of a device, used to pick the remote shell. */
 export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
 /** Remote shell dialect derived from the platform. */
@@ -84,8 +86,36 @@ export interface DeviceProfile {
 export declare function isDialableDevice(d: DeviceProfile): boolean;
 /** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
-/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+/**
+ * `--device` values that mean "resolve me", not "connect to a box with this
+ * name". A real device registered under one of these would be unreachable,
+ * and pinning `interactive.host` to one is a misconfiguration that has to fail
+ * at WRITE time — otherwise the read side can only report "none is set", which
+ * tells the user to run the command they just ran.
+ */
+export declare const RESERVED_DEVICE_NAMES: Set<string>;
+/**
+ * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
+ *
+ * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
+ * already registered — including one this version would refuse to create.
+ */
 export declare function assertValidDeviceName(name: string): void;
+/**
+ * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
+ * routing sentinel.
+ *
+ * Deliberately separate from {@link assertValidDeviceName}, and called from
+ * exactly two kinds of place: `agents devices add <name>`, and the config keys
+ * that point AT a device (`interactive.host`, `usage.primary-host`).
+ *
+ * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
+ * receive tailnet node names the user never typed — `devices sync` upserts every
+ * observed node in a loop with no per-node catch, so one node named `auto` would
+ * abort the entire sync and register nothing after it. A name the fleet OBSERVES
+ * is not a name anyone CHOSE; only the second kind is policy's business.
+ */
+export declare function assertRegistrableDeviceName(name: string): void;
 /** Map a Tailscale `OS` field to our platform enum. */
 export declare function platformFromOs(os: string | undefined): DevicePlatform;
 /** The remote shell a platform speaks. */
@@ -132,12 +162,39 @@ export declare function upsertDevice(name: string, input: DeviceInput): Promise<
 export declare function writeReachability(updates: Record<string, DeviceReachability>): Promise<string[]>;
 /** Remove a device. Returns false if it was not registered. */
 export declare function removeDevice(name: string): Promise<boolean>;
-/** Load the set of ignored node names. Missing file => empty set. A malformed
- * file is a hard error for the same reason the registry is: silently returning
- * [] would let the next write wipe the user's dismissals. */
+/**
+ * The ignore-list: tailscale node names the user explicitly dismissed from
+ * auto-discovery. A dismissed node is deliberately NOT a device (it never
+ * enters the registry), so it has no per-device doc — its home is the central,
+ * TRACKED `~/.agents/agents.yaml` under a `fleet.ignored` list, which syncs
+ * fleet-wide via `agents repo push/pull`: a dismissal on one box stops the
+ * suggestion on every box (RUSH-3062). Auto-discovery (`runDeviceSync`'s
+ * pending diff) subtracts this set, so an ignored node never re-surfaces as a
+ * suggestion. Writes go through `updateMeta` — the central-config write path
+ * (withMetaLock + atomic write) — so two agents writing concurrently cannot
+ * corrupt it, and no second lock is hand-rolled here.
+ */
+export type { IgnoredDeviceEntry } from '../fleet/types.js';
+/**
+ * The full ignore-list entries — who dismissed a node, when, and on which box —
+ * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
+ * []. A malformed block is a hard error for the same reason the registry is:
+ * silently returning [] would let the next write wipe the user's dismissals.
+ */
+export declare function loadIgnoredEntries(meta?: Meta): IgnoredDeviceEntry[];
+/** Load the set of ignored node names. Same corruption contract as
+ * {@link loadIgnoredEntries}. */
 export declare function loadIgnored(): Promise<Set<string>>;
 /** True if `name` is on the ignore-list. */
 export declare function isIgnored(name: string): Promise<boolean>;
+/**
+ * Union `names` into the meta's ignore-list, stamping new entries with
+ * `ignoredAt` and THIS machine's id. Existing entries keep their original
+ * who/when, so re-adding a name is a true no-op. Returns the input unchanged
+ * when no name is new. Exported for the one-shot legacy-store migration in
+ * lib/devices/config-migration.ts.
+ */
+export declare function withIgnoredAdded(meta: Meta, names: string[], ignoredAt: string): Meta;
 /** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
 export declare function addIgnored(name: string): Promise<Set<string>>;
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was

package/dist/lib/devices/registry.js

@@ -17,8 +17,9 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { getDevicesRegistryPath, readMeta, updateMeta } from '../state.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
+import { machineId } from '../machine-id.js';
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -62,12 +63,46 @@ function registryPath() {
 /** Valid logical device name: the ssh-alias charset, so it renders into an
  * unambiguous `Host` stanza and is safe as an ssh target. */
 const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+/**
+ * `--device` values that mean "resolve me", not "connect to a box with this
+ * name". A real device registered under one of these would be unreachable,
+ * and pinning `interactive.host` to one is a misconfiguration that has to fail
+ * at WRITE time — otherwise the read side can only report "none is set", which
+ * tells the user to run the command they just ran.
+ */
+export const RESERVED_DEVICE_NAMES = new Set(['auto', 'interactive', 'all']);
+/**
+ * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
+ *
+ * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
+ * already registered — including one this version would refuse to create.
+ */
 export function assertValidDeviceName(name) {
     if (!DEVICE_NAME_RE.test(name)) {
         throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
     }
 }
+/**
+ * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
+ * routing sentinel.
+ *
+ * Deliberately separate from {@link assertValidDeviceName}, and called from
+ * exactly two kinds of place: `agents devices add <name>`, and the config keys
+ * that point AT a device (`interactive.host`, `usage.primary-host`).
+ *
+ * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
+ * receive tailnet node names the user never typed — `devices sync` upserts every
+ * observed node in a loop with no per-node catch, so one node named `auto` would
+ * abort the entire sync and register nothing after it. A name the fleet OBSERVES
+ * is not a name anyone CHOSE; only the second kind is policy's business.
+ */
+export function assertRegistrableDeviceName(name) {
+    assertValidDeviceName(name);
+    if (RESERVED_DEVICE_NAMES.has(name.trim().toLowerCase())) {
+        throw new Error(`${JSON.stringify(name)} is a reserved --device value, not a device name. ` +
+            `Reserved: ${[...RESERVED_DEVICE_NAMES].join(', ')}.`);
+    }
+}
 /** Map a Tailscale `OS` field to our platform enum. */
 export function platformFromOs(os) {
     switch ((os ?? '').toLowerCase()) {
@@ -246,55 +281,76 @@ export async function removeDevice(name) {
         return true;
     });
 }
-function ignoredPath() {
-    return getDevicesIgnoredPath();
+/**
+ * The full ignore-list entries — who dismissed a node, when, and on which box —
+ * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
+ * []. A malformed block is a hard error for the same reason the registry is:
+ * silently returning [] would let the next write wipe the user's dismissals.
+ */
+export function loadIgnoredEntries(meta = readMeta()) {
+    const raw = meta.fleet?.ignored;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) ||
+        raw.some((e) => !e ||
+            typeof e.name !== 'string' ||
+            typeof e.ignoredAt !== 'string' ||
+            typeof e.ignoredOn !== 'string')) {
+        throw new Error(`Device ignore-list corrupted in agents.yaml (fleet.ignored): expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair ~/.agents/agents.yaml.`);
+    }
+    return raw;
 }
-/** Load the set of ignored node names. Missing file => empty set. A malformed
- * file is a hard error for the same reason the registry is: silently returning
- * [] would let the next write wipe the user's dismissals. */
+/** Load the set of ignored node names. Same corruption contract as
+ * {@link loadIgnoredEntries}. */
 export async function loadIgnored() {
-    const p = ignoredPath();
-    let raw;
-    try {
-        raw = await fs.readFile(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return new Set();
-        throw err;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        return new Set(Array.isArray(parsed.ignored) ? parsed.ignored : []);
-    }
-    catch (err) {
-        throw new Error(`Device ignore-list corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
-    }
+    return new Set(loadIgnoredEntries().map((e) => e.name));
 }
 /** True if `name` is on the ignore-list. */
 export async function isIgnored(name) {
     return (await loadIgnored()).has(name);
 }
+/**
+ * Union `names` into the meta's ignore-list, stamping new entries with
+ * `ignoredAt` and THIS machine's id. Existing entries keep their original
+ * who/when, so re-adding a name is a true no-op. Returns the input unchanged
+ * when no name is new. Exported for the one-shot legacy-store migration in
+ * lib/devices/config-migration.ts.
+ */
+export function withIgnoredAdded(meta, names, ignoredAt) {
+    const entries = loadIgnoredEntries(meta); // throws on a corrupted block — never wipe it
+    const have = new Set(entries.map((e) => e.name));
+    const fresh = names.filter((n) => !have.has(n));
+    if (fresh.length === 0)
+        return meta;
+    const fleet = (meta.fleet ?? { devices: {} });
+    const ignored = [
+        ...entries,
+        ...fresh.map((name) => ({ name, ignoredAt, ignoredOn: machineId() })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
+    const nextFleet = { ...fleet, ignored };
+    return { ...meta, fleet: nextFleet };
+}
 /** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
 export async function addIgnored(name) {
     assertValidDeviceName(name);
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        set.add(name);
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return set;
-    });
+    const meta = updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
+    return new Set(loadIgnoredEntries(meta).map((e) => e.name));
 }
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export async function removeIgnored(name) {
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        if (!set.delete(name))
-            return false;
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return true;
+    let removed = false;
+    updateMeta((m) => {
+        const fleet = m.fleet;
+        if (!fleet?.ignored)
+            return m;
+        const entries = loadIgnoredEntries(m);
+        const next = entries.filter((e) => e.name !== name);
+        if (next.length === entries.length)
+            return m;
+        removed = true;
+        const nextFleet = { ...fleet, ignored: next };
+        return { ...m, fleet: nextFleet };
     });
+    return removed;
 }

package/dist/lib/devices/stats-cache.d.ts

@@ -8,8 +8,12 @@ import type { DeviceProfile } from './registry.js';
  * rewrites the cache, unreachable boxes included).
  */
 export declare const STATS_STALE_MS: number;
+/** Static hardware totals are valid for seven days. */
+export declare const SPECS_STALE_MS: number;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export declare function isFreshDeviceSpecs(stats: DeviceStats, now?: number): boolean;
 /** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export declare function readStatsCache(): Record<string, DeviceStats>;
 /**
@@ -30,6 +34,8 @@ export interface FleetStatsResult {
 export interface LoadFleetStatsOptions {
     /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
     forceRefresh?: boolean;
+    /** Read only static hardware facts, whose cache lifetime is seven days. */
+    specsOnly?: boolean;
     /** Device name of THIS machine — always probed locally (no ssh), never cached-served. */
     selfName?: string;
     /** Injectable probes + cache IO for tests (default to the real ssh/local/disk ones). */

package/dist/lib/devices/stats-cache.js

@@ -37,10 +37,17 @@ const CACHE_FILE = '.fleet-stats.json';
  * rewrites the cache, unreachable boxes included).
  */
 export const STATS_STALE_MS = 3 * 60_000;
+/** Static hardware totals are valid for seven days. */
+export const SPECS_STALE_MS = 7 * 24 * 60 * 60_000;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export function isFreshDeviceStats(stats, now = Date.now()) {
     return now - stats.fetchedAt <= STATS_STALE_MS;
 }
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export function isFreshDeviceSpecs(stats, now = Date.now()) {
+    const fetchedAt = stats.specsFetchedAt ?? stats.fetchedAt;
+    return now - fetchedAt <= SPECS_STALE_MS;
+}
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
@@ -93,13 +100,14 @@ export async function loadFleetStats(devices, opts = {}) {
     const toProbe = [];
     let servedFromCache = false;
     for (const d of devices) {
-        if (d.name === self) {
+        if (d.name === self && !opts.specsOnly) {
             // This machine is always probed locally — cheap, no ssh, always live.
             toProbe.push(d);
             continue;
         }
         const cached = cache[d.name];
-        if (cached && isFreshDeviceStats(cached, now)) {
+        const cacheFresh = cached && (opts.specsOnly ? isFreshDeviceSpecs(cached, now) : isFreshDeviceStats(cached, now));
+        if (cached && cacheFresh) {
             stats.set(d.name, cached);
             servedFromCache = true;
         }

package/dist/lib/exec.d.ts

@@ -94,6 +94,8 @@ export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 export interface ExecOptions {
     agent: AgentId;
     version?: string;
+    /** Version home whose native auth/config is overlaid onto this run's binary. */
+    configVersion?: string;
     /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
     /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
@@ -398,7 +400,7 @@ export interface TmuxWrapContext {
     raw: boolean;
     /** The AGENTS_NO_TMUX=1 escape hatch. */
     noTmuxEnv: boolean;
-    /** This device's `tmux.enabled` config — false turns the wrap off for every launch on this box. */
+    /** This device's `tmux.enabled` config — true opts every eligible launch on this box into the wrap. */
     configEnabled: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
@@ -407,7 +409,7 @@ export interface TmuxWrapContext {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * Opting into tmux wrapping gives every interactive agent an exact, unique `%pane` handle so
  * `agents sessions --active` can tell co-located agents apart, and lets `agents
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
@@ -418,7 +420,7 @@ export interface TmuxWrapContext {
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
+ *   - tmux.enabled    — this device explicitly opted into addressable tmux panes.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
@@ -482,6 +484,26 @@ export declare const UNKNOWN_OUTCOME_EXIT_CODE = 1;
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+export declare function detectOutOfCredits(text: string): boolean;
+/**
+ * Classify what a Claude run's output + exit code means for the account's
+ * persisted refusal marker. Pure and exported so the persist/clear decision is
+ * unit-tested on the real path (runWithFallback can't be driven with a real
+ * `claude` spawn in tests). Precedence: a session-limit reset wins (it carries a
+ * clock), then a clock-less billing exhaustion, then a clean success clears any
+ * stale marker; anything else leaves the marker untouched.
+ */
+export type ClaudeRefusalAction = {
+    action: 'note_session';
+    resetsAt: Date;
+} | {
+    action: 'note_out_of_credits';
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export declare function classifyClaudeRunRefusal(output: string, exitCode: number): ClaudeRefusalAction;
 /**
  * Patterns that indicate an authentication failure — the agent is logged out,
  * its token was revoked, or the session expired. These are the user-visible

package/dist/lib/exec.js

@@ -28,7 +28,7 @@ import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
-import { isTmuxEnabled } from './device-config.js';
+import { isTmuxEnabled, selfConfiguredDeviceRole } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
@@ -38,7 +38,7 @@ import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
 import { getAccountInfo } from './agents.js';
-import { getUsageLookupKey, noteClaudeSessionLimit, parseClaudeSessionLimitReset } from './accounting/usage.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset } from './accounting/usage.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -293,17 +293,28 @@ export function buildExecEnv(options) {
         // Resolve version/versionHome here (this module already imports
         // installations/versions); the adapters must not import it themselves or they
         // close a versions -> shims -> harness -> adapter import cycle.
-        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version);
+        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion ?? options.version);
         configAdapter.applyExecConfigEnv(result, {
             agent: options.agent,
             version,
             versionHome,
             interactive: resolveInteractive(options),
+            deviceRole: selfConfiguredDeviceRole(),
             resolveClaudeSetupToken,
         });
     }
     else {
         stripForeignConfigDir(result);
+        // Grok's adapter owns the same GROK_HOME export in generated shims, but a
+        // labeled account deliberately runs one version's binary with another
+        // version's config. Apply that overlay here because the shim's binary-slot
+        // export cannot express a distinct account slot.
+        if (options.agent === 'grok' && options.configVersion) {
+            const { versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion);
+            if (!versionHome)
+                throw new Error(`Cannot resolve Grok account config home for ${options.configVersion}.`);
+            result.GROK_HOME = path.join(versionHome, '.grok');
+        }
     }
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
@@ -322,6 +333,7 @@ export function buildExecEnv(options) {
     // every event the child emits. `options.sessionId` is the CHILD's id, so read the
     // spawner from the live env; guard a same-session resume from naming itself parent.
     // Local-spawn scope here; forwarding it across the `--device` SSH hop is Phase 4.
+    delete result.AGENTS_PARENT_SESSION_ID;
     const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
     if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
@@ -388,6 +400,7 @@ export const AGENT_COMMANDS = {
             // independent; legacy --sandbox flags cannot express that combination.
             plan: [],
             edit: [],
+            auto: [],
             // skip = codex --yolo: drops the sandbox entirely and approves anything.
             skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
@@ -1163,7 +1176,7 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * Opting into tmux wrapping gives every interactive agent an exact, unique `%pane` handle so
  * `agents sessions --active` can tell co-located agents apart, and lets `agents
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
@@ -1174,7 +1187,7 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
+ *   - tmux.enabled    — this device explicitly opted into addressable tmux panes.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export function shouldWrapInTmux(ctx) {
@@ -1282,11 +1295,14 @@ export function formatPaneTail(raw, maxLines = 30) {
  * Lifecycle:
  *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
  *      on (global), and returns the pane id.
- *   2. A per-session `pane-died` hook detaches the attach client the instant the
- *      AGENT pane exits, so attach returns instead of parking on a dead pane. The
- *      hook is guarded on `#{hook_pane}` so it fires ONLY for the agent pane —
- *      user-created splits (Ctrl-b " / %) that the user exits are closed in place
- *      (`kill-pane`) instead of tearing down the whole client, so exiting one
+ *   2. A per-session `pane-died` hook tears the session down the instant the AGENT
+ *      pane exits: with a client attached it `detach-client`s so attach returns
+ *      instead of parking on a dead pane (then resolveAfterAttach reads the status
+ *      and kills); with no client attached it `kill-session`s outright, so a
+ *      wrapped agent that exits unattended can't leave a dead husk lingering on the
+ *      socket. The hook is guarded on `#{hook_pane}` so it fires ONLY for the agent
+ *      pane — user-created splits (Ctrl-b " / %) that the user exits are closed in
+ *      place (`kill-pane`) instead of tearing down the whole client, so exiting one
  *      split leaves the agent running full-window rather than kicking you out.
  *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
  *      headless active-scan attributes it, then attach the TTY (blocking).
@@ -1303,7 +1319,7 @@ async function runInTmux(options, executable, args) {
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
-    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.\n  If tmux is broken on this machine, turn the wrap off for good: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
+    const NO_TMUX_TIP = `${GRAY}  This run used the opt-in tmux wrap. Re-run with --no-tmux for a direct launch, or turn the wrap off: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
     // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
@@ -1600,11 +1616,10 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
-    // Interactive spawn-wrap: on macOS/Linux, run the agent INSIDE a shared-socket
-    // tmux session (then attach this TTY) so it gets a unique, addressable %pane.
-    // Headless runs, Windows, already-in-tmux, --raw, and AGENTS_NO_TMUX=1 keep the
-    // bare spawn below. See shouldWrapInTmux / runInTmux.
-    if (shouldWrapInTmux({
+    // Interactive spawn-wrap: when this device opts in on macOS/Linux, run the
+    // agent INSIDE a shared-socket tmux session (then attach this TTY) so it gets
+    // a unique, addressable %pane. Every failed guard keeps the bare spawn below.
+    const wrapInTmux = shouldWrapInTmux({
         interactive,
         platform: process.platform,
         inTmux: !!process.env.TMUX,
@@ -1612,7 +1627,8 @@ async function spawnAgent(options) {
         noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
         configEnabled: isTmuxEnabled(),
         tmuxAvailable: isTmuxInstalled(),
-    })) {
+    });
+    if (wrapInTmux) {
         timer.mark('startup');
         try {
             const result = await runInTmux(options, executable, args);
@@ -1865,6 +1881,29 @@ export const RATE_LIMIT_PATTERNS = [
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
+/**
+ * Narrow detector for a BILLING exhaustion — tokens/credits run out or the
+ * monthly spend cap is hit — as opposed to a time-window rate limit. This class
+ * does NOT recover on a clock, so rotation must remember it per-account
+ * (noteClaudeOutOfCredits) until a later successful run clears it.
+ */
+const OUT_OF_CREDITS_PATTERNS = [
+    /out of (?:usage )?credits/i,
+    /spend[\s-]?limit/i,
+];
+export function detectOutOfCredits(text) {
+    return OUT_OF_CREDITS_PATTERNS.some(pattern => pattern.test(text));
+}
+export function classifyClaudeRunRefusal(output, exitCode) {
+    const sessionLimitReset = parseClaudeSessionLimitReset(output);
+    if (sessionLimitReset)
+        return { action: 'note_session', resetsAt: sessionLimitReset };
+    if (detectOutOfCredits(output))
+        return { action: 'note_out_of_credits' };
+    if (exitCode === 0)
+        return { action: 'clear' };
+    return { action: 'none' };
+}
 /**
  * Patterns that indicate an authentication failure — the agent is logged out,
  * its token was revoked, or the session expired. These are the user-visible
@@ -2086,12 +2125,26 @@ export async function runWithFallback(options) {
             throw err;
         }
         const output = `${result.stderr}\n${result.stdout}`;
+        // Persist a per-account refusal marker so rotation stops re-picking a
+        // known-dead account: a session-limit recovers on its clock, a billing
+        // exhaustion (tokens/credits) recovers only on a later successful run, and a
+        // clean run clears any stale marker. Decision extracted + unit-tested in
+        // classifyClaudeRunRefusal.
         const sessionLimitReset = agent === 'claude' ? parseClaudeSessionLimitReset(output) : null;
-        if (sessionLimitReset && version) {
-            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
-            const usageKey = getUsageLookupKey(account);
-            if (usageKey)
-                noteClaudeSessionLimit(usageKey, sessionLimitReset);
+        if (agent === 'claude' && version) {
+            const refusal = classifyClaudeRunRefusal(output, result.exitCode ?? 1);
+            if (refusal.action !== 'none') {
+                const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+                const usageKey = getUsageLookupKey(account);
+                if (usageKey) {
+                    if (refusal.action === 'note_session')
+                        noteClaudeSessionLimit(usageKey, refusal.resetsAt);
+                    else if (refusal.action === 'note_out_of_credits')
+                        noteClaudeOutOfCredits(usageKey);
+                    else if (refusal.action === 'clear')
+                        clearClaudeAccountRefusal(usageKey);
+                }
+            }
         }
         if (result.exitCode === 0 && !sessionLimitReset)
             return 0;

package/dist/lib/feed/answer.d.ts

@@ -0,0 +1,29 @@
+import { type ActiveSession } from '../session/active.js';
+import { type MessageReceipt } from './feed.js';
+export interface VerifiedOperator {
+    id?: string;
+    verified: boolean;
+    label?: string;
+}
+export interface FeedAnswerResult {
+    status: 'delivered' | 'already_answered';
+    receipt: MessageReceipt;
+}
+/** Atomically claim the first answer, then route it over the session's recorded reply rail. */
+export declare function claimAndRouteAttentionAnswer(input: {
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operator: VerifiedOperator;
+    feedRoot?: string;
+    mailboxRoot?: string;
+    sessions?: ActiveSession[];
+}): Promise<FeedAnswerResult>;
+/** Forward a fleet attention answer to the device that owns its scope. */
+export declare function forwardFeedAnswer(input: {
+    host: string;
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operatorId?: string;
+}): Promise<FeedAnswerResult>;