@phnx-labs/agents-cli 1.22.29 → 1.22.30

package/dist/lib/device-config.d.ts

@@ -73,6 +73,16 @@ export declare function isSchedulerEnabled(): boolean;
  * scheduler init) refuses with.
  */
 export declare function assertSchedulerEnabled(): void;
+/** True unless this machine's device doc disables the daemon outright (top-level kill switch). */
+export declare function isDaemonEnabled(): boolean;
+/**
+ * Throw when the daemon is disabled on this machine, naming the setting and
+ * the fix. Every AUTO-start surface (routines add/start/catchup/webhook,
+ * `ensureDaemonStarted`) refuses with this before calling `startDaemon()`.
+ * `agents daemon start` is the deliberate override and does NOT call this —
+ * disable only blocks auto-start, mirroring `systemctl disable`.
+ */
+export declare function assertDaemonEnabled(): void;
 /**
  * Read the `agents.max-concurrent` cap for each named device from its synced
  * device doc (no SSH). Devices without a cap are omitted — uncapped is the

package/dist/lib/device-config.js

@@ -67,6 +67,16 @@ export const CONFIG_KEYS = [
         type: 'bool',
         description: 'Whether the routines scheduler (daemon) may fire on this device.',
     },
+    {
+        name: 'daemon.enabled',
+        yamlKey: 'daemonEnabled',
+        scope: 'device',
+        type: 'bool',
+        description: 'Whether the daemon may run on this device at all (secrets broker, browser IPC, watchdog, and the ' +
+            'routines scheduler). Disabling is the top-level kill switch: nothing auto-starts the daemon while it ' +
+            'is set, including `routines add`/`routines start`/`routines catchup`/webhook triggers. ' +
+            '`agents daemon start` still starts it explicitly.',
+    },
     {
         name: 'watchdog.enabled',
         yamlKey: 'watchdogEnabled',
@@ -294,6 +304,23 @@ export function assertSchedulerEnabled() {
     throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
         `Re-enable with: agents devices configure ${machineId()} --scheduler on`);
 }
+/** True unless this machine's device doc disables the daemon outright (top-level kill switch). */
+export function isDaemonEnabled() {
+    return getConfigValue('daemon.enabled').value !== false;
+}
+/**
+ * Throw when the daemon is disabled on this machine, naming the setting and
+ * the fix. Every AUTO-start surface (routines add/start/catchup/webhook,
+ * `ensureDaemonStarted`) refuses with this before calling `startDaemon()`.
+ * `agents daemon start` is the deliberate override and does NOT call this —
+ * disable only blocks auto-start, mirroring `systemctl disable`.
+ */
+export function assertDaemonEnabled() {
+    if (isDaemonEnabled())
+        return;
+    throw new Error(`The daemon is disabled on this device (daemon.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
+        `Re-enable with: agents daemon enable`);
+}
 /**
  * Read the `agents.max-concurrent` cap for each named device from its synced
  * device doc (no SSH). Devices without a cap are omitted — uncapped is the

package/dist/lib/exec.d.ts

@@ -288,6 +288,33 @@ export declare function nativeResume(agent: AgentId, version?: string): boolean;
  * only accept `-c` config overrides.
  */
 export declare function codexWritableRootsConfig(dir: string): string;
+/**
+ * Resolve the executable `buildExecCommand` will put in `cmd[0]`, or null when
+ * that resolution finds nothing on disk.
+ *
+ * This is an EXISTENCE probe, not an "is it managed by us" check. A harness the
+ * user installed themselves (Homebrew, a vendor `curl | sh`, a distro package)
+ * has no version home at all, and running it is a supported state — so with no
+ * version pinned we answer with a PATH lookup of the bare launch command, the
+ * same thing `spawnAgent` would resolve.
+ *
+ * `findInPath` deliberately excludes our own shims dir, because a shim is a
+ * dispatcher rather than an install. That exclusion alone is too strong here:
+ * the shim DOES launch whenever agents-cli owns at least one version of the
+ * agent — it resolves the version itself, and when no default is pinned it
+ * prints its own accurate `no default set … agents use <agent> <version>`
+ * guidance. Pre-empting that with "not installed" would name the wrong fix
+ * (`agents add`) for a machine that already has the harness. So the shim counts
+ * only when a managed version exists; with zero managed versions it is the dead
+ * end this probe was written to catch (RUSH-2339).
+ *
+ * The version-pinned branch mirrors buildExecCommand exactly: versioned shim
+ * first, then the version home's real binary. It deliberately does NOT fall back
+ * to PATH — with a version pinned, buildExecCommand spawns the literal
+ * `<cli>@<version>`, which is not on PATH, so a PATH hit here would be a lie
+ * that still exits 127.
+ */
+export declare function resolveLaunchBinary(agent: AgentId, version?: string): string | null;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/exec.js

@@ -9,9 +9,9 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_MODES } from './types.js';
-import { AGENTS } from './agents.js';
+import { AGENTS, findInPath } from './agents.js';
 import { parseTimeout } from './routines.js';
-import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
+import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, listInstalledVersions, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { isTierToken, resolveTier } from './model-tiers.js';
 import { createTimer, redactPrompt, redactArgs } from './events.js';
@@ -725,6 +725,53 @@ export function nativeResume(agent, version) {
 export function codexWritableRootsConfig(dir) {
     return `sandbox_workspace_write.writable_roots=[${JSON.stringify(dir)}]`;
 }
+/**
+ * Resolve the executable `buildExecCommand` will put in `cmd[0]`, or null when
+ * that resolution finds nothing on disk.
+ *
+ * This is an EXISTENCE probe, not an "is it managed by us" check. A harness the
+ * user installed themselves (Homebrew, a vendor `curl | sh`, a distro package)
+ * has no version home at all, and running it is a supported state — so with no
+ * version pinned we answer with a PATH lookup of the bare launch command, the
+ * same thing `spawnAgent` would resolve.
+ *
+ * `findInPath` deliberately excludes our own shims dir, because a shim is a
+ * dispatcher rather than an install. That exclusion alone is too strong here:
+ * the shim DOES launch whenever agents-cli owns at least one version of the
+ * agent — it resolves the version itself, and when no default is pinned it
+ * prints its own accurate `no default set … agents use <agent> <version>`
+ * guidance. Pre-empting that with "not installed" would name the wrong fix
+ * (`agents add`) for a machine that already has the harness. So the shim counts
+ * only when a managed version exists; with zero managed versions it is the dead
+ * end this probe was written to catch (RUSH-2339).
+ *
+ * The version-pinned branch mirrors buildExecCommand exactly: versioned shim
+ * first, then the version home's real binary. It deliberately does NOT fall back
+ * to PATH — with a version pinned, buildExecCommand spawns the literal
+ * `<cli>@<version>`, which is not on PATH, so a PATH hit here would be a lie
+ * that still exits 127.
+ */
+export function resolveLaunchBinary(agent, version) {
+    const command = AGENT_COMMANDS[agent].base[0];
+    if (version) {
+        const versionedShim = path.join(getShimsDir(), `${command}@${version}`);
+        if (process.platform === 'win32' && fs.existsSync(versionedShim + '.cmd')) {
+            return versionedShim + '.cmd';
+        }
+        if (fs.existsSync(versionedShim))
+            return versionedShim;
+        const binary = getBinaryPath(agent, version);
+        return binary && fs.existsSync(binary) ? binary : null;
+    }
+    const native = findInPath(command);
+    if (native)
+        return native;
+    if (listInstalledVersions(agent).length === 0)
+        return null;
+    // Re-scan PATH accepting the shim: point findInPath's exclusion at a path that
+    // matches nothing, so the real shims dir participates like any other PATH entry.
+    return findInPath(command, { shimsDir: path.join(getShimsDir(), '.no-such-dir') });
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];

package/dist/lib/hosts/dispatch.d.ts

@@ -118,6 +118,8 @@ export interface DispatchOptions {
     version?: string;
     /** Run strategy (e.g. "balanced") — the remote picks among ITS signed-in accounts. */
     strategy?: string;
+    /** Named provider account — the remote resolves it against ITS signed-in versions. */
+    account?: string;
     balanced?: boolean;
     fallback?: string;
     mode?: string;
@@ -193,6 +195,8 @@ export interface InteractiveDispatchOptions {
     version?: string;
     /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
     strategy?: string;
+    /** Named provider account to resolve on the remote host. */
+    account?: string;
     /** Optional prompt — forwarded only when the caller explicitly forced interactive mode. */
     prompt?: string;
     mode?: string;

package/dist/lib/hosts/dispatch.js

@@ -401,6 +401,8 @@ export function buildRunForwardedArgs(opts) {
         args.push('--timeout', opts.timeout);
     if (opts.strategy)
         args.push('--strategy', opts.strategy);
+    if (opts.account)
+        args.push('--account', opts.account);
     if (opts.balanced)
         args.push('--balanced');
     if (opts.fallback)
@@ -466,6 +468,8 @@ export function buildInteractiveRunForwardedArgs(opts) {
         args.push('--timeout', opts.timeout);
     if (opts.strategy)
         args.push('--strategy', opts.strategy);
+    if (opts.account)
+        args.push('--account', opts.account);
     if (opts.balanced)
         args.push('--balanced');
     if (opts.fallback)

package/dist/lib/hosts/remote-cmd.js

@@ -76,6 +76,7 @@ export const RUN_OPTION_FORWARDING = {
     fallback: 'forward',
     balanced: 'forward',
     strategy: 'forward',
+    account: 'forward',
     loop: 'forward',
     maxIterations: 'forward',
     budget: 'forward',

package/dist/lib/hosts/run-target.d.ts

@@ -62,6 +62,7 @@ export interface HostPromptRun {
     addDir?: string[];
     timeout?: string;
     strategy?: string;
+    account?: string;
     balanced?: boolean;
     fallback?: string;
     loop?: boolean;

package/dist/lib/hosts/run-target.js

@@ -109,6 +109,7 @@ export async function dispatchPromptToHost(host, opts) {
         addDir: opts.addDir,
         timeout: opts.timeout,
         strategy: opts.strategy,
+        account: opts.account,
         balanced: opts.balanced,
         fallback: opts.fallback,
         loop: opts.loop,

package/dist/lib/import.js

@@ -19,7 +19,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { AGENTS } from './agents.js';
+import { AGENTS, resolveNativeBinaryPath } from './agents.js';
 import { getUserAgentsDir, getVersionsDir } from './state.js';
 import { setGlobalDefault } from './versions.js';
 import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks, assertIsolationBoundary } from './shims.js';
@@ -200,15 +200,16 @@ export function importInstallScriptBinary(spec, version, binaryPath, versionDir)
     if (alreadyExists) {
         return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: binaryPath };
     }
-    if (!fs.existsSync(binaryPath)) {
-        return { success: false, error: `Binary does not exist: ${binaryPath}` };
+    const nativeBinary = resolveNativeBinaryPath(spec.cliCommand, binaryPath);
+    if (!nativeBinary) {
+        return { success: false, error: `Binary does not resolve to a native executable: ${binaryPath}` };
     }
     try {
         fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
         fs.mkdirSync(path.join(versionDir, 'node_modules', '.bin'), { recursive: true });
-        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify({ name: `agents-${spec.agentId}-${version}`, version: '1.0.0', private: true, imported: true, from: binaryPath, installScriptBased: true }, null, 2));
-        fs.symlinkSync(binaryPath, binaryLink);
-        return { success: true, resolvedFromPath: binaryPath };
+        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify({ name: `agents-${spec.agentId}-${version}`, version: '1.0.0', private: true, imported: true, from: nativeBinary, installScriptBased: true }, null, 2));
+        fs.symlinkSync(nativeBinary, binaryLink);
+        return { success: true, resolvedFromPath: nativeBinary };
     }
     catch (err) {
         return { success: false, error: err.message };

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

@@ -0,0 +1,19 @@
+import { LRUCache } from 'lru-cache';
+export interface MemoryCacheOptions<K extends {} = string, V extends {} = {}> {
+    /** Hard entry bound. A cache without a bound is not allowed. */
+    max: number;
+    /** Milliseconds before an entry is treated as absent. */
+    ttlMs: number;
+    /** Optional async loader. Concurrent fetches for one key are coalesced. */
+    fetchMethod?: (key: K, staleValue: V | undefined) => Promise<V>;
+    /** Injectable monotonic clock for deterministic TTL tests. */
+    now?: () => number;
+}
+/**
+ * Correctness-first process-local cache defaults.
+ *
+ * The cache is always bounded, never returns stale values, and does not extend
+ * an entry's life merely because it was read. Durable/cross-process state must
+ * continue to live in SQLite or an atomic on-disk snapshot.
+ */
+export declare function createMemoryCache<K extends {}, V extends {}>(options: MemoryCacheOptions<K, V>): LRUCache<K, V>;

package/dist/lib/memory-cache.js

@@ -0,0 +1,31 @@
+import { LRUCache } from 'lru-cache';
+/**
+ * Correctness-first process-local cache defaults.
+ *
+ * The cache is always bounded, never returns stale values, and does not extend
+ * an entry's life merely because it was read. Durable/cross-process state must
+ * continue to live in SQLite or an atomic on-disk snapshot.
+ */
+export function createMemoryCache(options) {
+    if (!Number.isSafeInteger(options.max) || options.max < 1) {
+        throw new Error('memory cache max must be a positive integer');
+    }
+    if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+        throw new Error('memory cache ttlMs must be positive');
+    }
+    return new LRUCache({
+        max: options.max,
+        ttl: options.ttlMs,
+        allowStale: false,
+        updateAgeOnGet: false,
+        updateAgeOnHas: false,
+        ttlAutopurge: false,
+        // A supplied deterministic clock must be read on every operation; the
+        // library's 1ms cached-now optimization follows wall time, not that clock.
+        ttlResolution: options.now ? 0 : 1,
+        fetchMethod: options.fetchMethod
+            ? async (key, staleValue) => options.fetchMethod(key, staleValue)
+            : undefined,
+        perf: options.now ? { now: options.now } : undefined,
+    });
+}

package/dist/lib/migrate.d.ts

@@ -77,7 +77,7 @@ export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): vo
  * 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;
+export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string, historyDir?: 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

@@ -14,6 +14,8 @@ import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
 import { migrateLegacyRoutineActivation, setJobEnabled } from './routines.js';
+import { addEnabledRoutinesOnUpgrade } from './routine-activation.js';
+import { DAEMON_TICK_ROUTINE_NAMES } from './daemon-ticks.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -825,7 +827,7 @@ function repairAgentConfigSymlinks() {
  * 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')) {
+export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_DIR, 'versions'), shimsDir = path.resolve(CACHE_DIR, 'shims'), historyDir = path.dirname(versionsRoot)) {
     // 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
@@ -884,7 +886,7 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
             // 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);
+            const realBinary = findInPath(cli, { shimsDir, historyDir });
             try {
                 fs.unlinkSync(binLink);
                 // createLink: a real symlink where the OS allows it (POSIX, and Windows
@@ -2205,6 +2207,9 @@ export async function runMigration() {
     // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
     migrateRoutineDeviceToDevices();
     migrateLegacyRoutineActivation();
+    // These routines replace daemon timers that were always active. Devices with
+    // an existing activation manifest must retain that behavior after upgrade.
+    addEnabledRoutinesOnUpgrade(DAEMON_TICK_ROUTINE_NAMES);
     // Fold the legacy watchdog enable sentinel into the watchdog routine so a user
     // who opted in under the old build stays opted in after upgrading. After the
     // routine rewrites above so the routines dir is in its canonical shape.

package/dist/lib/routine-activation.d.ts

@@ -3,6 +3,8 @@ export declare function normalizeRoutineNames(names: Iterable<string>): string[]
 export declare function enabledRoutineNames(): string[] | null;
 export declare function routineEnabledOnThisDevice(name: string): boolean | null;
 export declare function replaceEnabledRoutines(names: Iterable<string>): string[];
+/** Add newly introduced replacements to an already-materialized device manifest. */
+export declare function addEnabledRoutinesOnUpgrade(names: Iterable<string>): boolean;
 /**
  * Add or remove one routine on this machine. `legacyEnabledNames` seeds the
  * manifest the first time an upgraded host changes activation, preserving every

package/dist/lib/routine-activation.js

@@ -26,6 +26,22 @@ export function replaceEnabledRoutines(names) {
     updateMeta((meta) => ({ ...meta, deviceRoutines: normalized }));
     return normalized;
 }
+/** Add newly introduced replacements to an already-materialized device manifest. */
+export function addEnabledRoutinesOnUpgrade(names) {
+    const additions = normalizeRoutineNames(names);
+    let changed = false;
+    updateMeta((meta) => {
+        if (!Array.isArray(meta.deviceRoutines))
+            return meta;
+        const current = normalizeRoutineNames(meta.deviceRoutines);
+        const next = normalizeRoutineNames([...current, ...additions]);
+        if (next.length === current.length && next.every((name, index) => name === current[index]))
+            return meta;
+        changed = true;
+        return { ...meta, deviceRoutines: next };
+    });
+    return changed;
+}
 /**
  * Add or remove one routine on this machine. `legacyEnabledNames` seeds the
  * manifest the first time an upgraded host changes activation, preserving every

package/dist/lib/runner.d.ts

@@ -59,6 +59,13 @@ export interface RoutineLaunchPlan {
  */
 export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string, deps?: {
     resolveRunVersion?: typeof resolveRunVersion;
+    readAccountLabels?: () => {
+        labels: Record<string, {
+            agent: AgentId;
+            fingerprint: string;
+        }>;
+    };
+    resolveAccountLabel?: (agent: AgentId, label: string) => Promise<string>;
 }): Promise<RoutineLaunchPlan>;
 /**
  * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
@@ -105,5 +112,16 @@ export declare function inferFinalStatusFromLog(stdoutPath: string, agent: Agent
     status: 'completed' | 'failed';
     exitCode: number;
 } | null;
+/**
+ * PIDs of the in-flight detached routine children on THIS device — every local
+ * run record still marked `running` whose spawned process is genuinely alive
+ * (`isPidOurs`, so a dead-and-reused pid does not count). These are the `unref`'d
+ * spawns that survive a daemon exit in their own process group (SING-11a): a
+ * takeover must not kill them and `stopDaemon` reports them rather than pretending
+ * the process tree is clean (SING-12). Scoped to `getRunsDir()`, which is under
+ * this state dir's HOME, so a different state dir's children are invisible here.
+ * `host:`-placed runs have no local pid and are excluded.
+ */
+export declare function listLiveRoutineChildren(): number[];
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;

package/dist/lib/runner.js

@@ -513,6 +513,11 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
     // credential (RUSH-1957). Falls through to the strategy only when the account
     // is not signed in on this box, with a loud warning rather than a silent stall.
     if (config.account) {
+        const { readAccountLabels, resolveAccountLabel } = await import('./account-labels.js');
+        if ((deps.readAccountLabels ?? readAccountLabels)().labels[config.account]) {
+            const version = await (deps.resolveAccountLabel ?? resolveAccountLabel)(agent, config.account);
+            return { chain: [{ agent, version }], rotation: null, pinned: true };
+        }
         const version = await resolveAccountVersion(agent, config.account);
         if (version) {
             return { chain: [{ agent, version }], rotation: null, pinned: true };
@@ -1720,6 +1725,53 @@ function finalizeHostRun(meta) {
     }
     catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
 }
+/**
+ * PIDs of the in-flight detached routine children on THIS device — every local
+ * run record still marked `running` whose spawned process is genuinely alive
+ * (`isPidOurs`, so a dead-and-reused pid does not count). These are the `unref`'d
+ * spawns that survive a daemon exit in their own process group (SING-11a): a
+ * takeover must not kill them and `stopDaemon` reports them rather than pretending
+ * the process tree is clean (SING-12). Scoped to `getRunsDir()`, which is under
+ * this state dir's HOME, so a different state dir's children are invisible here.
+ * `host:`-placed runs have no local pid and are excluded.
+ */
+export function listLiveRoutineChildren() {
+    const runsDir = getRunsDir();
+    if (!fs.existsSync(runsDir))
+        return [];
+    const pids = [];
+    let jobDirs;
+    try {
+        jobDirs = fs.readdirSync(runsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    }
+    catch {
+        return pids;
+    }
+    for (const jobDir of jobDirs) {
+        const jobRunsPath = path.join(runsDir, jobDir.name);
+        let runDirs;
+        try {
+            runDirs = fs.readdirSync(jobRunsPath, { withFileTypes: true }).filter((e) => e.isDirectory());
+        }
+        catch {
+            continue;
+        }
+        for (const runDirEntry of runDirs) {
+            const metaPath = path.join(jobRunsPath, runDirEntry.name, 'meta.json');
+            if (!fs.existsSync(metaPath))
+                continue;
+            try {
+                const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+                if (meta.status !== 'running' || meta.hostTaskId || !meta.pid)
+                    continue;
+                if (isPidOurs(meta.pid, meta.spawnedAt))
+                    pids.push(meta.pid);
+            }
+            catch { /* unreadable/partial record — skip */ }
+        }
+    }
+    return pids;
+}
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();

package/dist/lib/secrets/agent.d.ts

@@ -67,6 +67,23 @@ export declare function shouldSelfHealForUpgrade(persistent: boolean, storeSize:
  * keeps serving; its own sweep adopts the new code at the next quiet moment.
  */
 export declare function shouldTeardownVersionSkewedBroker(realHeldBundles: number): boolean;
+/**
+ * Whether a version-skewed client may evict the reachable broker at all. The
+ * held-bundle gate above is necessary but not sufficient: a broker the always-on
+ * daemon is hosting must NEVER be client-evicted, even when it holds zero
+ * unlocks. teardownStaleBroker() recognizes only the standalone broker's
+ * pidPath() O_EXCL claim (the daemon writes ownerPath(), never pidPath()), so
+ * evicting a daemon-hosted broker unlinks its socket WITHOUT stopping the daemon;
+ * the daemon then keeps hostedBroker != null and shouldTakeOverBroker() refuses
+ * to re-host, orphaning its broker until the daemon restarts while every reader
+ * falls onto cold one-off brokers that re-prompt Touch ID — the storm. Deferring
+ * is safe: daemon code-version upgrades are handled by postinstall.js restarting
+ * it, and agentPing() already gated on PROTOCOL_VERSION, so a code-skewed daemon
+ * broker is still wire-compatible. Only when NO daemon owns the broker (churning
+ * dev installs with a dead/absent daemon — the case #435's client twin was built
+ * for) does the zero-held-bundles teardown apply, exactly as before.
+ */
+export declare function shouldClientEvictSkewedBroker(daemonRunning: boolean, realHeldBundles: number): boolean;
 export interface StoredBundle {
     bundle: SecretsBundle;
     env: Record<string, string>;
@@ -84,6 +101,8 @@ export interface AgentStatusEntry {
     leaseId?: string;
     keys?: string[];
 }
+/** Public accessor for the broker's socket path — `agents daemon status`/`services` reads it for display. */
+export declare function secretsBrokerSocketPath(): string;
 /**
  * Read the current broker capability token, or null if none is present. Clients
  * read it fresh per request and attach it to every non-ping command; a broker

package/dist/lib/secrets/agent.js

@@ -142,6 +142,27 @@ export function shouldSelfHealForUpgrade(persistent, storeSize, runningVersion,
 export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
     return realHeldBundles === 0;
 }
+/**
+ * Whether a version-skewed client may evict the reachable broker at all. The
+ * held-bundle gate above is necessary but not sufficient: a broker the always-on
+ * daemon is hosting must NEVER be client-evicted, even when it holds zero
+ * unlocks. teardownStaleBroker() recognizes only the standalone broker's
+ * pidPath() O_EXCL claim (the daemon writes ownerPath(), never pidPath()), so
+ * evicting a daemon-hosted broker unlinks its socket WITHOUT stopping the daemon;
+ * the daemon then keeps hostedBroker != null and shouldTakeOverBroker() refuses
+ * to re-host, orphaning its broker until the daemon restarts while every reader
+ * falls onto cold one-off brokers that re-prompt Touch ID — the storm. Deferring
+ * is safe: daemon code-version upgrades are handled by postinstall.js restarting
+ * it, and agentPing() already gated on PROTOCOL_VERSION, so a code-skewed daemon
+ * broker is still wire-compatible. Only when NO daemon owns the broker (churning
+ * dev installs with a dead/absent daemon — the case #435's client twin was built
+ * for) does the zero-held-bundles teardown apply, exactly as before.
+ */
+export function shouldClientEvictSkewedBroker(daemonRunning, realHeldBundles) {
+    if (daemonRunning)
+        return false;
+    return shouldTeardownVersionSkewedBroker(realHeldBundles);
+}
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -175,6 +196,10 @@ function agentDir() {
 function socketPath() {
     return path.join(agentDir(), 'agent.sock');
 }
+/** Public accessor for the broker's socket path — `agents daemon status`/`services` reads it for display. */
+export function secretsBrokerSocketPath() {
+    return socketPath();
+}
 function pidPath() {
     return path.join(agentDir(), 'agent.pid');
 }
@@ -345,7 +370,7 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             // the broker is running pre-upgrade code and should be restarted.
             return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION, cliVersion: getCliVersion() };
         case 'get': {
-            // Walk own-harness → global so a `--for` grant wins over a global one and
+            // Walk own-harness → global so an `--agent` grant wins over a global one and
             // an unscoped unlock serves every harness (bundleScopeChain).
             for (const scope of bundleScopeChain(req.harness)) {
                 const key = scopedBundleKey(req.name, scope);
@@ -1334,7 +1359,12 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     if (ping.reachable) {
         if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
             return true;
-        if (!shouldTeardownVersionSkewedBroker((await agentStatus()).length))
+        // A reachable but version-skewed broker: tear it down ONLY when no daemon
+        // hosts it and it holds no unlocks. Evicting a daemon-hosted broker orphans
+        // the daemon's socket and starts the Touch ID storm — see
+        // shouldClientEvictSkewedBroker.
+        const { isDaemonRunning } = await import('../daemon.js');
+        if (!shouldClientEvictSkewedBroker(isDaemonRunning(), (await agentStatus()).length))
             return true;
         await teardownStaleBroker();
     }

package/dist/lib/secrets/scope.d.ts

@@ -4,7 +4,7 @@
  * (bundles.ts).
  *
  * A grant is stored under a scope and read under a scope; the two must agree or
- * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * the bundle is invisible. `agents secrets unlock --agent <agent>` exists to NARROW
  * a grant to one harness, so an unlock without it is global by definition.
  *
  * This module deliberately has NO imports: agent.ts and session-store.ts already
@@ -13,14 +13,14 @@
  * and throw at runtime even though tsc is happy.
  */
 /**
- * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * Scope of an unlock that was not narrowed with `--agent`: readable by every
  * harness. Not a valid harness name, so it can never collide with one.
  */
 export declare const GLOBAL_HARNESS = "*";
 /**
  * Scopes a reader consults, most specific first: its own harness, then the global
  * grant. This is the resolution order of the scoped-grant model — a narrow
- * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * `--agent claude` unlock stays claude-only while an unscoped unlock serves
  * everyone — not a fallback papering over a miss.
  */
 export declare function bundleScopeChain(harness: string | undefined): string[];

package/dist/lib/secrets/scope.js

@@ -4,7 +4,7 @@
  * (bundles.ts).
  *
  * A grant is stored under a scope and read under a scope; the two must agree or
- * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * the bundle is invisible. `agents secrets unlock --agent <agent>` exists to NARROW
  * a grant to one harness, so an unlock without it is global by definition.
  *
  * This module deliberately has NO imports: agent.ts and session-store.ts already
@@ -13,14 +13,14 @@
  * and throw at runtime even though tsc is happy.
  */
 /**
- * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * Scope of an unlock that was not narrowed with `--agent`: readable by every
  * harness. Not a valid harness name, so it can never collide with one.
  */
 export const GLOBAL_HARNESS = '*';
 /**
  * Scopes a reader consults, most specific first: its own harness, then the global
  * grant. This is the resolution order of the scoped-grant model — a narrow
- * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * `--agent claude` unlock stays claude-only while an unscoped unlock serves
  * everyone — not a fallback papering over a miss.
  */
 export function bundleScopeChain(harness) {