@phnx-labs/agents-cli 1.20.15 → 1.20.16

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+**`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/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. */

package/dist/lib/daemon.js

@@ -18,6 +18,7 @@ import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
+import { readAndResolveBundleEnv } from './secrets/bundles.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -25,6 +26,12 @@ const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
 const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
+// A long-lived `claude setup-token` value stored in this secrets bundle/key is
+// baked into the daemon's service-manager environment so headless routine runs
+// authenticate without depending on the short-lived interactive Keychain OAuth
+// session (which expires between runs and produces intermittent 401s).
+const DAEMON_OAUTH_BUNDLE = 'claude';
+const DAEMON_OAUTH_KEY = 'CLAUDE_CODE_OAUTH_TOKEN';
 function getDaemonDir() {
     const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
@@ -225,6 +232,34 @@ export async function runDaemon() {
     const monitorInterval = setInterval(() => {
         monitorRunningJobs();
     }, 60_000);
+    // Cross-machine session sync: push this machine's transcripts to R2 and pull
+    // every other machine's, ~every 90s. Skipped silently when the r2.backups
+    // bundle is absent. An overlap guard prevents a slow cycle from stacking.
+    let syncing = false;
+    const runSessionSync = async () => {
+        if (syncing)
+            return;
+        syncing = true;
+        try {
+            const { isSyncConfigured } = await import('./session/sync/config.js');
+            if (!isSyncConfigured())
+                return;
+            const { syncSessions } = await import('./session/sync/sync.js');
+            const r = await syncSessions();
+            if (r.pushed || r.pulled || r.errors.length) {
+                log('INFO', `sessions sync: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}` +
+                    (r.errors.length ? `, ${r.errors.length} error(s): ${r.errors[0]}` : ''));
+            }
+        }
+        catch (err) {
+            log('ERROR', `sessions sync failed: ${err.message}`);
+        }
+        finally {
+            syncing = false;
+        }
+    };
+    const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
+    void runSessionSync(); // kick once at startup
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -236,6 +271,7 @@ export async function runDaemon() {
         scheduler.stopAll();
         await browserIPC.stop();
         clearInterval(monitorInterval);
+        clearInterval(syncInterval);
         removeDaemonPid();
         process.exit(0);
     };
@@ -244,10 +280,42 @@ export async function runDaemon() {
     process.on('SIGINT', () => handleShutdown());
     await new Promise(() => { });
 }
+/**
+ * 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 function readDaemonClaudeOAuthToken() {
+    try {
+        const { env } = readAndResolveBundleEnv(DAEMON_OAUTH_BUNDLE, { caller: 'daemon' });
+        const token = (env[DAEMON_OAUTH_KEY] ?? '').trim();
+        return token.length > 0 ? token : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Escape a string for safe inclusion in an XML <string> node. */
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist() {
     const agentsBin = getAgentsBinPath();
     const logPath = getLogPath();
+    const oauthToken = readDaemonClaudeOAuthToken();
+    const oauthEntry = oauthToken
+        ? `
+    <key>${DAEMON_OAUTH_KEY}</key>
+    <string>${xmlEscape(oauthToken)}</string>`
+        : '';
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -271,7 +339,7 @@ export function generateLaunchdPlist() {
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin</string>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin</string>${oauthEntry}
   </dict>
 </dict>
 </plist>`;
@@ -279,6 +347,10 @@ export function generateLaunchdPlist() {
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
 export function generateSystemdUnit() {
     const agentsBin = getAgentsBinPath();
+    const oauthToken = readDaemonClaudeOAuthToken();
+    const oauthLine = oauthToken
+        ? `\nEnvironment=${DAEMON_OAUTH_KEY}=${oauthToken}`
+        : '';
     return `[Unit]
 Description=Agents Daemon - Scheduled Job Runner
 After=network.target
@@ -288,7 +360,7 @@ Type=simple
 ExecStart=${agentsBin} daemon _run
 Restart=always
 RestartSec=10
-Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin
+Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin${oauthLine}
 
 [Install]
 WantedBy=default.target`;
@@ -338,6 +410,9 @@ function startDaemonLocked() {
                 fs.mkdirSync(plistDir, { recursive: true });
             }
             fs.writeFileSync(plistPath, generateLaunchdPlist(), 'utf-8');
+            // The plist may embed a long-lived OAuth token in EnvironmentVariables;
+            // keep it owner-only so it isn't world/group readable on disk.
+            fs.chmodSync(plistPath, 0o600);
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -365,6 +440,8 @@ function startDaemonLocked() {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
             fs.writeFileSync(unitPath, generateSystemdUnit(), 'utf-8');
+            // May embed a long-lived OAuth token in an Environment= line; owner-only.
+            fs.chmodSync(unitPath, 0o600);
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
@@ -377,6 +454,23 @@ function startDaemonLocked() {
     }
     return startDetached();
 }
+/**
+ * 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 function buildDetachedDaemonEnv(baseEnv = process.env) {
+    const env = { ...baseEnv };
+    if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
+        const token = readDaemonClaudeOAuthToken();
+        if (token)
+            env.CLAUDE_CODE_OAUTH_TOKEN = token;
+    }
+    return env;
+}
 function startDetached() {
     const agentsBin = getAgentsBinPath();
     const logPath = getLogPath();
@@ -384,6 +478,7 @@ function startDetached() {
     const child = spawn(agentsBin, ['daemon', '_run'], {
         stdio: ['ignore', logFd, logFd],
         detached: true,
+        env: buildDetachedDaemonEnv(),
     });
     child.unref();
     fs.closeSync(logFd);

package/dist/lib/migrate.d.ts

@@ -25,6 +25,28 @@
  * LEGACY_SYSTEM_DIR" without duplicating data.
  */
 export declare function foldLegacySystemRepo(): void;
+/**
+ * Repair self-referential agent binary symlinks.
+ *
+ * Some installScript-based agents — notably Factory's `droid`, whose installer
+ * drops a standalone native binary at ~/.local/bin/droid — were registered at
+ * install time by resolving the post-install binary with `which <cli>`. Because
+ * ~/.agents/.cache/shims sits ahead of ~/.local/bin on PATH, `which` could
+ * return OUR OWN dispatcher shim, and the install step symlinked
+ *   ~/.agents/.history/versions/<agent>/<version>/node_modules/.bin/<cli>
+ * back at ~/.agents/.cache/shims/<cli>. Launching that agent then re-execs the
+ * dispatcher forever (an infinite exec loop that hangs the terminal).
+ *
+ * This walks every installed version's node_modules/.bin and, for any entry
+ * whose symlink resolves into the shims dir, re-points it at the real binary
+ * (found on PATH with the shims dir excluded) — or removes it when no real
+ * binary can be found, letting getBinaryPath's per-agent resolver take over.
+ * Idempotent: a correctly-pointed link is left untouched on re-run.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests
+ * can drive a fixture tree without touching the user's ~/.agents.
+ */
+export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string): void;
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in

package/dist/lib/migrate.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { AGENTS, agentConfigDirName } from './agents.js';
+import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -715,6 +715,100 @@ function repairAgentConfigSymlinks() {
         console.error(`Repaired ${repaired} agent config symlink${repaired === 1 ? '' : 's'} to point at ~/.agents/versions/`);
     }
 }
+/**
+ * Repair self-referential agent binary symlinks.
+ *
+ * Some installScript-based agents — notably Factory's `droid`, whose installer
+ * drops a standalone native binary at ~/.local/bin/droid — were registered at
+ * install time by resolving the post-install binary with `which <cli>`. Because
+ * ~/.agents/.cache/shims sits ahead of ~/.local/bin on PATH, `which` could
+ * return OUR OWN dispatcher shim, and the install step symlinked
+ *   ~/.agents/.history/versions/<agent>/<version>/node_modules/.bin/<cli>
+ * back at ~/.agents/.cache/shims/<cli>. Launching that agent then re-execs the
+ * dispatcher forever (an infinite exec loop that hangs the terminal).
+ *
+ * This walks every installed version's node_modules/.bin and, for any entry
+ * whose symlink resolves into the shims dir, re-points it at the real binary
+ * (found on PATH with the shims dir excluded) — or removes it when no real
+ * binary can be found, letting getBinaryPath's per-agent resolver take over.
+ * Idempotent: a correctly-pointed link is left untouched on re-run.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests
+ * can drive a fixture tree without touching the user's ~/.agents.
+ */
+export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_DIR, 'versions'), shimsDir = path.resolve(CACHE_DIR, 'shims')) {
+    // Normalize the shims dir through realpath so the prefix check below survives
+    // a symlinked ~/.agents (or macOS's /tmp -> /private/tmp): fs.realpathSync on
+    // the link target resolves those symlinks, so the dir we compare against must
+    // too, or every loop would read as "points at a real binary" and be skipped.
+    shimsDir = path.resolve(shimsDir);
+    try {
+        shimsDir = fs.realpathSync(shimsDir);
+    }
+    catch {
+        /* shims dir absent — leave the resolved path; nothing will match it */
+    }
+    let agents;
+    try {
+        agents = fs.readdirSync(versionsRoot);
+    }
+    catch {
+        return; // no versions installed yet
+    }
+    let repaired = 0;
+    for (const agent of agents) {
+        const cli = agent in AGENTS ? AGENTS[agent].cliCommand : agent;
+        let versions;
+        try {
+            versions = fs.readdirSync(path.join(versionsRoot, agent));
+        }
+        catch {
+            continue;
+        }
+        for (const version of versions) {
+            const binLink = path.join(versionsRoot, agent, version, 'node_modules', '.bin', cli);
+            let stat;
+            try {
+                stat = fs.lstatSync(binLink);
+            }
+            catch {
+                continue; // no .bin entry for this version
+            }
+            if (!stat.isSymbolicLink())
+                continue;
+            let real;
+            try {
+                real = fs.realpathSync(binLink);
+            }
+            catch {
+                // Dangling symlink — if it was aimed at the shims dir it's the loop
+                // residue; drop it either way so getBinaryPath reports honestly.
+                try {
+                    fs.unlinkSync(binLink);
+                    repaired++;
+                }
+                catch { /* best-effort */ }
+                continue;
+            }
+            if (!path.resolve(real).startsWith(shimsDir + path.sep))
+                continue; // points at a real binary — fine
+            // Self-referential: the link resolves back into our own shims dir.
+            // findInPath does a pure-Node PATH scan (no subprocess) and already
+            // skips our shims dir, so it returns the genuine install if one exists.
+            const realBinary = findInPath(cli);
+            try {
+                fs.unlinkSync(binLink);
+                if (realBinary)
+                    fs.symlinkSync(realBinary, binLink);
+                repaired++;
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    if (repaired > 0) {
+        console.error(`Repaired ${repaired} self-referential agent binary symlink${repaired === 1 ? '' : 's'} (infinite exec-loop fix).`);
+    }
+}
 /**
  * Move a directory from `src` to `dest`. No-op when src is absent. When dest
  * already exists, merge by copying everything that isn't already there, then
@@ -1733,4 +1827,8 @@ export async function runMigration() {
     migrateExtrasExtrasToAgentsExtras();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
+    // Repair self-referential node_modules/.bin/<cli> symlinks (the droid
+    // infinite-exec-loop). Also runs after the bucket moves so it scans the
+    // canonical HISTORY_DIR/versions tree.
+    repairSelfReferentialBinShims();
 }