@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/teams/agents.d.ts

@@ -1,3 +1,4 @@
+import { captureProcessStartTime } from '../platform/index.js';
 import { AgentType } from './parsers.js';
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
@@ -26,18 +27,25 @@ export type { AgentType } from './parsers.js';
  */
 export declare function buildSentinelCommand(cmd: string[], exitCodePath: string): string;
 /**
- * Capture a stable identifier for a process at the moment it was started.
- * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
- * still occupies the PID we observed at spawn time. A bare kill(pid, 0)
- * probe cannot tell whether the OS has recycled the slot to an unrelated
- * process — combined with detached spawns and unref(), that's exactly how
- * `agents teams stop` ends up SIGKILLing random process groups.
+ * Env for a locally-spawned teammate. Freezes ONE actor for the whole spawn
+ * tree: actorEnv(resolveActor()) stamps AGENTS_ACTOR* onto the child env, so the
+ * teammate's inner `agents run` reads it via inheritedActor and short-circuits
+ * computeActor instead of re-resolving — every teammate under one orchestrator
+ * shares the orchestrator's single frozen actor (see actor.ts). Precedence:
+ * process env < actor < the teammate's --env overrides, so an explicit override
+ * still wins. Single source of truth shared by launchProcess() and its test.
+ */
+export declare function buildTeammateSpawnEnv(envOverrides: Record<string, string> | null): NodeJS.ProcessEnv;
+/**
+ * Re-exported from `platform/process.ts`, which owns the one implementation.
  *
- * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
- * Returns null on any error so callers can skip the guard rather than crash.
+ * This module used to carry its own near-identical copy, and that copy had no
+ * Windows branch — it fell through to `ps`, which does not exist there, so
+ * `captureProcessStartTime` always returned null and the pid-reuse guard at
+ * `stop()` was silently inert on Windows. That is exactly how `agents teams stop`
+ * ends up SIGKILLing an unrelated process group once the OS recycles a pid.
  */
-export declare function captureProcessStartTime(pid: number): string | null;
+export { captureProcessStartTime };
 /**
  * Reasoning-intensity knob. Passed through to `agents run --effort`, which
  * translates it into per-agent reasoning flags (claude --effort, codex
@@ -130,6 +138,7 @@ export declare class AgentProcess {
     startedAt: Date;
     completedAt: Date | null;
     parentSessionId: string | null;
+    actor: string | null;
     cloudSessionId: string | null;
     cloudProvider: string | null;
     prUrl: string | null;

package/dist/lib/teams/agents.js

@@ -7,7 +7,7 @@
  * dependency scheduling via --after, per-teammate model/effort overrides, and
  * multiple permission modes (plan, edit, full).
  */
-import { spawn, execSync, execFileSync } from 'child_process';
+import { spawn, execSync } from 'child_process';
 import { getAgentsInvocation } from '../daemon.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
@@ -15,7 +15,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
 import { resolveAgentsDir } from './persistence.js';
-import { findExecutable } from '../platform/index.js';
+import { findExecutable, captureProcessStartTime } from '../platform/index.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
@@ -23,6 +23,7 @@ import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS, getAccountInfo } from '../agents.js';
 import { resolveVersion, isVersionInstalled, verifyInstalledBinaryLaunches } from '../versions.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
+import { resolveActor, actorEnv } from '../actor.js';
 import { recordRunName } from '../session/run-names.js';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
@@ -169,42 +170,31 @@ export function buildSentinelCommand(cmd, exitCodePath) {
     return `${cmd.map(shSingleQuote).join(' ')}; echo $? > ${shSingleQuote(exitCodePath)}`;
 }
 /**
- * Capture a stable identifier for a process at the moment it was started.
- * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
- * still occupies the PID we observed at spawn time. A bare kill(pid, 0)
- * probe cannot tell whether the OS has recycled the slot to an unrelated
- * process — combined with detached spawns and unref(), that's exactly how
- * `agents teams stop` ends up SIGKILLing random process groups.
- *
- * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
- * Returns null on any error so callers can skip the guard rather than crash.
+ * Env for a locally-spawned teammate. Freezes ONE actor for the whole spawn
+ * tree: actorEnv(resolveActor()) stamps AGENTS_ACTOR* onto the child env, so the
+ * teammate's inner `agents run` reads it via inheritedActor and short-circuits
+ * computeActor instead of re-resolving — every teammate under one orchestrator
+ * shares the orchestrator's single frozen actor (see actor.ts). Precedence:
+ * process env < actor < the teammate's --env overrides, so an explicit override
+ * still wins. Single source of truth shared by launchProcess() and its test.
  */
-export function captureProcessStartTime(pid) {
-    if (!pid || pid <= 0)
-        return null;
-    try {
-        if (process.platform === 'linux') {
-            const stat = fsSync.readFileSync(`/proc/${pid}/stat`, 'utf-8');
-            const lastParen = stat.lastIndexOf(')');
-            if (lastParen < 0)
-                return null;
-            const tail = stat.slice(lastParen + 2);
-            const fields = tail.split(' ');
-            // After comm we are at field 3; starttime is field 22, so index 19 here.
-            return fields[19] || null;
-        }
-        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        const trimmed = out.trim();
-        return trimmed.length > 0 ? trimmed : null;
-    }
-    catch {
-        return null;
-    }
+export function buildTeammateSpawnEnv(envOverrides) {
+    return {
+        ...sanitizeProcessEnv(process.env),
+        ...actorEnv(resolveActor()),
+        ...(envOverrides ?? {}),
+    };
 }
+/**
+ * Re-exported from `platform/process.ts`, which owns the one implementation.
+ *
+ * This module used to carry its own near-identical copy, and that copy had no
+ * Windows branch — it fell through to `ps`, which does not exist there, so
+ * `captureProcessStartTime` always returned null and the pid-reuse guard at
+ * `stop()` was silently inert on Windows. That is exactly how `agents teams stop`
+ * ends up SIGKILLing an unrelated process group once the OS recycles a pid.
+ */
+export { captureProcessStartTime };
 /** Agent types the team runner supports. */
 const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity', 'kimi', 'droid'];
 // Suffix appended to all prompts to ensure agents provide a summary
@@ -479,6 +469,12 @@ export class AgentProcess {
     startedAt = new Date();
     completedAt = null;
     parentSessionId = null;
+    // Frozen actor (resolveActor().id) this teammate runs under. Stamped onto the
+    // local spawn env via actorEnv (buildTeammateSpawnEnv) so the teammate's inner
+    // `agents run` inherits one actor for the whole tree instead of re-resolving,
+    // and persisted so the record shows who ran it. Set from the resolved actor at
+    // construction; loadFromDisk restores the persisted value.
+    actor = null;
     cloudSessionId = null;
     cloudProvider = null;
     prUrl = null;
@@ -564,6 +560,7 @@ export class AgentProcess {
         this.completedAt = completedAt;
         this.baseDir = baseDir;
         this.parentSessionId = parentSessionId;
+        this.actor = resolveActor().id;
         this.cloudSessionId = cloudSessionId;
         this.cloudProvider = cloudProvider;
         this.prUrl = prUrl;
@@ -628,6 +625,7 @@ export class AgentProcess {
             duration: this.duration(),
             mode: this.mode,
             parent_session_id: this.parentSessionId,
+            actor: this.actor,
             workspace_dir: this.workspaceDir,
             cloud_session_id: this.cloudSessionId,
             cloud_provider: this.cloudProvider,
@@ -884,6 +882,7 @@ export class AgentProcess {
             started_at: this.startedAt.toISOString(),
             completed_at: this.completedAt?.toISOString() || null,
             parent_session_id: this.parentSessionId,
+            actor: this.actor,
             cloud_session_id: this.cloudSessionId,
             cloud_provider: this.cloudProvider,
             pr_url: this.prUrl,
@@ -948,6 +947,10 @@ export class AgentProcess {
                 ? meta.task_type
                 : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null, meta.profile_name || null);
             agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
+            // The persisted actor is the truth for a reload; the constructor set it to
+            // THIS process's resolved actor, which is wrong for a teammate someone else
+            // ran. Legacy teammates predating the field carry no actor -> null.
+            agent.actor = meta.actor ?? null;
             // Distributed-team fields: set post-construction (like startTime) so the
             // constructor signature stays fixed. Null on every pre-existing teammate.
             agent.hostName = meta.host_name || null;
@@ -1556,9 +1559,7 @@ export class AgentManager {
                 stdio: ['ignore', stdoutFd, stdoutFd],
                 cwd: agent.cwd || undefined,
                 detached: true,
-                env: agent.envOverrides
-                    ? { ...sanitizeProcessEnv(process.env), ...agent.envOverrides }
-                    : sanitizeProcessEnv(process.env),
+                env: buildTeammateSpawnEnv(agent.envOverrides),
             });
             await new Promise((resolve, reject) => {
                 childProcess.once('spawn', resolve);

package/dist/lib/types.d.ts

@@ -689,6 +689,26 @@ export interface BrandConfig {
     /** False to keep the config but stop minting/using the brand. */
     enabled: boolean;
 }
+/**
+ * An actor -- a responsible entity behind a run (a human today, a top-level
+ * agent later). Keyed in the `actors:` map by a short slug. Every field is
+ * optional enrichment over what `tailscale whois` already resolves: pin a
+ * preferred git email, add a github handle, or override the display name.
+ * `login` is the tailnet login-name to match against (defaults to the map key).
+ * See lib/actor.ts.
+ */
+export interface ActorConfig {
+    /** 'human' (default) or 'agent'. Only humans get personal git credit. */
+    kind?: 'human' | 'agent';
+    /** Display + git author name. Overrides the tailnet DisplayName. */
+    name?: string;
+    /** Git author email. Overrides the tailnet login email. */
+    email?: string;
+    /** GitHub handle, for PR attribution. */
+    github?: string;
+    /** Tailnet login-name this entry matches. Defaults to the map key. */
+    login?: string;
+}
 /** Top-level structure of ~/.agents/.system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
@@ -765,8 +785,23 @@ export interface Meta {
      */
     brands?: Record<string, BrandConfig>;
     /**
-     * Keys like `skill.hermes` — registries seeded from SEEDED_REGISTRIES exactly
-     * once. Tracked so a user `registry remove` won't silently re-seed.
+     * Actors keyed by slug -- who is behind a run. Enriches or overrides the
+     * identity `tailscale whois` resolves (git email, github handle, display
+     * name, human vs agent). See lib/actor.ts.
+     */
+    actors?: Record<string, ActorConfig>;
+    /**
+     * Removal tombstones for SEEDED_REGISTRIES presets, keyed like `skill.hermes`.
+     *
+     * Seeded presets are resolved in memory by `getRegistries` (see
+     * `offeredSeeds`) rather than written into agents.yaml — persisting them from
+     * the read path dirtied this git-tracked file and deadlocked
+     * `agents repo pull` (RUSH-1925). A key listed here means the user ran
+     * `registry remove` on that preset, so it is no longer offered.
+     *
+     * Entries written by the pre-RUSH-1925 seeding also appear here; those files
+     * carry the registry in their own `registries:` block too, which takes
+     * precedence, so the preset stays exactly as configured.
      */
     seededPresets?: string[];
     /**
@@ -831,6 +866,16 @@ export interface Meta {
         };
         transports?: Record<string, string>;
     };
+    /**
+     * Routines daemon settings. `projects` is the allowlist of project roots
+     * whose `.agents/routines/*.yml` may be synced into `~/.agents/routines/`
+     * and fired by the daemon — never auto-discovered from a cloned public
+     * repo without an explicit opt-in (`agents routines enable-project`).
+     * Paths are stored absolute (or home-relative `~/…`).
+     */
+    routines?: {
+        projects?: string[];
+    };
 }
 /** Persisted agent-host entry in agents.yaml (overlay or inline). */
 export interface HostEntry {

package/dist/lib/usage.d.ts

@@ -151,6 +151,22 @@ export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot |
 export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
+/**
+ * The access token to use for a READ-ONLY Claude usage fetch, or null when the
+ * stored token is within the refresh leeway.
+ *
+ * Returns null instead of refreshing on purpose. Claude's refresh token is
+ * single-use and rotates server-side on every refresh; with one account signed
+ * into several machines, refreshing here would stampede that one token and
+ * silently invalidate every other holder — the RUSH-1822 failure, except in the
+ * usage path (fired in the background by the SWR cache and by `agents run`'s
+ * default "balanced" rotation on every unpinned run) rather than the health
+ * probe. So a usage read must never rotate: a near-expiry token yields "no usage
+ * right now" instead of a fleet-wide logout. Mirrors {@link probeClaudeStatus};
+ * the single legitimate refresh belongs to the actual claude run, never a read.
+ * Pure — unit-tested.
+ */
+export declare function claudeUsageAccessTokenNoRefresh(oauth: Pick<ClaudeOauthCredentials, 'accessToken' | 'expiresAt'>): string | null;
 /** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
 interface KimiUsageQuota {
     limit?: string | number | null;
@@ -242,8 +258,24 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--host`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
+ *
+ * `opts.accessTokenCache` opts INTO the no-ACL access-token cache (the Touch ID
+ * storm fix, see the cache helpers above). It is OFF by default so every caller
+ * keeps the full ACL-read credential — the cached copy deliberately omits the
+ * refresh token, so callers that refresh (`isClaudeAuthValid` ->
+ * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
+ * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
+ * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
+ */
+export declare function loadClaudeOauth(home?: string, opts?: {
+    accessTokenCache?: boolean;
+}): Promise<ClaudeOauthCredentials | null>;
+/**
+ * Save Claude OAuth credentials to the system keychain/keyring.
+ * Reads the existing payload, merges the new OAuth fields, and writes back.
+ * Exported for regression tests; not part of the public command surface.
  */
-export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
+export declare function saveClaudeOauth(home: string | undefined, credentials: ClaudeOauthCredentials): Promise<boolean>;
 /**
  * Derive the Keychain service name for a Claude home directory.
  * Managed (non-default) homes get a hash suffix for isolation.

package/dist/lib/usage.js

@@ -17,7 +17,7 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import { decodeJwtPayload, decryptDroidAuthPayload } from './agents.js';
 import { walkForFiles } from './fs-walk.js';
-import { getKeychainToken, setKeychainToken, deleteKeychainToken, } from './secrets/index.js';
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden, } from './secrets/index.js';
 import { getCacheDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
@@ -375,10 +375,33 @@ async function getCodexUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/**
+ * The access token to use for a READ-ONLY Claude usage fetch, or null when the
+ * stored token is within the refresh leeway.
+ *
+ * Returns null instead of refreshing on purpose. Claude's refresh token is
+ * single-use and rotates server-side on every refresh; with one account signed
+ * into several machines, refreshing here would stampede that one token and
+ * silently invalidate every other holder — the RUSH-1822 failure, except in the
+ * usage path (fired in the background by the SWR cache and by `agents run`'s
+ * default "balanced" rotation on every unpinned run) rather than the health
+ * probe. So a usage read must never rotate: a near-expiry token yields "no usage
+ * right now" instead of a fleet-wide logout. Mirrors {@link probeClaudeStatus};
+ * the single legitimate refresh belongs to the actual claude run, never a read.
+ * Pure — unit-tested.
+ */
+export function claudeUsageAccessTokenNoRefresh(oauth) {
+    if (claudeAccessTokenNeedsRefresh(oauth.expiresAt ?? null))
+        return null;
+    const token = oauth.accessToken?.trim();
+    return token ? token : null;
+}
 /** Fetch Claude usage via the Anthropic OAuth usage API. */
 async function getClaudeUsageInfo(options) {
     try {
-        const oauth = await loadClaudeOauth(options?.home);
+        // Opt into the no-ACL access-token cache: this is the every-60s watchdog hot
+        // path and usage needs only the access token, so it kills the Touch ID storm.
+        const oauth = await loadClaudeOauth(options?.home, { accessTokenCache: true });
         if (!oauth?.accessToken) {
             return { snapshot: null, error: null };
         }
@@ -387,7 +410,8 @@ async function getClaudeUsageInfo(options) {
         if (!isClaudeUsageOrgMatch(requestedOrgId, liveOrgId)) {
             return { snapshot: null, error: null };
         }
-        const accessToken = await getClaudeAccessToken(oauth, options?.home);
+        // Read-only: never refresh a single-use token just to read usage (RUSH-1822).
+        const accessToken = claudeUsageAccessTokenNoRefresh(oauth);
         if (!accessToken) {
             return { snapshot: null, error: null };
         }
@@ -627,7 +651,10 @@ async function getDroidUsageInfo(options) {
 }
 /** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
 export async function probeClaudeStatus(home, cliVersion) {
-    const oauth = await loadClaudeOauth(home);
+    // Opt into the no-ACL access-token cache: the daemon warms this probe every ~3
+    // min per account and it never refreshes (access token only), so caching is safe
+    // and stops it from adding to the Touch ID storm.
+    const oauth = await loadClaudeOauth(home, { accessTokenCache: true });
     const accessToken = oauth?.accessToken?.trim();
     if (!accessToken)
         return { status: null, token: 'missing' };
@@ -862,6 +889,103 @@ function parseClaudeOauthPayload(raw) {
         return null;
     }
 }
+// ── No-ACL cache for Claude's OAuth token (kills the macOS Touch ID storm) ──
+//
+// The source item `Claude Code-credentials-<hash>` is ACL-bound to Claude Code's
+// own process, so every read agents-cli makes (via `/usr/bin/security`) pops
+// Touch ID. The Factory watchdog polls `agents view --json` every 60s per agent,
+// and each poll that crosses the 2-minute usage cache fires a background refresh
+// -> loadClaudeOauth -> keychain read -> a biometric prompt. With many agents and
+// accounts that is a prompt every couple of minutes, per account.
+//
+// Fix: after one real (prompting) read, cache the ACCESS token in a device-local
+// NO-ACL keychain item — the same `set-no-acl` mechanism secrets/session-store.ts
+// uses for unlocked bundles, whose reads never prompt — and serve every later read
+// from it until the token's own `expiresAt`. The ACL read then happens at most once
+// per token lifetime (~a few times a day), shared across every agent process.
+//
+// Security posture: only the short-lived access token is cached, never the refresh
+// token, and the entry dies at the token's expiry (capped below). This mirrors the
+// no-ACL posture session-store.ts already accepts for held bundles.
+const CLAUDE_OAUTH_CACHE_PREFIX = 'agents-cli.claude-oauth-cache.';
+/** Hard cap so a token with a distant or absent `expiresAt` can't pin a stale entry. */
+const CLAUDE_OAUTH_CACHE_MAX_TTL_MS = 8 * 60 * 60 * 1000;
+/** The no-ACL cache item name for a Claude keychain service (hashed to stay tidy). */
+function claudeOauthCacheItem(service) {
+    const hash = createHash('sha256').update(service).digest('hex').slice(0, 16);
+    return `${CLAUDE_OAUTH_CACHE_PREFIX}${hash}`;
+}
+/** Whether the no-ACL cache is meaningful: macOS (where the source read prompts) or
+ * whenever a test keychain backend is installed, so the path is exercisable on CI.
+ * Off macOS in production the source read is prompt-free, so there is nothing to cache. */
+function claudeOauthCacheActive() {
+    return process.platform === 'darwin' || isKeychainBackendOverridden();
+}
+/** Read the cached access token (prompt-free). Null on miss, or when the cache entry
+ * or the token itself has expired — in which case the stale entry is dropped. */
+function readCachedClaudeOauth(service) {
+    try {
+        const entry = JSON.parse(getKeychainToken(claudeOauthCacheItem(service)));
+        if (!entry || typeof entry.accessToken !== 'string' || !entry.accessToken)
+            return null;
+        const now = Date.now();
+        const tokenExpired = typeof entry.expiresAt === 'number' && entry.expiresAt > 0 && now >= entry.expiresAt;
+        if (now >= entry.cacheExpiresAt || tokenExpired) {
+            try {
+                deleteKeychainToken(claudeOauthCacheItem(service));
+            }
+            catch {
+                /* best-effort eviction */
+            }
+            return null;
+        }
+        return {
+            accessToken: entry.accessToken,
+            refreshToken: null,
+            expiresAt: entry.expiresAt ?? null,
+            scopes: entry.scopes ?? null,
+            subscriptionType: entry.subscriptionType ?? null,
+            rateLimitTier: entry.rateLimitTier ?? null,
+            organizationUuid: entry.organizationUuid ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Populate the no-ACL cache after a real (prompting) source read. Best-effort — the
+ * cache is an optimization, so any failure just means the next read prompts again. */
+function writeCachedClaudeOauth(service, creds) {
+    if (!creds.accessToken)
+        return;
+    try {
+        const now = Date.now();
+        const cap = now + CLAUDE_OAUTH_CACHE_MAX_TTL_MS;
+        const tokenExp = typeof creds.expiresAt === 'number' && creds.expiresAt > now ? creds.expiresAt : cap;
+        const entry = {
+            accessToken: creds.accessToken,
+            expiresAt: creds.expiresAt ?? null,
+            scopes: creds.scopes ?? null,
+            subscriptionType: creds.subscriptionType ?? null,
+            rateLimitTier: creds.rateLimitTier ?? null,
+            organizationUuid: creds.organizationUuid ?? null,
+            cacheExpiresAt: Math.min(tokenExp, cap),
+        };
+        setKeychainToken(claudeOauthCacheItem(service), JSON.stringify(entry), { noAcl: true });
+    }
+    catch {
+        /* best-effort — cache is an optimization */
+    }
+}
+/** Evict the no-ACL cache so a source rotation or sign-out is reflected immediately. */
+function deleteCachedClaudeOauth(service) {
+    try {
+        deleteKeychainToken(claudeOauthCacheItem(service));
+    }
+    catch {
+        /* best-effort — cache is an optimization */
+    }
+}
 /**
  * Load a version home's Claude OAuth credential from the two stores Claude Code
  * uses, tried in order:
@@ -878,19 +1002,48 @@ function parseClaudeOauthPayload(raw) {
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--host`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
+ *
+ * `opts.accessTokenCache` opts INTO the no-ACL access-token cache (the Touch ID
+ * storm fix, see the cache helpers above). It is OFF by default so every caller
+ * keeps the full ACL-read credential — the cached copy deliberately omits the
+ * refresh token, so callers that refresh (`isClaudeAuthValid` ->
+ * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
+ * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
+ * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
  */
-export async function loadClaudeOauth(home) {
+export async function loadClaudeOauth(home, opts) {
     // The OS keychain/keyring step is macOS/Linux-only. Windows skips straight
     // to the .credentials.json fallback — the Claude CLI has no keychain
-    // integration there and stores its OAuth token in that file too.
-    if (process.platform === 'darwin' || process.platform === 'linux') {
+    // integration there and stores its OAuth token in that file too. An injected
+    // test backend is the exception: it makes the keychain path exercisable
+    // anywhere, so the platform check must yield to it exactly as the inner
+    // claudeOauthCacheActive() gate does — otherwise this whole block is dead on
+    // a Windows runner and the tests below it read an empty home.
+    if (process.platform === 'darwin' || process.platform === 'linux' || isKeychainBackendOverridden()) {
+        const service = getClaudeKeychainService(home);
+        // Serve the no-ACL cache first (opt-in, macOS/test only) so the ACL-gated read
+        // below — the one that pops Touch ID — happens at most once per token lifetime
+        // instead of on every usage refresh. Off unless the caller opts in, because the
+        // cached copy drops the refresh token (see the doc comment above).
+        const cacheActive = opts?.accessTokenCache === true && claudeOauthCacheActive();
+        if (cacheActive) {
+            const cached = readCachedClaudeOauth(service);
+            if (cached)
+                return cached;
+        }
         try {
-            const fromKeychain = parseClaudeOauthPayload(getKeychainToken(getClaudeKeychainService(home)));
-            if (fromKeychain)
+            const fromKeychain = parseClaudeOauthPayload(getKeychainToken(service));
+            if (fromKeychain) {
+                if (cacheActive)
+                    writeCachedClaudeOauth(service, fromKeychain);
                 return fromKeychain;
+            }
         }
         catch {
             // No keychain item, or no reachable keyring (headless Linux) — fall through.
+            // Evict any stale no-ACL cache so a sign-out/deletion isn't masked.
+            if (cacheActive)
+                deleteCachedClaudeOauth(service);
         }
     }
     const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
@@ -907,10 +1060,15 @@ export async function loadClaudeOauth(home) {
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.
  * Reads the existing payload, merges the new OAuth fields, and writes back.
+ * Exported for regression tests; not part of the public command surface.
  */
-async function saveClaudeOauth(home, credentials) {
-    // Windows not yet supported
-    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+export async function saveClaudeOauth(home, credentials) {
+    // Windows not yet supported. An injected test backend is the exception, for
+    // the same reason as the loadClaudeOauth guard above: it makes the keychain
+    // path exercisable anywhere, and without it this returns before the rotated
+    // credential is written OR the no-ACL cache is evicted — so a cached reader
+    // keeps serving the pre-rotation access token.
+    if (process.platform !== 'darwin' && process.platform !== 'linux' && !isKeychainBackendOverridden()) {
         return false;
     }
     try {
@@ -944,6 +1102,8 @@ async function saveClaudeOauth(home, credentials) {
             // Entry might not exist, ignore
         }
         setKeychainToken(service, payloadJson);
+        // A new credential rotation means any cached access token is stale.
+        deleteCachedClaudeOauth(service);
         return true;
     }
     catch {

package/dist/lib/versions.d.ts

@@ -444,8 +444,15 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  * the exact failure this repairs. Agents with a global/native binary (grok,
  * droid) have no such tarball and are returned unchanged.
  */
-export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
-export declare function healBrokenDefaultLaunches(log?: (m: string) => void): Promise<string[]>;
+export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<string | null>;
+export declare function healBrokenDefaultLaunches(log?: (m: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<{
+    repaired: string[];
+    unhealed: string[];
+}>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;