@phnx-labs/agents-cli 1.22.53 → 1.22.54

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,16 @@ 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";
 /**
  * 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 +127,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;
 /**

package/dist/lib/accounting/usage.js

@@ -59,6 +59,14 @@ export function usageNoCredentialError(agent) {
 export function usageExpiredCredentialError(agent) {
     return `${agent} credential expired — re-auth this account (a usage read never refreshes it).`;
 }
+/**
+ * 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 function usageExpiredKimiCredentialError() {
+    return `Kimi credential expired — run Kimi once to refresh it (a usage read never refreshes it).`;
+}
 export function usageRejectedError(agent, status) {
     return status === 429
         ? `${agent} is rate-limiting the usage endpoint for this machine (HTTP 429).`
@@ -84,6 +92,31 @@ export function usageHeadlessScopeError(agent = 'Claude') {
 export function isUsageHeadlessScopeError(error) {
     return typeof error === 'string' && error.includes(USAGE_HEADLESS_SCOPE_MARKER);
 }
+/**
+ * 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 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 function usageNoClaudeUsageCredentialError() {
+    return (`Claude ${USAGE_NO_USAGE_CREDENTIAL_MARKER} — a usage read never uses your login ` +
+        '(RUSH-1822); a setup-token cannot read usage (RUSH-2392). The account still runs.');
+}
+/** True when an error string is the Claude no-usage-credential state (#2987). */
+export function isUsageNoUsageCredentialError(error) {
+    return typeof error === 'string' && error.includes(USAGE_NO_USAGE_CREDENTIAL_MARKER);
+}
 /**
  * Detect Anthropic's usage-endpoint scope denial: HTTP 403 whose body names
  * `user:profile` (or "scope requirement"). A bare 403 without that body stays
@@ -130,6 +163,16 @@ export function usageUnreachableError(agent, cause) {
  */
 export const USAGE_NO_RECENT_USAGE_MARKER = 'no usage recorded yet';
 export const USAGE_BENIGN_STATE = Symbol('usageBenignState');
+/**
+ * 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 const USAGE_NOT_COLLECTED_MARKER = 'stale';
 /**
  * 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) —
@@ -155,8 +198,12 @@ export function classifyUsageFetchFailure(agent, agentId, status, retryAfterHead
 export function classifyUsageErrorKind(error) {
     if (!error)
         return null;
+    if (error === USAGE_NOT_COLLECTED_MARKER)
+        return 'not-collected';
     if (isUsageHeadlessScopeError(error))
         return 'headless-scope';
+    if (isUsageNoUsageCredentialError(error))
+        return 'no-usage-credential';
     if (error.startsWith('No readable '))
         return 'no-credential';
     if (error.includes('credential expired'))
@@ -342,7 +389,7 @@ export async function getUsageInfoForIdentity(input, opts) {
     // cache file holds every account without collision.
     if (!usageKey) {
         if (readOnly)
-            return { snapshot: null, error: 'stale' };
+            return { snapshot: null, error: USAGE_NOT_COLLECTED_MARKER };
         return getUsageInfo(input.agentId, {
             home: input.home,
             cliVersion: input.cliVersion,
@@ -361,11 +408,12 @@ export async function getUsageInfoForIdentity(input, opts) {
     // it. A stale-or-absent snapshot is handled downstream by the router's own
     // freshness guard (`isUsageVerified` in rotate.ts), which routes around a
     // number it can't confirm rather than trusting an old one — so returning a
-    // stale snapshot here is safe, and an absent one reports `'stale'`.
+    // stale snapshot here is safe, and an absent one reports
+    // {@link USAGE_NOT_COLLECTED_MARKER}.
     if (readOnly) {
         if (cached)
             return { snapshot: cached, error: null };
-        return { snapshot: null, error: 'stale' };
+        return { snapshot: null, error: USAGE_NOT_COLLECTED_MARKER };
     }
     // Explicit refresh: block on the shared device collector.
     return fetchLiveUsageDeduped(input, usageKey, cached, opts?.fileOnly === true);
@@ -460,15 +508,28 @@ function formatUsageErrorKindLabel(kind, detail) {
     switch (kind) {
         case 'no-credential':
             return 'sign in / provision token';
+        // Both of these are permanent for the account as configured, and both used
+        // to render as the generic bucket — which reads as a transient failure and
+        // sends operators back to `claude setup-token` for a remedy that cannot
+        // work (#2987). Name the state instead.
+        case 'no-usage-credential':
+            return USAGE_NO_USAGE_CREDENTIAL_MARKER;
+        case 'headless-scope':
+            return USAGE_HEADLESS_SCOPE_MARKER;
         case 'expired-credential':
+            // Kimi refreshes its own credential on a normal launch; the recovery hint
+            // is embedded in the error string so the label matches the exact action.
+            if (detail?.includes('run Kimi once'))
+                return 'run Kimi once';
             return 're-auth for usage';
+        case 'not-collected':
+            return 'usage pending';
         case 'rate-limited': {
             const retryHint = detail?.match(/not retrying for (.+)\.$/)?.[1] ?? null;
             return retryHint ? `rate-limited (retry ~${retryHint})` : 'rate-limited';
         }
         case 'rejected':
         case 'unreachable':
-        case 'headless-scope':
         case null:
         case undefined:
         default:
@@ -766,7 +827,11 @@ async function getClaudeUsageInfo(options) {
             fileOnly: options?.fileOnly === true,
         });
         if (!oauth?.accessToken) {
-            return { snapshot: null, error: usageNoCredentialError('Claude') };
+            // NOT the shared no-credential message: "sign in" is not a remedy here.
+            // The account this reads for is usually signed in already — the reader is
+            // forbidden from touching that login (RUSH-1822) — so the shared wording
+            // asked the operator to redo the one thing they had already done (#2987).
+            return { snapshot: null, error: usageNoClaudeUsageCredentialError() };
         }
         const requestedOrgId = normalizeString(options?.organizationId);
         const liveOrgId = normalizeString(oauth.organizationUuid);
@@ -887,7 +952,7 @@ async function getKimiUsageInfo(options) {
         }
         const expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
         if (expiresAt !== null && Date.now() / 1000 >= expiresAt) {
-            return { snapshot: null, error: usageExpiredCredentialError('Kimi') };
+            return { snapshot: null, error: usageExpiredKimiCredentialError() };
         }
         // Honour a live Retry-After rather than re-arming the penalty (see
         // usage-backoff.ts). No request at all while the window is open.

package/dist/lib/agent-spec/agents.d.ts

@@ -376,8 +376,11 @@ export declare function resolveOpenCodeAccountId(base: string): string | undefin
  * this file is not authoritative, and probing the Keychain would raise an
  * authorization sheet per installed version on every `agents run` — the reason
  * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
- * only store, so a token-less file is proof of signed-out. `platform` is a
- * parameter so both branches are testable on any host.
+ * only store, so a missing or token-less file is proof of signed-out — unless a
+ * Linux setup-token (`.claude/.oauth_token`) is present, which the shim exports
+ * as `CLAUDE_CODE_OAUTH_TOKEN` and can authenticate the run without
+ * `.credentials.json`. `platform` is a parameter so both branches are testable
+ * on any host.
  *
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */

package/dist/lib/agent-spec/agents.js

@@ -1897,14 +1897,29 @@ function museAuthEmail(value, depth = 0) {
  * this file is not authoritative, and probing the Keychain would raise an
  * authorization sheet per installed version on every `agents run` — the reason
  * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
- * only store, so a token-less file is proof of signed-out. `platform` is a
- * parameter so both branches are testable on any host.
+ * only store, so a missing or token-less file is proof of signed-out — unless a
+ * Linux setup-token (`.claude/.oauth_token`) is present, which the shim exports
+ * as `CLAUDE_CODE_OAUTH_TOKEN` and can authenticate the run without
+ * `.credentials.json`. `platform` is a parameter so both branches are testable
+ * on any host.
  *
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */
 export function isClaudeCredentialFileBlank(base, platform = process.platform) {
     if (platform === 'darwin')
         return false;
+    // A per-version setup-token is a real credential on Linux even when
+    // `.credentials.json` was never written (the shim's `$CLAUDE_CONFIG_DIR/.oauth_token`
+    // fallback). Treat it as signed-in so rotation does not skip a worker that
+    // authenticates from an attached setup-token.
+    try {
+        const token = fs.readFileSync(path.join(base, '.claude', '.oauth_token'), 'utf-8').trim();
+        if (token.length > 0)
+            return false;
+    }
+    catch {
+        /* absent — fall through to the credentials.json floor */
+    }
     try {
         const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
         const oauth = JSON.parse(raw).claudeAiOauth;
@@ -1913,11 +1928,14 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
         return !nonEmpty(oauth.accessToken) && !nonEmpty(oauth.refreshToken);
     }
-    catch {
-        // No file (a Keychain-backed home, or never logged in here) or an
-        // unreadable/corrupt one: not positive evidence of a blank credential, so
-        // leave the existing signal alone rather than declaring a working install
-        // signed out.
+    catch (err) {
+        // Off macOS the file IS the store. Missing it means this home cannot
+        // authenticate (a newly installed default with leftover `.claude.json`
+        // oauthAccount is the PHNX-2685 false-healthy case). A corrupt file is
+        // not positive evidence of a blank credential — leave the existing
+        // signal alone rather than declaring a working install signed out.
+        if (err.code === 'ENOENT')
+            return true;
         return false;
     }
 }

package/dist/lib/analytics/mix-commands.js

@@ -73,7 +73,10 @@ export function registerMixCommands(parent) {
         .option('--days <n>', 'Days of history to include', '7')
         .option('--json', 'Emit JSON instead of tables')
         .action(function summary() {
-        const o = this.opts();
+        // optsWithGlobals(): --json collides by name with the `insights` parent, so
+        // commander binds it to the parent and this.opts() never sees it. Merging
+        // ancestor opts is what the per-recipe leaves below already do.
+        const o = this.optsWithGlobals();
         renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
     });
     setHelpSections(mix, {
@@ -104,7 +107,8 @@ export function registerMixCommands(parent) {
     parent.command('recipes')
         .description('List baked mix-recipe ids')
         .option('--json', 'Emit JSON')
-        .action((o) => {
+        .action(function recipes() {
+        const o = this.optsWithGlobals();
         const list = listRecipes();
         if (o.json) {
             console.log(JSON.stringify(list, null, 2));
@@ -122,7 +126,8 @@ export function registerMixCommands(parent) {
         .option('--days <n>', 'Days of history', '7')
         .option('--limit <n>', 'Max rows', '40')
         .option('--json', 'Emit JSON')
-        .action((o) => {
+        .action(function query() {
+        const o = this.optsWithGlobals();
         const win = analyticsWindow(parseMixDays(o.days));
         const kind = o.kind && USAGE_KINDS.includes(o.kind)
             ? o.kind
@@ -165,8 +170,9 @@ export function registerMixCommands(parent) {
             .option('--days <n>', 'Days of history', '7')
             .option('--json', 'Emit JSON')
             .action(function recipeAction() {
-            const parentOpts = this.parent?.opts?.();
-            const o = { ...parentOpts, ...this.opts() };
+            // optsWithGlobals() merges the `insights` parent opts, so the name-colliding
+            // --json/--since reach this leaf (see the sibling commands above).
+            const o = this.optsWithGlobals();
             const win = analyticsWindow(parseMixDays(o.days));
             const section = runRecipe(id, win);
             if (o.json) {
@@ -187,7 +193,7 @@ export function registerMixCommands(parent) {
         .option('--days <n>', 'Days of history to include', '7')
         .option('--json', 'Emit JSON instead of tables')
         .action(function summary() {
-        const o = this.opts();
+        const o = this.optsWithGlobals();
         renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
     });
     setHelpSections(trends, {

package/dist/lib/auth-mint.d.ts

@@ -0,0 +1,150 @@
+/**
+ * First-class setup-token mint + seed (PHNX-2364).
+ *
+ * Closes the mint-auth manual recipe: drive `claude setup-token` through the
+ * same injectable PTY driver `agents fleet login` uses, capture a well-formed
+ * `sk-ant-oat01-…` token (the #1767 ANSI-banner guard), and seed BOTH:
+ *
+ *   1. a named provider account (`agents accounts add` shape, policy never)
+ *   2. the reserved FILE-BASED `auth` bundle keyed per-account email, which
+ *      usage/probe reads (`resolveClaudeSetupToken`)
+ *
+ * Native rotating OAuth is never copied. Only this non-rotating class is
+ * stored and optionally synced. Interactive mint is Claude-only; every other
+ * harness fails loud with the command that actually provisions it.
+ */
+import type { AgentId } from './types.js';
+import { type CredentialAccount } from './account-registry.js';
+import { type DriveOptions, type PtyDriver } from './fleet/remote-login.js';
+/** Well-formed Claude setup-token as it appears inside a TTY blob. */
+export declare const CLAUDE_SETUP_TOKEN_CAPTURE_RE: RegExp;
+export interface MintFlow {
+    harness: AgentId;
+    provider: string;
+    auth: 'setup-token';
+    /** Interactive mint argv after HOME=… <bin>. Null when stdin-seed only. */
+    mintArgs: string[] | null;
+    verificationUrlRegex: RegExp;
+    tokenCapture: RegExp;
+}
+/**
+ * Harnesses that expose an interactive setup-token mint. Native device-code
+ * login (codex/droid/kimi/grok) stays on `agents fleet login`; API keys stay
+ * on `agents accounts add`. Adding a harness here without a real mint command
+ * is a lying table — do not.
+ */
+export declare const MINT_FLOWS: Record<string, MintFlow>;
+export declare function listMintableHarnesses(): AgentId[];
+export declare function getMintFlow(harnessRaw: string): MintFlow;
+export declare function unmintableMessage(harness: string): string;
+/** Strip CSI / Fe ANSI so a #1767 TTY blob can be scanned for a real token. */
+export declare function stripAnsi(text: string): string;
+/**
+ * Pull a single well-formed Claude setup-token out of a (possibly ANSI-wrapped)
+ * screen. Returns null when none is present. Two distinct tokens fail loud —
+ * guessing which one to seed is how a banner fragment becomes an auth header.
+ */
+export declare function extractClaudeSetupToken(screen: string): string | null;
+/** First https URL on the screen, trailing punctuation stripped. */
+export declare function extractMintUrl(screen: string, flow: MintFlow): string | undefined;
+export declare function isEmail(value: string): boolean;
+/** Account-name slug of an email (`ada@example.com` → `ada-at-example.com`). */
+export declare function accountNameFromEmail(email: string): string;
+export declare function assertValidSetupToken(token: string): string;
+export interface ResolveMintIdentityInput {
+    account?: string;
+    email?: string;
+    home?: string;
+}
+export interface ResolvedMintIdentity {
+    accountName: string;
+    email: string;
+}
+/**
+ * Resolve the named account + the email that keys the reserved `auth` bundle.
+ * `--account` that looks like an email is the email; a name needs `--email` or
+ * a locally signed-in `.claude.json`. Missing email fails loud — we must not
+ * fall back to a bare shared key (that is the multi-account mix-up).
+ */
+export declare function resolveMintIdentity(input: ResolveMintIdentityInput): ResolvedMintIdentity;
+/**
+ * Write (or rotate) the reserved FILE-BASED `auth` bundle's per-account key.
+ * Usage/probe ignores a keychain- or vault-backed bundle of this name, so a
+ * wrong backend fails loud instead of looking like a successful mint.
+ */
+export declare function seedReservedAuthToken(email: string, token: string): {
+    key: string;
+};
+/**
+ * Create or rotate the named provider account that `agents run --account` and
+ * `agents accounts sync` consume. Existing account of a different kind fails
+ * loud rather than silently overwriting an API key with a setup-token.
+ */
+export declare function seedNamedAccount(name: string, token: string, flow: MintFlow): CredentialAccount;
+export interface MintDriveHooks {
+    driver?: PtyDriver;
+    openUrl?: (url: string) => Promise<void>;
+    /** Asked once the authorize URL is on screen, when `--code` was not given. */
+    readCode?: () => Promise<string | undefined>;
+    drive?: DriveOptions;
+}
+export interface DriveMintResult {
+    token: string;
+    url?: string;
+    sessionId: string;
+}
+export interface DriveSetupTokenMintOpts extends MintDriveHooks {
+    code?: string;
+    /** Suppress stdout progress so `--json` callers get a parseable blob. */
+    json?: boolean;
+}
+/**
+ * Drive `claude setup-token` in a PTY: scrape the authorize URL, open it,
+ * optionally paste `--code`, then capture the token with the #1767 guard.
+ * Tears the session down on the way out (success, timeout, or throw).
+ */
+export declare function driveSetupTokenMint(command: string, flow: MintFlow, opts?: DriveSetupTokenMintOpts): Promise<DriveMintResult>;
+export declare function buildMintCommand(flow: MintFlow, bin: string, home: string): string;
+export declare function resolveMintInstallation(harness: AgentId): {
+    version: string;
+    bin: string;
+    home: string;
+};
+export interface MintAndSeedInput {
+    harness: string;
+    account?: string;
+    email?: string;
+    token?: string;
+    code?: string;
+    open?: boolean;
+    fleet?: boolean;
+    devices?: string[];
+    /** Suppress progress prints so `--json` stdout stays machine-parseable. */
+    json?: boolean;
+    hooks?: MintDriveHooks;
+}
+export interface FleetSyncRow {
+    device: string;
+    ok: boolean;
+    message: string;
+}
+export interface MintAndSeedResult {
+    harness: AgentId;
+    account: string;
+    email: string;
+    authBundleKey: string;
+    rotated: boolean;
+    fleet: FleetSyncRow[];
+}
+/**
+ * End-to-end mint: resolve identity, obtain a token (stdin or PTY drive),
+ * seed the named account + reserved auth bundle, optionally sync the fleet.
+ * Never returns or logs the token.
+ */
+export declare function mintAndSeed(input: MintAndSeedInput): Promise<MintAndSeedResult>;
+export declare function resolveSyncTargets(fleet: boolean, devices: string[]): Promise<string[]>;
+/** True when a Claude setup-token is already seeded on this box (setup status). */
+export declare function hasMintedSetupToken(): {
+    ready: boolean;
+    detail: string;
+};