@phnx-labs/agents-cli 1.20.15 → 1.20.17

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+**Headless Linux: `agents secrets` works out of the box when the keyring is locked**
+
+- On a headless server the libsecret/GNOME-keyring collection is locked, so the encrypted-file fallback is the only option — but it previously hard-failed unless `AGENTS_SECRETS_PASSPHRASE` was set, leaving `agents secrets` silently unusable. Now, on a headless run with no passphrase set, a random machine-local passphrase is auto-provisioned once at `~/.agents/.cache/secrets/.passphrase` (mode 0600) so the encrypted-file store just works. `AGENTS_SECRETS_PASSPHRASE` still takes precedence (off-disk key), an existing `.passphrase` is reused for stable interactive/headless behavior, and interactive TTY sessions are still prompted. Security model + resolution order documented in `docs/secrets.md`. (#371)
+
+**`agents secrets get/set <item>`: raw, cross-platform keychain access for hooks**
+
+- New `agents secrets get <item>` / `agents secrets set <item>` read and write a single keychain item **by bare name** (outside the bundle namespace), so shell hooks and automation have one platform-agnostic credential primitive to call instead of hardcoding `/usr/bin/security` (macOS-only) or `secret-tool` (Linux-only). `get` prints the value to stdout (newline-terminated for clean `$(…)` capture), sends diagnostics to stderr, and exits 1 with empty stdout when the item is missing — exactly what a `SessionStart` hook needs to probe-and-fallback quietly. Routing goes through the existing cross-platform keychain layer: macOS via `/usr/bin/security`, Linux via `secret-tool` with the encrypted-file fallback.
+- `setKeychainToken` now writes bare (non-`agents-cli.`) items on macOS **without** the biometry ACL, mirroring the existing no-prompt read path for such items. This is what lets a hook read e.g. `linear-api-key` silently on every launch — routing it through the Touch ID helper would attach an ACL the `/usr/bin/security` read can't satisfy without popping the legacy password sheet. The change is purely additive: every existing caller passes an `agents-cli.`-namespaced item and is unaffected (still biometry-gated via the signed helper).
+
 **`agents inspect` summary: expanded detail for hooks, plugins, and MCP**
 
 - The bare `agents inspect <agent>` / `agents inspect <repo>` summary no longer collapses everything to a count table. Simple kinds (commands, skills, rules, subagents, workflows) keep a count line but now preview a few names; the rich kinds get their own expanded sections: **hooks** show their events + `matches:` predicates + cache (`PreToolUse(Bash) · git_dirty · prompt~"deploy" (5m cache)`), **plugins** show version + bundle contents (`v2.1.0  skills:6 commands:5 hooks:2 mcp:1`), and **MCP** show transport + url/command. Drill-down flags (`--hooks`, `--plugins`, `--mcp`) and `--brief` are unchanged; `--json` gains the structured detail additively (existing keys retained).

package/dist/commands/secrets.js

@@ -8,7 +8,7 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
-import { deleteKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -365,6 +365,7 @@ export function registerSecretsCommands(program) {
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
+        { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
     ]);
@@ -465,6 +466,57 @@ export function registerSecretsCommands(program) {
             process.exit(1);
         }
     });
+    cmd
+        .command('get <item>')
+        .description('Print a raw keychain item by name (for shell hooks/automation). Cross-platform; no bundle required.')
+        .action((item) => {
+        try {
+            // Routes through the platform keychain layer: macOS reads bare items
+            // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
+            // encrypted-file fallback. The value goes to stdout (newline-terminated
+            // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
+            // to stderr so they never pollute the captured value.
+            const value = getKeychainToken(item);
+            process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
+        }
+        catch {
+            // Missing item is a normal, quiet outcome for a hook probe: exit 1,
+            // print nothing to stdout. Callers test the exit code / empty capture.
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('set <item>')
+        .description('Store a raw keychain item by name (for shell hooks/automation). Cross-platform; no bundle required.')
+        .option('--value <v>', 'Value to store (omit to read from stdin or be prompted)')
+        .option('--value-stdin', 'Read the value from stdin')
+        .action(async (item, opts) => {
+        try {
+            let value;
+            if (opts.value !== undefined) {
+                value = opts.value;
+            }
+            else if (opts.valueStdin) {
+                value = readStdinSync();
+                if (!value)
+                    throw new Error('No value received on stdin.');
+            }
+            else {
+                value = await promptForSecret(`Enter value for ${item}`);
+            }
+            // setKeychainToken stores bare items WITHOUT the biometry ACL on macOS
+            // so `agents secrets get` can read them back without a password sheet;
+            // on Linux it goes through secret-tool / encrypted-file fallback.
+            setKeychainToken(item, value);
+            console.error(chalk.green(`Stored keychain item '${item}'.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     cmd
         .command('create [name]')
         .description('Create an empty bundle')

package/dist/commands/sessions-sync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `agents sessions sync` — push this machine's transcripts to R2 and pull every
+ * other machine's, merging copies of the same session via CRDT union. The local
+ * sessions index is rebuilt from the synced-in mirror by the normal scanner.
+ */
+import type { Command } from 'commander';
+interface SyncCmdOptions {
+    verbose?: boolean;
+    json?: boolean;
+}
+export declare function runSessionsSync(options: SyncCmdOptions): Promise<void>;
+export declare function registerSessionsSyncCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-sync.js

@@ -0,0 +1,73 @@
+/**
+ * `agents sessions sync` — push this machine's transcripts to R2 and pull every
+ * other machine's, merging copies of the same session via CRDT union. The local
+ * sessions index is rebuilt from the synced-in mirror by the normal scanner.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { isSyncConfigured, SYNC_BUNDLE } from '../lib/session/sync/config.js';
+import { syncSessions } from '../lib/session/sync/sync.js';
+export async function runSessionsSync(options) {
+    if (!isSyncConfigured()) {
+        console.error(chalk.red(`Sessions sync is not configured.`) +
+            `\nAdd R2 credentials to the '${SYNC_BUNDLE}' bundle:\n` +
+            `  agents secrets add ${SYNC_BUNDLE} R2_ACCOUNT_ID\n` +
+            `  agents secrets add ${SYNC_BUNDLE} R2_BUCKET_NAME\n` +
+            `  agents secrets add ${SYNC_BUNDLE} R2_ACCESS_KEY_ID\n` +
+            `  agents secrets add ${SYNC_BUNDLE} R2_SECRET_ACCESS_KEY`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const result = await syncSessions({
+            verbose: options.verbose,
+            log: msg => console.error(chalk.dim(msg)),
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const parts = [
+                `pushed ${result.pushed}`,
+                `pulled ${result.pulled}`,
+                result.merged > 0 ? `merged ${result.merged}` : null,
+            ].filter(Boolean);
+            console.log(chalk.green('synced') + ` ${result.machine}: ` + parts.join(', ') +
+                chalk.dim(` (${result.pushSkipped + result.pullSkipped} unchanged)`));
+        }
+        if (result.errors.length > 0) {
+            for (const e of result.errors)
+                console.error(chalk.yellow(`  ! ${e}`));
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`sync failed: ${err.message}`));
+        process.exitCode = 1;
+    }
+}
+export function registerSessionsSyncCommand(sessionsCmd) {
+    const syncCmd = sessionsCmd
+        .command('sync')
+        .description('Sync session transcripts across machines via R2 (CRDT merge). Claude and Codex.')
+        .option('-v, --verbose', 'Log each pushed and pulled session')
+        .option('--json', 'Output the sync result as JSON');
+    setHelpSections(syncCmd, {
+        examples: `
+      # One sync cycle (push local changes, pull + merge from other machines)
+      agents sessions sync
+
+      # See exactly what moved
+      agents sessions sync --verbose
+    `,
+        notes: `
+      - Credentials come from the '${SYNC_BUNDLE}' secrets bundle (R2 S3 API, read+write).
+      - Each machine writes only its own prefix; conflicts are impossible by construction.
+      - The daemon runs this automatically (~90s); this command forces an immediate cycle.
+      - Sessions present locally always win; synced-in copies fill in other machines' sessions.
+    `,
+    });
+    syncCmd.action(async (options) => {
+        await runSessionsSync(options);
+    });
+}

package/dist/commands/sessions.js

@@ -29,6 +29,7 @@ import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
+import { registerSessionsSyncCommand } from './sessions-sync.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
@@ -1144,6 +1145,7 @@ export function registerSessionsCommands(program) {
         await sessionsAction(query, options);
     });
     registerSessionsTailCommand(sessionsCmd);
+    registerSessionsSyncCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/sync.d.ts

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing

package/dist/commands/sync.js

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing
@@ -25,12 +32,13 @@ import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVers
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     program
         .command('sync [agentSpec]')
-        .summary('Sync resources into an installed agent version')
-        .description('Sync resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into an installed agent version. Previews what will change and lets you pick.\n\n[agentSpec] is the agent name with an optional @version, e.g. "claude" or "claude@2.1.142". Omit the version to sync into the active (or sole installed) one.')
+        .summary('Make this machine current, or sync resources into one agent')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude" or "claude@2.1.142".\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
@@ -39,10 +47,66 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
+        // Umbrella verb (no agent given): make this machine current.
+        .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
+        .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
+        .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
+        .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
+        .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
         .action(async (agentSpec, opts) => {
         await runSync(agentSpec, opts);
     });
 }
+/**
+ * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
+ * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
+ * arrives with `agents login`) and runs the fetch+reconcile stages, then prints
+ * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
+ */
+async function runUmbrella(opts, quiet, outLog, errLog) {
+    const flags = {
+        repos: opts.repos,
+        secrets: opts.secrets,
+        sessions: opts.sessions,
+        cloud: opts.cloud,
+        local: opts.local,
+    };
+    const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE || undefined;
+    if (!quiet)
+        outLog(chalk.bold('Syncing this machine…'));
+    try {
+        const result = await runUmbrellaSync({
+            flags,
+            yes: !!opts.yes,
+            passphrase,
+            log: (msg) => { if (!quiet)
+                outLog(chalk.gray(`  ${msg}`)); },
+        });
+        if (!quiet) {
+            const parts = [];
+            if (result.repos) {
+                parts.push(`repos ${result.repos.pulled} pulled` +
+                    (result.repos.errors.length ? `, ${result.repos.errors.length} failed` : ''));
+            }
+            if (result.secrets) {
+                parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
+            }
+            if (result.sessions) {
+                parts.push(result.sessions.ran ? `sessions ${result.sessions.merged} merged` : 'sessions off');
+            }
+            if (result.reconciled)
+                parts.push('reconciled');
+            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+            const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
+            for (const e of errs)
+                errLog(chalk.yellow(`  ! ${e}`));
+        }
+    }
+    catch (err) {
+        errLog(chalk.red(`sync failed: ${err.message}`));
+        process.exitCode = 1;
+    }
+}
 async function runSync(agentSpec, opts) {
     const quiet = !!opts.quiet;
     const errLog = (msg) => { if (!quiet)
@@ -77,10 +141,9 @@ async function runSync(agentSpec, opts) {
         version = opts.agentVersion;
     }
     if (!agentId) {
-        errLog(chalk.red('Usage: agents sync <agent>[@version]'));
-        errLog(chalk.gray('       agents sync claude'));
-        errLog(chalk.gray('       agents sync claude@2.1.142'));
-        process.exitCode = 1;
+        // No agent specified → the umbrella verb: make this machine current
+        // (fetch repos + secrets + sessions, then reconcile all installed agents).
+        await runUmbrella(opts, quiet, outLog, errLog);
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------

package/dist/commands/view.js

@@ -3,7 +3,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
-import { formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
+import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
@@ -306,7 +306,11 @@ async function showInstalledVersions(filterAgentId) {
         return {
             ...info,
             plan: canon.plan,
-            usageStatus: canon.usageStatus,
+            // Throttle state comes from the live usage windows, not the pay-as-you-go
+            // overage flag that AccountInfo.usageStatus used to carry. A maxed window
+            // means rate-limited; no snapshot means no badge. See
+            // deriveUsageStatusFromSnapshot.
+            usageStatus: deriveUsageStatusFromSnapshot(usageByKey.get(key)?.snapshot),
             overageCredits: canon.overageCredits,
         };
     };
@@ -984,7 +988,11 @@ async function collectAgentsJson(filterAgentId) {
         return {
             ...info,
             plan: canon.plan,
-            usageStatus: canon.usageStatus,
+            // Throttle state comes from the live usage windows, not the pay-as-you-go
+            // overage flag that AccountInfo.usageStatus used to carry. A maxed window
+            // means rate-limited; no snapshot means no badge. See
+            // deriveUsageStatusFromSnapshot.
+            usageStatus: deriveUsageStatusFromSnapshot(usageByKey.get(key)?.snapshot),
             overageCredits: canon.overageCredits,
         };
     };

package/dist/index.js

@@ -893,7 +893,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v9';
+        const sentinelValue = 'v10';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/agents.d.ts

@@ -13,6 +13,17 @@ export interface CliState {
 export declare const CODEX_HOOKS_MIN_VERSION = "0.116.0";
 /** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
 export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
+/**
+ * Synchronous PATH search -- no subprocess. Returns first matching binary path.
+ *
+ * Skips our own shims dir (`~/.agents/.cache/shims/`) — those shims are
+ * dispatch helpers, not real installs. Counting them as installed produced a
+ * false positive where agents with NO real binary on the host (e.g. a
+ * never-installed Cursor whose only PATH entry was our `cursor-agent` shim
+ * dispatcher) showed up under `agents view`'s "Not Managed by Agents CLI"
+ * section, even though the user had nothing to import.
+ */
+export declare function findInPath(command: string): string | null;
 /**
  * Master registry of all supported agents keyed by AgentId.
  *

package/dist/lib/agents.js

@@ -66,7 +66,7 @@ function saveCliVersionCache() {
  * dispatcher) showed up under `agents view`'s "Not Managed by Agents CLI"
  * section, even though the user had nothing to import.
  */
-function findInPath(command) {
+export function findInPath(command) {
     const pathEnv = process.env.PATH || '';
     const pathExt = process.platform === 'win32' ? (process.env.PATHEXT || '').split(';') : [''];
     const shimsDir = getShimsDir();
@@ -814,14 +814,16 @@ export async function getAccountInfo(agentId, home) {
                 else if (oa?.billingType) {
                     plan = oa.billingType;
                 }
-                let usageStatus = null;
-                const reason = data.cachedExtraUsageDisabledReason;
-                if (reason === 'out_of_credits')
-                    usageStatus = 'out_of_credits';
-                else if (reason)
-                    usageStatus = 'rate_limited';
-                else
-                    usageStatus = 'available';
+                // usageStatus is NOT derived from cachedExtraUsageDisabledReason. That
+                // field reports why pay-as-you-go overage is off (out_of_credits = no
+                // overage credits purchased; org_level_disabled = admin turned overage
+                // off), which says nothing about whether the account is throttled — a
+                // Pro account at 5% weekly usage with overage disabled is fully usable.
+                // Real throttle state comes from the live usage windows; callers derive
+                // it via deriveUsageStatusFromSnapshot(). Here we only report whether
+                // the account is signed in at all. Overage state stays visible through
+                // overageCredits below.
+                const usageStatus = email ? 'available' : null;
                 let overageCredits = null;
                 const orgId = oa?.organizationUuid;
                 const creditCache = orgId && data.overageCreditGrantCache?.[orgId];

package/dist/lib/daemon.d.ts

@@ -18,6 +18,16 @@ export declare function isDaemonRunning(): boolean;
 export declare function log(level: string, message: string): void;
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export declare function runDaemon(): Promise<void>;
+/**
+ * Read the long-lived Claude OAuth token (from `claude setup-token`) that the
+ * user stored under the `claude` secrets bundle. Resolves the bundle the same
+ * way `agents run --secrets` does, so the token is found whether it was stored
+ * keychain-backed or as a literal. Returns null when the bundle/key isn't
+ * configured, the Keychain read is cancelled, or the platform has no keychain —
+ * the daemon then behaves exactly as before (relying on the interactive OAuth
+ * session). Never throws: a misconfigured token must not block daemon startup.
+ */
+export declare function readDaemonClaudeOAuthToken(): string | null;
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export declare function generateLaunchdPlist(): string;
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
@@ -27,6 +37,15 @@ export declare function startDaemon(): {
     pid: number | null;
     method: string;
 };
+/**
+ * Environment for the detached daemon fallback. The launchd/systemd paths
+ * deliver the long-lived OAuth token via the service manifest's environment;
+ * the detached path has no manifest, so inject it here. Read happens during an
+ * interactive `routines start`, so a Keychain Touch ID prompt can be satisfied;
+ * the daemon then passes it to every routine run it spawns. An already-set
+ * value (e.g. inherited from launchd) is left untouched.
+ */
+export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export declare function stopDaemon(): boolean;
 /** Get current daemon status including running state, PID, and enabled job count. */