@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/dist/commands/ssh.js

@@ -34,7 +34,7 @@ import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { getDeviceDiscoveryStatus, setDeviceDiscoveryStatus } from '../lib/devices/discovery-policy.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, isAgentsBrowserDrive, markFleetRemote, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -351,9 +351,21 @@ function trySshLeasedBox(name, cmd) {
         console.error(chalk.red(`Leased box '${name}' is not reachable yet (status: ${boxStatus(box)}).`));
         process.exit(1);
     }
-    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...cmd], { stdio: 'inherit' });
+    // Crabbox ssh does not go through buildSshInvocation; stamp the same
+    // consent marker so a browser drive on a leased box is gated too.
+    const remoteCmd = leasedBoxRemoteCmd(cmd);
+    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...remoteCmd], { stdio: 'inherit' });
     process.exit(res.status ?? 1);
 }
+/**
+ * Remote argv for `agents ssh <slug>` into a leased crabbox. Crabbox ssh does
+ * not go through {@link buildSshInvocation}, so this stamps the same
+ * AGENTS_FLEET_REMOTE consent marker a registered-device ssh would (PHNX-3065).
+ * Exported so the branch is unit-testable without a live crabbox.
+ */
+export function leasedBoxRemoteCmd(cmd) {
+    return isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, { shell: 'posix' }) : cmd;
+}
 /** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
@@ -2412,6 +2424,10 @@ An interactive login with no command mirrors the home-relative directory you
 launched from — 'agents ssh yosemite-s0' from ~/src/app lands in ~/src/app on
 the target when it exists, else the remote home. Same portable-cwd rule as
 'agents run --device'. Passing a command keeps the remote home.
+
+An 'agents browser …', 'ag browser …', or standalone 'browser …' command is
+stamped AGENTS_FLEET_REMOTE so the target's browser.remote-control consent
+gate applies, same as 'agents browser <verb> --device <name>'.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.

package/dist/commands/status.js

@@ -97,6 +97,20 @@ export function registerStatusCommand(syncCmd) {
         if (status.totals.orphan > 0) {
             console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
         }
+        // Config drift is its OWN class, not a per-agent "N missing": a box that has
+        // not folded its device-scoped state still carries a stale top-level header or
+        // a lingering central fleet/hosts/accounts/browser block. Surface it distinctly
+        // so an un-drained box is SEEN here instead of via a mystery pull conflict
+        // (PHNX-3315).
+        if (status.config.staleHeader || status.config.centralLeaks.length > 0) {
+            console.log(`  ${'config (device-scoped)'.padEnd(28)} ${chalk.yellow('not drained — folds automatically on normal `agents` use here (idempotent)')}`);
+            if (status.config.staleHeader) {
+                console.log(chalk.gray('    · top-level agents.yaml header is stale (pre-rename)'));
+            }
+            for (const leak of status.config.centralLeaks) {
+                console.log(chalk.gray(`    · central ${leak} should be device-scoped`));
+            }
+        }
         // Hand off to the shared interactive/apply flow (summary already printed above).
         await promptDriftSync({ cwd, yes: opts.yes, status, quiet: true });
     });

package/dist/commands/view.d.ts

@@ -11,6 +11,7 @@ import { accountDisplayLabel } from '../lib/agents.js';
 import type { AccountInfo } from '../lib/agents.js';
 import type { AgentId } from '../lib/types.js';
 import type { FormatUsageSummaryOpts, UsageInfo } from '../lib/accounting/usage.js';
+import { type ConfiguredDeviceRole } from '../lib/device-config.js';
 import type { ResourceSection, ViewJsonAgent } from '../lib/view-types.js';
 export type { ResourceItemJson, ResourceSection, SyncState, VersionResourcesJson, ViewJsonAgent, ViewJsonVersion } from '../lib/view-types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
@@ -68,6 +69,13 @@ export declare function descriptionForPrefix(desc: string | undefined, prefix: s
  * host is missing is flagged rather than silently listed as runnable.
  */
 export declare function renderHarnessBlocks(harnesses: ProfileSummary[], installedHosts: Set<AgentId>, showPaths: boolean, byokMap?: Map<string, ByokUsageResult>): void;
+/**
+ * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
+ * tested directly: a usage read may fall through to the interactive OAuth login
+ * ONLY for a foreground human render on a `personal` device. Both conditions are
+ * required — role alone is not sufficient.
+ */
+export declare function allowInteractiveUsageLogin(role: ConfiguredDeviceRole | undefined, isTTY: boolean): boolean;
 /** Build the set of resource sections to include in `--json` from the
  *  `--resources` / `--detailed` flags, plus (in --json mode) the per-section
  *  boolean filters (`--skills` etc.) that plain `--json` historically ignored. */
@@ -81,7 +89,9 @@ export declare function parseResourceSections(options: {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>): Promise<ViewJsonAgent[]>;
+export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>, opts?: {
+    forceRefresh?: boolean;
+}): Promise<ViewJsonAgent[]>;
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an

package/dist/commands/view.js

@@ -8,7 +8,8 @@ import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanag
 import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
-import { agentReportsUsage, classifyUsageErrorKind, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageBenignState, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, } from '../lib/accounting/usage.js';
+import { agentReportsUsage, classifyUsageErrorKind, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageBenignState, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, usageErrorForDisplay, } from '../lib/accounting/usage.js';
+import { selfConfiguredDeviceRole } from '../lib/device-config.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/installations/shims.js';
@@ -316,6 +317,29 @@ function renderHostClisSection(cwd) {
         console.log(`  ${chalk.red('error')}      ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
     }
 }
+/**
+ * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
+ * tested directly: a usage read may fall through to the interactive OAuth login
+ * ONLY for a foreground human render on a `personal` device. Both conditions are
+ * required — role alone is not sufficient.
+ */
+export function allowInteractiveUsageLogin(role, isTTY) {
+    return role === 'personal' && isTTY === true;
+}
+/**
+ * Whether this `agents view` invocation may fall through to the interactive
+ * OAuth login for a usage read (USAGE-READ-2). True only for a foreground human
+ * render on a `personal` device: the interactive login is the sole credential
+ * carrying the `user:profile` scope the usage endpoint needs, and a human
+ * running one command is not the unattended-loop revocation risk RUSH-1822
+ * fixed. The `--json` path never reaches these render functions (it returns
+ * early via `collectAgentsJson`), and a non-TTY (piped/scripted) run is excluded
+ * here too, so a machine reader can never silently acquire the interactive
+ * credential — role alone is not sufficient.
+ */
+function usageAllowInteractiveLogin() {
+    return allowInteractiveUsageLogin(selfConfiguredDeviceRole(), process.stdout.isTTY === true);
+}
 async function showInstalledVersions(filterAgentId, viewOpts) {
     const spinnerText = filterAgentId
         ? `Checking ${agentLabel(filterAgentId)} agents...`
@@ -422,7 +446,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             cliVersion,
             info,
         })),
-    ], { forceRefresh: viewOpts?.forceRefresh });
+    ], {
+        forceRefresh: viewOpts?.forceRefresh,
+        allowInteractiveLogin: usageAllowInteractiveLogin(),
+    });
     spinner.stop();
     console.log(chalk.bold('Installed Agent CLIs\n'));
     const mergeCanonical = (info) => {
@@ -930,7 +957,7 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             home,
             cliVersion: version,
             info: accountInfo,
-        });
+        }, { allowInteractiveLogin: usageAllowInteractiveLogin() });
         const accountLabel = accountColumnLabel(accountInfo);
         const emailStr = accountLabel ? chalk.cyan(`  ${accountLabel}`) : '';
         const status = chalk.green(version);
@@ -1209,7 +1236,7 @@ export function parseResourceSections(options, jsonMode) {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-export async function collectAgentsJson(filterAgentId, resourceSections) {
+export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const authCache = readAuthHealthCache();
     const host = machineId();
@@ -1230,7 +1257,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
         home,
         cliVersion: version,
         info,
-    })));
+    })), { forceRefresh: opts?.forceRefresh === true });
     const mergeCanonical = (info) => {
         const key = getUsageLookupKey(info);
         if (!key)
@@ -1273,6 +1300,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
             plan: info.plan,
             usageStatus: info.usageStatus,
             overageCredits: info.overageCredits,
+            usageError: usageErrorForDisplay(usageInfo?.error),
             windows: snapshot
                 ? snapshot.windows.map((w) => ({
                     key: w.key,
@@ -1562,7 +1590,7 @@ export async function viewAction(agentArg, options) {
             return;
         }
         if (json) {
-            const data = await collectAgentsJson(undefined, resourceSections);
+            const data = await collectAgentsJson(undefined, resourceSections, { forceRefresh });
             console.log(JSON.stringify(data, null, 2));
             return;
         }
@@ -1624,7 +1652,7 @@ export async function viewAction(agentArg, options) {
     if (json) {
         // --json ignores the @version suffix, but --resources/--detailed (or a
         // section flag) now attach each version's resource inventory + sync-state.
-        const data = await collectAgentsJson(agentId, resourceSections);
+        const data = await collectAgentsJson(agentId, resourceSections, { forceRefresh });
         console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], harnesses: [] }, null, 2));
         return;
     }

package/dist/lib/account-registry.js

@@ -23,9 +23,9 @@ import * as yaml from 'yaml';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { getUserAgentsDir, readMeta, updateMeta } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken } from './secrets/index.js';
-import { bundleExists, deleteBundle, listBundles, readBundle, renameBundle, writeBundleWithItems } from './secrets/bundles.js';
+import { bundleExists, deleteBundle, listBundles, readAndResolveBundleEnv, readBundle, renameBundle, writeBundleWithItems } from './secrets/bundles.js';
 import { getAccountProvider } from './account-provider-registry.js';
-import { accountSecretItem, buildAccountBundle, parseAccountBundle } from './account-schema.js';
+import { accountSecretItem, buildAccountBundle, parseAccountBundle, secretVarFor } from './account-schema.js';
 const NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const NATIVE_LABEL = /^[a-zA-Z0-9][a-zA-Z0-9@._+-]*$/;
 const AUTH_KINDS = ['api-key', 'setup-token', 'bearer-token'];
@@ -455,6 +455,18 @@ export function resolveCredentialAccount(name, host, expectedProvider, base = ge
     const envVar = account.auth === 'setup-token' ? 'CLAUDE_CODE_OAUTH_TOKEN' : adapter.envFor(host, account.auth);
     if (!hasKeychainToken(account.secretRef))
         throw new Error(`Credential for account '${account.name}' is missing on this device. Add it with 'agents accounts set-key ${account.name}'.`);
+    const secretVar = secretVarFor(account.auth);
+    // Account bundles are policy `never`, so their value items carry no biometry
+    // ACL. Resolve through the bundle path that verifies that policy and attests
+    // `silentNoAcl` to the headless keychain guard. Calling getKeychainToken()
+    // directly makes a headless --account launch reject the prompt-free item as
+    // if it required Touch ID before the helper ever reads it (PHNX-2939).
+    const secret = readAndResolveBundleEnv(account.name, {
+        keys: [secretVar],
+        keyMode: 'storage',
+        agentOnly: true,
+        caller: 'accounts resolve',
+    }).env[secretVar];
     const connectionEnv = { ...adapter.connectionEnvFor(host) };
     if (account.baseUrl) {
         const baseUrlEnv = adapter.baseUrlEnvFor(host);
@@ -467,7 +479,7 @@ export function resolveCredentialAccount(name, host, expectedProvider, base = ge
         name: account.name,
         provider: account.provider,
         auth: account.auth,
-        env: { ...connectionEnv, [envVar]: getKeychainToken(account.secretRef) },
+        env: { ...connectionEnv, [envVar]: secret },
     };
 }
 /**

package/dist/lib/accounting/rotate.d.ts

@@ -336,16 +336,30 @@ export declare function resolveAccountVersion(agent: AgentId, account: string):
 export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
+/**
+ * Resolve the version `agents run` should use when the caller did not pin
+ * one with `@version`. The caller supplies the effective strategy.
+ *
+ * `pinned` still prefers the workspace/global default, but it MUST NOT launch
+ * a logged-out (or revoked) default when the same device holds a signed-in
+ * version that can run — that was a silent 1-second death on fleet workers
+ * whose default home had no credential (PHNX-2685). A rate-limited pin is
+ * still honoured: `--strategy pinned` remains the escape hatch to force the
+ * default through a throttle. When the default is auth-blocked and nothing
+ * else is healthy, `exhausted` is set so the caller fails loud instead of
+ * spawning into a credential-less home.
+ */
 export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string, collect?: (agent: AgentId) => Promise<RotateCandidate[]>): Promise<{
     version: string | null;
     rotation: RotateResult | null;
     /**
-     * Set when a non-pinned strategy found ZERO healthy candidates among the
-     * installed versions: the full excluded set, so callers fail loud with
-     * per-account reasons instead of launching the exhausted pinned default
-     * (RUSH-2132). Undefined for pinned, for successful picks, and when no
-     * version is installed at all (the pre-existing not-installed path — there
-     * is no account to be "unhealthy").
+     * Set when a strategy found ZERO healthy candidates among the installed
+     * versions: the full excluded set, so callers fail loud with per-account
+     * reasons instead of launching the exhausted pinned default (RUSH-2132).
+     * Also set for `pinned` when the default is logged out / revoked and no
+     * signed-in alternative exists (PHNX-2685). Undefined for successful picks
+     * and when no version is installed at all (the pre-existing not-installed
+     * path — there is no account to be "unhealthy").
      */
     exhausted?: RotateCandidate[];
 }>;

package/dist/lib/accounting/rotate.js

@@ -690,12 +690,6 @@ export async function selectBalancedVersion(agent) {
 export async function selectAvailableVersion(agent, preferredVersion) {
     return pickAvailableCandidate(await collectRunCandidates(agent), preferredVersion);
 }
-/**
- * Resolve the version `agents run` should use when the caller did not pin
- * one with `@version`. The caller supplies the effective strategy; if that
- * strategy cannot find a usable candidate, fall back to the pinned
- * workspace/global version.
- */
 /**
  * Record a rotation pick so parallel callers see it as recently-used.
  * Writes a stamp file per agent — lightweight, no locking needed since
@@ -722,12 +716,49 @@ function readRotationStamp(agent) {
     catch { /* missing or corrupt — treat as no stamp */ }
     return null;
 }
+/**
+ * Resolve the version `agents run` should use when the caller did not pin
+ * one with `@version`. The caller supplies the effective strategy.
+ *
+ * `pinned` still prefers the workspace/global default, but it MUST NOT launch
+ * a logged-out (or revoked) default when the same device holds a signed-in
+ * version that can run — that was a silent 1-second death on fleet workers
+ * whose default home had no credential (PHNX-2685). A rate-limited pin is
+ * still honoured: `--strategy pinned` remains the escape hatch to force the
+ * default through a throttle. When the default is auth-blocked and nothing
+ * else is healthy, `exhausted` is set so the caller fails loud instead of
+ * spawning into a credential-less home.
+ */
 export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates) {
     const fallback = resolveVersion(agent, cwd);
+    const candidates = await collect(agent);
     if (strategy === 'pinned') {
+        const pinnedCandidate = fallback
+            ? candidates.find((c) => c.version === fallback)
+            : undefined;
+        // Auth-blocked pin: the home cannot authenticate, so launching it is a
+        // guaranteed miss. Prefer a signed-in sibling on this device.
+        if (pinnedCandidate && isSignInRecoverable(readinessFromCandidate(pinnedCandidate))) {
+            const rotation = pickAvailableCandidate(candidates, fallback);
+            if (rotation) {
+                emit('rotation.resolved', {
+                    module: 'rotate',
+                    agent,
+                    version: rotation.picked.version,
+                    strategy,
+                    healthy: rotation.healthy.length,
+                    excluded: rotation.excluded.length,
+                });
+                return { version: rotation.picked.version, rotation };
+            }
+            return {
+                version: fallback,
+                rotation: null,
+                exhausted: candidates.length > 0 ? candidates : undefined,
+            };
+        }
         return { version: fallback, rotation: null };
     }
-    const candidates = await collect(agent);
     const rotation = strategy === 'available'
         ? pickAvailableCandidate(candidates, fallback)
         : pickBalancedCandidate(candidates);

package/dist/lib/accounting/usage.d.ts

@@ -22,6 +22,12 @@ import type { AgentId } from '../types.js';
  */
 export declare function usageNoCredentialError(agent: string): string;
 export declare function usageExpiredCredentialError(agent: string): string;
+/**
+ * Kimi-specific expired-credential wording. A normal Kimi launch refreshes its
+ * own OAuth access token, so the recovery action for an expired Kimi credential
+ * is to run Kimi once — not to re-auth through agents-cli (RUSH-3198).
+ */
+export declare function usageExpiredKimiCredentialError(): string;
 export declare function usageRejectedError(agent: string, status: number): string;
 /**
  * Canonical phrase for the Anthropic setup-token scope gap (RUSH-2392).
@@ -39,6 +45,26 @@ export declare const USAGE_HEADLESS_SCOPE_MARKER = "usage unavailable (headless)
 export declare function usageHeadlessScopeError(agent?: string): string;
 /** True when an error string is the setup-token scope gap (RUSH-2392). */
 export declare function isUsageHeadlessScopeError(error: string | null | undefined): boolean;
+/**
+ * Canonical phrase for a Claude account the usage reader holds no usable
+ * credential for. Distinct from {@link USAGE_HEADLESS_SCOPE_MARKER}, which
+ * means a setup-token WAS read and the endpoint refused its scope.
+ */
+export declare const USAGE_NO_USAGE_CREDENTIAL_MARKER = "usage unavailable (no usage credential)";
+/**
+ * Claude's own no-credential message. The shared
+ * {@link usageNoCredentialError} offers "sign in" as the remedy, which holds
+ * for Kimi/Droid/Cursor — their CLIs rotate a readable token on the next launch
+ * — and is false for Claude: the usage read deliberately never touches the
+ * interactive login (RUSH-1822), so an account that IS signed in reads as
+ * unreadable here and signing in again changes nothing. Naming only the second
+ * remedy would send the operator to `claude setup-token`, whose token then hits
+ * the `user:profile` scope gap (RUSH-2392) — the loop reported in #2987 — so
+ * this message states both constraints and that the account still runs.
+ */
+export declare function usageNoClaudeUsageCredentialError(): string;
+/** True when an error string is the Claude no-usage-credential state (#2987). */
+export declare function isUsageNoUsageCredentialError(error: string | null | undefined): boolean;
 /**
  * Detect Anthropic's usage-endpoint scope denial: HTTP 403 whose body names
  * `user:profile` (or "scope requirement"). A bare 403 without that body stays
@@ -72,6 +98,28 @@ export declare function usageUnreachableError(agent: string, cause?: unknown): s
 export declare const USAGE_NO_RECENT_USAGE_MARKER = "no usage recorded yet";
 export declare const USAGE_BENIGN_STATE: unique symbol;
 export type UsageBenignState = 'no-recent-usage';
+/**
+ * Sentinel `UsageInfo.error` for a read-only lookup whose cache held nothing
+ * (`getUsageInfoForIdentity`). No request was made and nothing failed — the
+ * daemon simply has not collected this account yet. It was an unclassified
+ * literal, so `classifyUsageErrorKind` fell through to `'rejected'` and
+ * `agents view` printed the generic "usage unavailable" for a cold cache,
+ * which reads as a failure the operator should chase (#2987). The string value
+ * is unchanged; callers that already compare against `'stale'` keep working.
+ */
+export declare const USAGE_NOT_COLLECTED_MARKER = "stale";
+/**
+ * Human-facing form of a `UsageInfo.error` for a machine/JSON consumer
+ * (`agents view --json`'s `usageError`). Every error string this module
+ * constructs is already a full human sentence EXCEPT the internal
+ * {@link USAGE_NOT_COLLECTED_MARKER} (`'stale'`) sentinel, which a read-only
+ * lookup returns for a never-cached account when `--refresh` was not passed. That
+ * value is an internal cache signal, not an error message, and leaking it verbatim
+ * contradicts the field's "human-readable" contract (PHNX-3348). Map it to a
+ * plain-language, actionable string and pass every genuine error through
+ * unchanged. Returns `null` when there is no error.
+ */
+export declare function usageErrorForDisplay(error: string | null | undefined): string | null;
 /**
  * Shared error-classification + 429 backoff for a networked usage fetch whose
  * only signal is an HTTP status (or none at all, on a network failure) —
@@ -91,7 +139,7 @@ export declare function classifyUsageFetchFailure(agent: string, agentId: 'antig
  * distinct causes (RUSH-3040). Matched against the canonical strings this file
  * constructs — never re-derive these prefixes at a call site.
  */
-export type UsageErrorKind = 'no-credential' | 'expired-credential' | 'rate-limited' | 'rejected' | 'headless-scope' | 'unreachable';
+export type UsageErrorKind = 'no-credential' | 'no-usage-credential' | 'expired-credential' | 'rate-limited' | 'rejected' | 'headless-scope' | 'unreachable' | 'not-collected';
 /** Classify a `UsageInfo.error` string into its {@link UsageErrorKind}, or null when there is no error. */
 export declare function classifyUsageErrorKind(error: string | null | undefined): UsageErrorKind | null;
 /**
@@ -176,6 +224,16 @@ interface UsageOptions {
      * setup-token, or `<home>/.claude/.credentials.json` only.
      */
     fileOnly?: boolean;
+    /**
+     * When true, a read that finds no file-based setup-token MAY fall through to
+     * Claude Code's interactive OAuth login (the only credential carrying
+     * `user:profile`, which `/api/oauth/usage` requires). OFF by default and set
+     * ONLY by a foreground human `agents view` on a `personal` device (see
+     * USAGE-READ-2). Every background caller — daemon usage warm, auth-health
+     * probe, watchdog — leaves it unset, preserving the RUSH-1822 guarantee that
+     * an unattended loop never transmits the interactive login to Anthropic.
+     */
+    allowInteractiveLogin?: boolean;
 }
 /** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
@@ -272,6 +330,14 @@ export declare const USAGE_FETCH_CONCURRENCY = 3;
 export interface UsageLookupOptions {
     forceRefresh?: boolean;
     fileOnly?: boolean;
+    /**
+     * Permit a foreground personal-device usage read to fall through to the
+     * interactive login when no setup-token exists (USAGE-READ-2). Set ONLY by
+     * `agents view` when `selfConfiguredDeviceRole() === 'personal'` and the
+     * output is a human TTY (not `--json`). Threads into `getClaudeUsageInfo` →
+     * `loadClaudeOauth`. Unset for every other lookup.
+     */
+    allowInteractiveLogin?: boolean;
 }
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: UsageLookupOptions): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
@@ -574,6 +640,7 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
 export declare function loadClaudeOauth(home?: string, opts?: {
     accessTokenCache?: boolean;
     fileOnly?: boolean;
+    allowInteractiveLogin?: boolean;
 }): Promise<ClaudeOauthCredentials | null>;
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.