@phnx-labs/agents-cli 1.22.28 → 1.22.30

package/dist/lib/session/parse.js

@@ -1125,6 +1125,40 @@ export function parseAntigravity(dbPath) {
     return events;
 }
 // ---------------------------------------------------------------------------
+// Composite session file paths
+// ---------------------------------------------------------------------------
+/**
+ * Separator between a container file and the id it holds inside a *composite*
+ * session `file_path`. Some harnesses keep every session in ONE file (OpenCode's
+ * single `opencode.db`), so the index stores `<container>#<session-id>` rather
+ * than one path per session — e.g.
+ * `/home/u/.local/share/opencode/opencode.db#ses_02410a2c…`.
+ */
+export const SESSION_FILE_PATH_SEP = '#';
+/**
+ * Split a stored session `file_path` into its on-disk container and the optional
+ * in-container fragment. For a plain per-session file the container is the path
+ * itself and `fragment` is undefined; for a composite path it is the part before
+ * the first `#` and the id after it.
+ */
+export function splitSessionFilePath(filePath) {
+    const hash = filePath.indexOf(SESSION_FILE_PATH_SEP);
+    if (hash < 0)
+        return { container: filePath, fragment: undefined };
+    return { container: filePath.slice(0, hash), fragment: filePath.slice(hash + 1) || undefined };
+}
+/**
+ * The filesystem path whose existence/stat decides whether a session row is
+ * stale. For a composite `file_path` this is the CONTAINER file — the row is a
+ * record inside it, never a filesystem entry of its own — so a composite session
+ * is stale only when its container is gone. For a plain path it is the path
+ * itself. Keying off the composite FORM (a `#` fragment), not any harness name,
+ * means any future single-file-DB harness inherits the correct behavior.
+ */
+export function sessionFilePathContainer(filePath) {
+    return splitSessionFilePath(filePath).container;
+}
+// ---------------------------------------------------------------------------
 // OpenCode parser
 // ---------------------------------------------------------------------------
 /**
@@ -1279,36 +1313,124 @@ export function parseGrok(filePath) {
     }
     return events;
 }
+/**
+ * Byte/char caps for the OpenCode tool-part projection below. Numeric
+ * constants, interpolated into the SQL — never user input.
+ */
+const OPENCODE_OUTPUT_MAX_CHARS = 2000;
+const OPENCODE_INPUT_MAX_BYTES = 4000;
+/**
+ * The transcript query {@link parseOpenCode} runs, exported so a test can assert
+ * the projection's real cost against a database instead of re-typing the SQL.
+ *
+ * A tool part is PROJECTED to exactly the fields the `case 'tool'` branch below
+ * reads — `tool`, `callID`, `state.status`, `state.input`, `state.output` —
+ * rather than carried whole. Two things this has to get right at once:
+ *
+ *   - Keep `state.input`. It carries `filePath` / `command`, and losing it is
+ *     what left `recentDirectoriesTouched` empty (RUSH-2358).
+ *   - Stay bounded. A tool part is not bounded by its output: on a real
+ *     `opencode.db` the largest part is 1,346,068 bytes of which
+ *     `state.attachments` (a base64 data URL from `read`) is 1,345,674, while
+ *     `state.output` is 23. Truncating only `state.output` therefore bounded
+ *     nothing — it took one session's loaded tool payload from 299,365 to
+ *     1,911,209 bytes. The projection drops `attachments` (and every other
+ *     unread key) outright, caps `state.output`, and collapses an oversized
+ *     `state.input` to just its addressing fields. Those are the keys the
+ *     enrichment reads — `filePath`/`path` for an edit and `cwd`/`workdir`/
+ *     `working_directory` for a shell (`extractRecentDirectoriesTouched` in
+ *     state.ts), plus `command`/`description`, themselves capped since a command
+ *     can be arbitrarily long. Above the cap every other input key (an `edit`'s
+ *     `oldString`/`newString`) is gone, deliberately — nothing downstream reads
+ *     them, and they are the weight.
+ *
+ * `json_valid` guards every `json_extract`: SQLite raises "malformed JSON" on a
+ * non-JSON value, which aborts the WHOLE query, so one bad `part` row would
+ * otherwise cost the entire transcript. Note the single-argument form is
+ * RFC-8259-strict — it rejects a JSONB blob that `json_extract` would accept.
+ * That is correct for today's schema (`part.data` / `message.data` are TEXT on
+ * a real database); if OpenCode ever migrates them to JSONB, these guards must
+ * move to `json_valid(data, 6)` or they will drop every row.
+ *
+ * The session id is bound as a parameter; the two caps are numeric literals.
+ */
+export const OPENCODE_TRANSCRIPT_QUERY = `
+  SELECT
+    CASE WHEN json_valid(m.data) THEN json_extract(m.data, '$.role') END AS role,
+    CASE WHEN json_valid(p.data) THEN json_extract(p.data, '$.type') END AS part_type,
+    CASE
+      WHEN json_valid(p.data) AND json_extract(p.data, '$.type') = 'tool'
+      THEN json_object(
+        'type', 'tool',
+        'tool', json_extract(p.data, '$.tool'),
+        'callID', json_extract(p.data, '$.callID'),
+        'state', json_object(
+          'status', json_extract(p.data, '$.state.status'),
+          'input', CASE
+            WHEN LENGTH(CAST(COALESCE(json_extract(p.data, '$.state.input'), '') AS BLOB)) > ${OPENCODE_INPUT_MAX_BYTES}
+            THEN json_object(
+              'filePath', json_extract(p.data, '$.state.input.filePath'),
+              'path', json_extract(p.data, '$.state.input.path'),
+              'command', substr(COALESCE(json_extract(p.data, '$.state.input.command'), ''), 1, ${OPENCODE_OUTPUT_MAX_CHARS}),
+              'description', substr(COALESCE(json_extract(p.data, '$.state.input.description'), ''), 1, ${OPENCODE_OUTPUT_MAX_CHARS}),
+              'cwd', json_extract(p.data, '$.state.input.cwd'),
+              'workdir', json_extract(p.data, '$.state.input.workdir'),
+              'working_directory', json_extract(p.data, '$.state.input.working_directory')
+            )
+            ELSE json_extract(p.data, '$.state.input')
+          END,
+          'output', substr(COALESCE(json_extract(p.data, '$.state.output'), ''), 1, ${OPENCODE_OUTPUT_MAX_CHARS})
+        )
+      )
+      ELSE p.data
+    END AS part_data,
+    m.time_created AS time_created
+  FROM message m
+  JOIN part p ON p.message_id = m.id AND p.session_id = m.session_id
+  WHERE m.session_id = ?
+  ORDER BY m.time_created ASC, p.time_created ASC;
+`.replace(/\n/g, ' ');
 export function parseOpenCode(filePath) {
-    const [dbPath, sessionId] = filePath.split('#');
+    const { container: dbPath, fragment: sessionId } = splitSessionFilePath(filePath);
     if (!dbPath || !sessionId)
         return [];
     const events = [];
     // Read through the node/bun SQLite wrapper (not the `sqlite3` CLI) so this
     // works on every OS — the CLI is absent on Windows.
     let rows;
+    // OpenCode stores the session's checklist in its own `todo` table (the current
+    // snapshot, not a history). Emitted below as one `todo_write` tool_use event so
+    // the shared enrichment (`extractTodoProgressFromEvents`) computes `todos`
+    // uniformly with every other harness (RUSH-2358).
+    let todoRows = [];
     let db;
     try {
-        // Query messages with their parts, ordered chronologically. Tool parts are
-        // truncated to keep large tool outputs from bloating memory; the session id
-        // is bound as a parameter rather than interpolated.
-        const query = `
-      SELECT
-        json_extract(m.data, '$.role') AS role,
-        json_extract(p.data, '$.type') AS part_type,
-        CASE
-          WHEN json_extract(p.data, '$.type') = 'tool'
-          THEN substr(p.data, 1, 2000)
-          ELSE p.data
-        END AS part_data,
-        m.time_created AS time_created
-      FROM message m
-      JOIN part p ON p.message_id = m.id AND p.session_id = m.session_id
-      WHERE m.session_id = ?
-      ORDER BY m.time_created ASC, p.time_created ASC;
-    `.replace(/\n/g, ' ');
+        // Messages with their parts, ordered chronologically. The query — and why
+        // the tool part is projected rather than carried whole — is documented on
+        // OPENCODE_TRANSCRIPT_QUERY above.
         db = new Database(dbPath);
-        rows = db.prepare(query).all(sessionId);
+        rows = db.prepare(OPENCODE_TRANSCRIPT_QUERY).all(sessionId);
+        // The `todo` table is a newer OpenCode addition. Probe for it the same way
+        // the scanner probes newer `session` columns, rather than wrapping the read
+        // in a blanket catch — a catch there reported a locked, corrupt, or
+        // permission-denied database as "this session has no todos".
+        //
+        // Row COUNT, not an empty-`get()` sentinel: the two production runtimes
+        // disagree on what `get()` returns for no row — node:sqlite gives
+        // `undefined`, bun:sqlite gives `null` (both ship; see sqlite.ts). A check
+        // written against either sentinel is always-true on the other runtime,
+        // which would run the `todo` SELECT on a schema that has no such table,
+        // throw, and hand the whole transcript to the outer catch — an empty
+        // session, silently, and only in the shipped Bun binary. `.all().length`
+        // cannot express that disagreement.
+        const hasTodoTable = db
+            .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'todo';`)
+            .all().length > 0;
+        if (hasTodoTable) {
+            todoRows = db
+                .prepare('SELECT content, status, time_updated FROM todo WHERE session_id = ? ORDER BY position ASC;')
+                .all(sessionId);
+        }
     }
     catch {
         /* DB not accessible, sqlite module unavailable, or query failed */
@@ -1400,6 +1522,29 @@ export function parseOpenCode(filePath) {
     catch {
         /* malformed row payload — return what we parsed so far */
     }
+    // Emit the OpenCode `todo` table as one `todo_write` snapshot so the shared
+    // enrichment layer derives `todos` the same way it does for every harness that
+    // records a checklist tool. `todo_write` is in SNAPSHOT_TODO_TOOLS, and the
+    // enrichment reads `args.todos`, so the shape matches without special-casing.
+    const todos = todoRows
+        .map(t => ({
+        content: typeof t.content === 'string' ? t.content : '',
+        status: typeof t.status === 'string' ? t.status : 'pending',
+    }))
+        .filter(t => t.content.trim());
+    if (todos.length) {
+        const lastTodoMs = todoRows.reduce((max, t) => {
+            const ms = typeof t.time_updated === 'number' ? t.time_updated : parseInt(String(t.time_updated), 10);
+            return Number.isFinite(ms) && ms > max ? ms : max;
+        }, 0);
+        events.push({
+            type: 'tool_use',
+            agent: 'opencode',
+            timestamp: lastTodoMs > 0 ? new Date(lastTodoMs).toISOString() : new Date().toISOString(),
+            tool: 'todo_write',
+            args: { todos },
+        });
+    }
     return events;
 }
 // ---------------------------------------------------------------------------

package/dist/lib/session/session-cache.d.ts

@@ -2,13 +2,14 @@ import type { ActiveSession } from './active.js';
 /**
  * How long a snapshot may be served before a reader re-gathers.
  * Short on purpose: live status (running/idle/waiting) must not go stale.
- * The daemon warm tick uses the same cadence (see {@link SESSION_CACHE_WARM_INTERVAL_MS}).
+ * The daemon warms more frequently than this ceiling so normal readers hit a
+ * fresh snapshot while expiry still forces a live gather after a missed tick.
  */
-export declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS: number;
-/** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
-export declare const SESSION_CACHE_WARM_INTERVAL_MS: number;
-/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
-export declare const SESSION_CACHE_WARM_KICKOFF_MS = 30000;
+export declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15000;
+/** Daemon warm interval — below the freshness ceiling to avoid an expiry gap. */
+export declare const SESSION_CACHE_WARM_INTERVAL_MS = 10000;
+/** Kick off the first warm shortly after daemon start, staggered off bootstrap. */
+export declare const SESSION_CACHE_WARM_KICKOFF_MS = 5000;
 /** Snapshot scope: this host only, or a fleet-wide merge written by a reader. */
 export type ActiveCacheScope = 'local' | 'fleet';
 export interface ActiveSessionsSnapshot {
@@ -56,6 +57,8 @@ export declare const IMMUTABLE_FIELD_KEYS: readonly ["topic", "label", "name", "
 export declare const LIVE_STATUS_KEYS: readonly ["status", "activity", "preview", "tokPerSec", "awaitingReason", "question", "todos", "tail", "lastActivityMs", "hostLink", "presence", "pidAlive", "tmuxClients", "windowHeartbeatMs", "provenance", "rateLimited", "plan"];
 /** Test seam: redirect the snapshot file. Returns the previous override. */
 export declare function setActiveSessionsSnapshotPathForTest(p: string | null): string | null;
+/** Test seam: isolate process-local entries between fixtures. */
+export declare function clearActiveSnapshotMemoryForTest(): void;
 /** Test seam: redirect the immutable-memo file. Returns the previous override. */
 export declare function setImmutableMemoPathForTest(p: string | null): string | null;
 /** Read one scope from the snapshot file (best-effort; missing/corrupt → null). */

package/dist/lib/session/session-cache.js

@@ -24,6 +24,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { createMemoryCache } from '../memory-cache.js';
 import { getCacheDir } from '../state.js';
 /** Snapshot file under `getCacheDir()` (regenerable, gitignored). */
 const SNAPSHOT_FILE = '.active-sessions.json';
@@ -32,13 +33,19 @@ const IMMUTABLE_FILE = '.active-session-immutable.json';
 /**
  * How long a snapshot may be served before a reader re-gathers.
  * Short on purpose: live status (running/idle/waiting) must not go stale.
- * The daemon warm tick uses the same cadence (see {@link SESSION_CACHE_WARM_INTERVAL_MS}).
+ * The daemon warms more frequently than this ceiling so normal readers hit a
+ * fresh snapshot while expiry still forces a live gather after a missed tick.
  */
-export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 4 * 60_000;
-/** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
-export const SESSION_CACHE_WARM_INTERVAL_MS = 3 * 60_000;
-/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
-export const SESSION_CACHE_WARM_KICKOFF_MS = 30_000;
+export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15_000;
+/** Daemon warm interval — below the freshness ceiling to avoid an expiry gap. */
+export const SESSION_CACHE_WARM_INTERVAL_MS = 10_000;
+/** Kick off the first warm shortly after daemon start, staggered off bootstrap. */
+export const SESSION_CACHE_WARM_KICKOFF_MS = 5_000;
+/** Process-local L1. The atomic snapshot remains the cross-process source. */
+const activeSnapshotMemory = createMemoryCache({
+    max: 2,
+    ttlMs: DEFAULT_ACTIVE_CACHE_MAX_AGE_MS,
+});
 /** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',
@@ -92,8 +99,13 @@ let immutablePathOverride = null;
 export function setActiveSessionsSnapshotPathForTest(p) {
     const prev = snapshotPathOverride;
     snapshotPathOverride = p;
+    activeSnapshotMemory.clear();
     return prev;
 }
+/** Test seam: isolate process-local entries between fixtures. */
+export function clearActiveSnapshotMemoryForTest() {
+    activeSnapshotMemory.clear();
+}
 /** Test seam: redirect the immutable-memo file. Returns the previous override. */
 export function setImmutableMemoPathForTest(p) {
     const prev = immutablePathOverride;
@@ -109,6 +121,9 @@ function immutablePath() {
 // ── snapshot read / write ──────────────────────────────────────────────────
 /** Read one scope from the snapshot file (best-effort; missing/corrupt → null). */
 export function readActiveSessionsCache(scope) {
+    const memory = activeSnapshotMemory.get(scope);
+    if (memory)
+        return memory;
     try {
         const parsed = JSON.parse(fs.readFileSync(snapshotPath(), 'utf-8'));
         if (!parsed || parsed.version !== 1 || !parsed.entries)
@@ -116,6 +131,7 @@ export function readActiveSessionsCache(scope) {
         const entry = parsed.entries[scope];
         if (!entry || !Array.isArray(entry.sessions) || typeof entry.capturedAt !== 'number')
             return null;
+        activeSnapshotMemory.set(scope, entry);
         return entry;
     }
     catch {
@@ -153,6 +169,7 @@ export function writeActiveSessionsCache(scope, sessions, opts = {}) {
         const tmp = `${snapshotPath()}.tmp`;
         fs.writeFileSync(tmp, JSON.stringify(body));
         fs.renameSync(tmp, snapshotPath());
+        activeSnapshotMemory.set(scope, snap);
     }
     catch {
         // best-effort

package/dist/lib/shims.js

@@ -600,6 +600,18 @@ else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi
 
+# A managed binary must never resolve back into this dispatcher. This can
+# happen when an install-script launcher was imported before adoption and was
+# later repointed at the agents shim. Use the durable native target recorded by
+# adoption instead of recursively exec-ing this script.
+if [ -x "$BINARY" ]; then
+  RESOLVED_BINARY=$(realpath "$BINARY" 2>/dev/null || readlink -f "$BINARY" 2>/dev/null || echo "")
+  RESOLVED_SHIM=$(realpath "$AGENTS_USER_DIR/.cache/shims/$CLI_COMMAND" 2>/dev/null || readlink -f "$AGENTS_USER_DIR/.cache/shims/$CLI_COMMAND" 2>/dev/null || echo "")
+  if [ -n "$RESOLVED_BINARY" ] && [ "$RESOLVED_BINARY" = "$RESOLVED_SHIM" ]; then
+    BINARY=$(adopted_original_bin || echo "")
+  fi
+fi
+
 # Auto-install if not present
 if [ ! -x "$BINARY" ]; then
   if [ "$VERSION_SOURCE" = "project" ]; then

package/dist/lib/startup/command-registry.d.ts

@@ -18,7 +18,7 @@
  * versions (which creates `prune <specs...>`) and prune.js (which attaches the
  * `cleanup` subcommand to it), in that order — see commands/prune.ts.
  */
-import type { Command } from 'commander';
+import { Command } from 'commander';
 /** A function that registers one or more commands onto the root program. */
 export type Registrar = (program: Command) => void;
 /** A thunk that dynamically imports a command module and returns its registrar. */
@@ -110,6 +110,8 @@ export declare const loadAudit: ModuleLoader;
 export declare const loadWebhook: ModuleLoader;
 export declare const loadFunnel: ModuleLoader;
 export declare const loadHumans: ModuleLoader;
+export declare const loadAccounts: ModuleLoader;
+export declare const loadDaemon: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -148,3 +150,15 @@ export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;
 export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 /** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
 export declare function isKnownTopLevelCommand(name: string): boolean;
+/**
+ * Register every module in {@link COMMAND_LOADERS} onto one fresh program and
+ * return it — the full public command tree, deduped by loader identity so a
+ * loader mapped to several names (e.g. `add`/`use`/`list` -> versions) runs once.
+ *
+ * Off the hot path only: the command-index generator (`scripts/gen-command-index.ts`)
+ * and the tests build the tree from this. Startup never calls it — src/index.ts
+ * registers just the one requested command via `registerEagerForRequest`. The
+ * inline aliases/tombstones ({@link INLINE_COMMAND_NAMES}) are NOT included: they
+ * are closures over entry-point state that src/index.ts registers directly.
+ */
+export declare function buildFullCommandTree(): Promise<Command>;

package/dist/lib/startup/command-registry.js

@@ -1,3 +1,24 @@
+/**
+ * Lazy command registry.
+ *
+ * The CLI entry point (src/index.ts) used to statically import every command
+ * module and call its `registerXCommand(program)` on every invocation. That
+ * loaded the entire command tree (~50 modules) before the first line of output,
+ * dominating cold-start latency.
+ *
+ * This module maps each user-typed top-level command name to a thunk that
+ * dynamically imports ONLY the module(s) that command needs. Fast commands
+ * (`--version`, `view`, ...) now pay for just the one module they use; the full
+ * tree is loaded only on the rare slow paths (unknown-command spellcheck, bare
+ * help) via `registerAllEagerCommands` in src/index.ts.
+ *
+ * Parity is non-negotiable: the name -> loader map below mirrors exactly which
+ * module registers which top-level command on `main`. Multi-command modules
+ * (versions, packages) map several names to the same loader; `prune` needs BOTH
+ * versions (which creates `prune <specs...>`) and prune.js (which attaches the
+ * `cleanup` subcommand to it), in that order — see commands/prune.ts.
+ */
+import { Command } from 'commander';
 // One loader per command module. Each dynamically imports the module and hands
 // back its register function. Kept as named consts so src/index.ts can compose
 // them into the exact main-branch registration order for the slow path.
@@ -89,6 +110,8 @@ export const loadAudit = async () => (await import('../../commands/audit.js')).r
 export const loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
 export const loadFunnel = async () => (await import('../../commands/funnel.js')).registerFunnelCommand;
 export const loadHumans = async () => (await import('../../commands/humans.js')).registerHumansCommands;
+export const loadAccounts = async () => (await import('../../commands/accounts.js')).registerAccountsCommand;
+export const loadDaemon = async () => (await import('../../commands/daemon.js')).registerDaemonCommand;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -123,6 +146,7 @@ export const LAZY_COMMAND_NAMES = new Set([
  * are handled directly in src/index.ts.
  */
 export const COMMAND_LOADERS = {
+    accounts: [loadAccounts],
     view: [loadView],
     inspect: [loadInspect],
     feedback: [loadFeedback],
@@ -241,6 +265,7 @@ export const COMMAND_LOADERS = {
     webhook: [loadWebhook],
     funnel: [loadFunnel],
     humans: [loadHumans],
+    daemon: [loadDaemon],
 };
 /**
  * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
@@ -279,3 +304,27 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
 export function isKnownTopLevelCommand(name) {
     return KNOWN_TOP_LEVEL_COMMANDS.has(name);
 }
+/**
+ * Register every module in {@link COMMAND_LOADERS} onto one fresh program and
+ * return it — the full public command tree, deduped by loader identity so a
+ * loader mapped to several names (e.g. `add`/`use`/`list` -> versions) runs once.
+ *
+ * Off the hot path only: the command-index generator (`scripts/gen-command-index.ts`)
+ * and the tests build the tree from this. Startup never calls it — src/index.ts
+ * registers just the one requested command via `registerEagerForRequest`. The
+ * inline aliases/tombstones ({@link INLINE_COMMAND_NAMES}) are NOT included: they
+ * are closures over entry-point state that src/index.ts registers directly.
+ */
+export async function buildFullCommandTree() {
+    const program = new Command();
+    const done = new Set();
+    for (const loaders of Object.values(COMMAND_LOADERS)) {
+        for (const loader of loaders) {
+            if (done.has(loader))
+                continue;
+            done.add(loader);
+            (await loader())(program);
+        }
+    }
+    return program;
+}

package/dist/lib/usage-refresh.js

@@ -198,8 +198,9 @@ export async function buildLocalUsageAccounts() {
                 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).
+                // that path is the Touch ID storm. Usage reads the file-based setup-token
+                // only, never the interactive login (see loadClaudeOauth); no setup-token
+                // reads as "usage pending".
                 fetch: () => getUsageInfo(agentId, {
                     home: fetchInput.home,
                     cliVersion: fetchInput.cliVersion,

package/dist/lib/usage.d.ts

@@ -466,17 +466,19 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * (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.
+ * `opts.accessTokenCache` marks a read-only, access-token-only consumer (the
+ * usage fetch and the auth-health probe). Such a caller authenticates ONLY with
+ * a file-based setup-token and, when none is provisioned, gets `null` — it never
+ * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
+ * to Anthropic's API is what gets it revoked; see the branch body and
+ * docs/design/credential-management.md). It is OFF by default so full-credential
+ * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) or export
+ * the full blob (`readClaudeCredentialsBlob` for Rush Cloud dispatch) still read
+ * the interactive login.
  *
- * `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.
+ * `opts.fileOnly` skips the ACL keychain read entirely — setup-token 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;