@phnx-labs/agents-cli 1.22.8 → 1.22.9

package/dist/lib/usage-refresh.js

@@ -1,49 +1,74 @@
 /**
- * Daemon-owned adaptive usage refresher.
+ * Daemon-owned usage refresher (per host).
  *
  * The routing hot path (`agents run` → collectRunCandidates) reads usage
  * CACHE-ONLY (`getUsageInfoForIdentity` `readOnly`, RUSH-2061) and never blocks
  * on a provider fetch. Something still has to keep that cache fresh — this
- * module is that something, running inside the daemon.
+ * module is that something, running inside the daemon on **each machine**.
  *
- * Design (per account, this host is the SOLE writer — the refresher only ever
- * touches accounts whose credentials live locally, so no cross-host
- * coordination and no shared-token contention):
+ * Design:
  *
- *  - **Adaptive cadence from burn rate.** Each refresh stores the session
- *    window's `usedPercent` + `capturedAt`. The next refresh is scheduled from
- *    `deriveUsageHeadroom`'s projected `minutesToLimit`: an account racing
- *    toward its cap is polled more often (down to 90s), an idle one rarely (up
- *    to 15min). `computeNextRefreshDelayMs` is the pure clamp.
- *  - **Hard hourly cap.** Regardless of cadence, at most `HOURLY_CALL_CAP` live
- *    fetches per account per rolling hour, so a fast burn can't turn the 90s
- *    floor into a hammering loop.
- *  - **Respects the existing 429 backoff.** A provider under
- *    `usageRateLimitedUntil` is skipped entirely — the whole point of the
- *    backoff is to stop poking an endpoint that just said no.
+ *  - **Per-host sole writer.** Only accounts whose credentials live on THIS
+ *    box are listed; no fleet-wide usage sync.
+ *  - **Fixed 5-minute cadence** (`REFRESH_INTERVAL_MS`). Enough to keep
+ *    balanced/`agents view` off multi-hour stale data without thrashing
+ *    provider APIs when the user runs agents frequently. The delay helpers
+ *    still accept a burn projection for tests/future tuning, but the default
+ *    floor and ceiling are both 5 minutes.
+ *  - **Hard hourly cap** (`HOURLY_CALL_CAP`) so a stuck "due" loop cannot
+ *    hammer an endpoint past ~12 calls/account/hour.
+ *  - **429 backoff.** A provider under `usageRateLimitedUntil` is skipped
+ *    entirely — no live fetch, no Touch ID, no re-armed penalty.
+ *  - **File-only credentials on the daemon path.** Refresh never opens the
+ *    ACL-bound macOS keychain item (Touch ID storm). It uses the no-ACL
+ *    access-token cache / setup-token / `.credentials.json` only
+ *    (`fileOnly: true` on `getUsageInfo`).
+ *  - **Concurrency-safe cache writes.** Usage + headroom files are updated
+ *    under `withFileLock` + atomic rename so a concurrent `agents view`
+ *    background refresh cannot tear or drop another account's row.
  *
- * It also publishes the projected headroom (`minutesToLimit` + status) to a
- * small cache keyed by usage key, so the routing hot path can deprioritize an
- * account projected to cap without recomputing a burn rate it has no prior
- * sample for. `fleet-cache.ts` is the sync reader.
+ * Scenarios (what this path must survive):
+ *
+ *  1. **Daemon tick overlaps a slow tick** — overlap guard in daemon.ts;
+ *     second tick is a no-op.
+ *  2. **`agents view` writes cache while daemon refreshes** — file lock
+ *     serializes read-modify-write; no lost updates.
+ *  3. **macOS keychain ACL / Touch ID** — fileOnly refresh never calls
+ *     `security find-generic-password` on Claude's ACL item.
+ *  4. **Provider 429** — whole provider skipped until Retry-After; cache
+ *     freezes (visible as aged `capturedAt`) rather than hammering.
+ *  5. **Expired access token (no refresh)** — usage path never rotates
+ *     single-use refresh tokens; counts as `failed`, reschedules 5m later.
+ *  6. **No file credential on this host** — account skipped / failed; no
+ *     keychain fallback from the daemon refresher.
+ *  7. **Grok/Codex (network:false)** — not listed by `buildLocalUsageAccounts`;
+ *     their "cache" is local logs, not this HTTP refresher.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { deriveUsageHeadroom, getUsageInfo, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
 import { getAccountInfo } from './agents.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
-/** Floor on the adaptive interval: an account seconds from its cap still isn't
- * polled faster than this. */
-export const REFRESH_MIN_MS = 90 * 1000;
-/** Ceiling on the adaptive interval: an idle account is still re-checked at
- * least this often so a cache never silently rots. */
-export const REFRESH_MAX_MS = 15 * 60 * 1000;
-/** Schedule the next refresh at `minutesToLimit / K` — poll well before the cap,
- * not exactly at it. */
+/**
+ * Default schedule between successful (or attempted) live usage fetches for one
+ * account. Floor and ceiling of the delay helper are pinned to this so the
+ * daemon does not poll faster than 5 minutes even under high burn, and does not
+ * let an idle account rot longer than 5 minutes between attempts.
+ */
+export const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
+export const REFRESH_MIN_MS = REFRESH_INTERVAL_MS;
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
+export const REFRESH_MAX_MS = REFRESH_INTERVAL_MS;
+/** Burn-rate divisor retained for the pure delay helper / tests; with min=max
+ * the divisor does not change the scheduled interval. */
 export const REFRESH_BURN_DIVISOR = 4;
-/** At most this many live fetches per account per rolling hour. */
-export const HOURLY_CALL_CAP = 6;
+/** At most this many live fetches per account per rolling hour (5m cadence ⇒ 12). */
+export const HOURLY_CALL_CAP = 12;
+/** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
+export const USAGE_REFRESH_TICK_MS = 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
 /** Test seam for the headroom cache path (see usage.ts `setClaudeUsageCachePathForTest`). */
 let headroomCachePathOverride = null;
@@ -74,27 +99,30 @@ export function readHeadroomEntry(usageKey) {
 /** Merge entries into the cache (best-effort; preserves other accounts' rows). */
 export function writeHeadroomEntries(entries) {
     try {
-        const dir = getCacheDir();
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        const merged = {
-            version: 1,
-            entries: { ...readHeadroomCache(), ...entries },
-        };
-        fs.writeFileSync(headroomCachePath(), JSON.stringify(merged, null, 2));
+        const cachePath = headroomCachePath();
+        ensureLockTarget(cachePath, JSON.stringify({ version: 1, entries: {} }, null, 2));
+        withFileLock(cachePath, () => {
+            // Re-read under the lock so a concurrent tick/view cannot drop rows.
+            const merged = {
+                version: 1,
+                entries: { ...readHeadroomCache(), ...entries },
+            };
+            atomicWriteFileSync(cachePath, JSON.stringify(merged, null, 2));
+        });
     }
     catch {
         // best-effort; a failed write just means the router sees no projection
     }
 }
 /**
- * The adaptive interval until the next refresh, clamped to [MIN, MAX]. A
- * shorter `minutesToLimit` (closer to the cap) polls sooner; `null` (unknown /
- * idle / not burning) waits the full ceiling.
+ * Interval until the next refresh attempt, clamped to [minMs, maxMs].
+ * Defaults pin both ends to {@link REFRESH_INTERVAL_MS} (5 minutes) so the
+ * live daemon path is a fixed schedule. Tests may pass a wider range to
+ * exercise burn-aware scheduling without changing production cadence.
  */
 export function computeNextRefreshDelayMs(minutesToLimit, opts = {}) {
-    const minMs = opts.minMs ?? REFRESH_MIN_MS;
-    const maxMs = opts.maxMs ?? REFRESH_MAX_MS;
+    const minMs = opts.minMs ?? REFRESH_INTERVAL_MS;
+    const maxMs = opts.maxMs ?? REFRESH_INTERVAL_MS;
     const divisor = opts.divisor ?? REFRESH_BURN_DIVISOR;
     if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
         return maxMs;
@@ -169,10 +197,14 @@ export async function buildLocalUsageAccounts() {
             accounts.push({
                 usageKey,
                 agentId,
+                // fileOnly: never open the ACL-bound keychain item from the daemon —
+                // that path is the Touch ID storm. Usage reads setup-token /
+                // no-ACL cache / .credentials.json only (see loadClaudeOauth).
                 fetch: () => getUsageInfo(agentId, {
                     home: fetchInput.home,
                     cliVersion: fetchInput.cliVersion,
                     organizationId: fetchInput.organizationId,
+                    fileOnly: true,
                 }),
             });
         }

package/dist/lib/usage.d.ts

@@ -86,6 +86,13 @@ interface UsageOptions {
     home?: string;
     cliVersion?: string | null;
     organizationId?: string | null;
+    /**
+     * When true, never open the ACL-bound OS keychain item (macOS Touch ID).
+     * Daemon usage refresh sets this so a background tick cannot pop biometrics.
+     * Credentials come from the no-ACL access-token cache, a file-based
+     * setup-token, or `<home>/.claude/.credentials.json` only.
+     */
+    fileOnly?: boolean;
 }
 /** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
@@ -462,9 +469,14 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * `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.
+ *
+ * `opts.fileOnly` (implies access-token-only consumers) skips the ACL keychain
+ * read entirely — setup-token, no-ACL cache, and `.credentials.json` only. Used
+ * by the daemon usage refresher so a background tick can never pop Touch ID.
  */
 export declare function loadClaudeOauth(home?: string, opts?: {
     accessTokenCache?: boolean;
+    fileOnly?: boolean;
 }): Promise<ClaudeOauthCredentials | null>;
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.

package/dist/lib/usage.js

@@ -24,6 +24,7 @@ import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, } from './usage-backoff.js';
 import { getCacheDir } from './state.js';
 import { mapBounded } from './concurrency.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -654,7 +655,12 @@ async function getClaudeUsageInfo(options) {
     try {
         // 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 });
+        // Daemon refresh also sets fileOnly so we never fall through to the ACL
+        // keychain item (that path is the Touch ID prompt).
+        const oauth = await loadClaudeOauth(options?.home, {
+            accessTokenCache: true,
+            fileOnly: options?.fileOnly === true,
+        });
         if (!oauth?.accessToken) {
             return { snapshot: null, error: usageNoCredentialError('Claude') };
         }
@@ -1333,6 +1339,10 @@ function deleteCachedClaudeOauth(service) {
  * `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.
+ *
+ * `opts.fileOnly` (implies access-token-only consumers) skips the ACL keychain
+ * read entirely — setup-token, no-ACL cache, and `.credentials.json` only. Used
+ * by the daemon usage refresher so a background tick can never pop Touch ID.
  */
 export async function loadClaudeOauth(home, opts) {
     // Read-only usage/probe callers (accessTokenCache) authenticate with a
@@ -1359,7 +1369,11 @@ export async function loadClaudeOauth(home, opts) {
     // 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()) {
+    //
+    // fileOnly: daemon refresh must never open the ACL-bound item (Touch ID).
+    // It may still read the no-ACL cache item (set-no-acl — prompt-free).
+    if (!opts?.fileOnly
+        && (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
@@ -1386,6 +1400,13 @@ export async function loadClaudeOauth(home, opts) {
                 deleteCachedClaudeOauth(service);
         }
     }
+    else if (opts?.fileOnly === true && opts?.accessTokenCache === true && claudeOauthCacheActive()) {
+        // fileOnly + accessTokenCache: still allow the no-ACL cache (never Touch ID).
+        const service = getClaudeKeychainService(home);
+        const cached = readCachedClaudeOauth(service);
+        if (cached)
+            return cached;
+    }
     const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
     try {
         if (fs.existsSync(credsPath)) {
@@ -1487,9 +1508,19 @@ export function readClaudeUsageCache(usageKey, cachePath = getClaudeUsageCachePa
 }
 /** Write a usage snapshot to the on-disk cache. */
 export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
-    const cache = readClaudeUsageCacheFile(cachePath);
-    cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
-    writeClaudeUsageCacheFile(cache, cachePath);
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            // Re-read under the lock so a concurrent daemon tick / agents view
+            // refresh cannot drop another account's row (lost update).
+            const cache = readClaudeUsageCacheFile(cachePath);
+            cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
 }
 /** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
@@ -1508,7 +1539,7 @@ function readClaudeUsageCacheFile(cachePath) {
 function writeClaudeUsageCacheFile(cache, cachePath) {
     try {
         fs.mkdirSync(path.dirname(cachePath), { recursive: true });
-        fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
     }
     catch {
         /* best-effort cache write */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.8",
+  "version": "1.22.9",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",