@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/lib/runner.js

@@ -5,6 +5,13 @@
  * sandboxed or unsandboxed environments, captures stdout to log files,
  * enforces timeouts, and extracts the final assistant report from the
  * agent's stream-JSON output.
+ *
+ * Version/account selection mirrors `agents run`: when a routine does not pin
+ * `version:`, the runner uses the configured run strategy (default `balanced`)
+ * to pick a healthy install, pins the absolute binary via `getBinaryPath`, and
+ * arms same-agent failover across other healthy accounts when a rate/usage
+ * limit is detected mid-run (foreground `executeJob` only — detached daemon
+ * fires once with the pre-flight pick).
  */
 import { spawn } from 'child_process';
 import * as fs from 'fs';
@@ -15,8 +22,10 @@ import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
-import { normalizeMode } from './exec.js';
+import { normalizeMode, buildExecEnv, detectRateLimit, } from './exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
+import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
+import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -161,6 +170,201 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * Resolve the version/account chain for a routine the same way `agents run`
+ * does: honor an explicit `version:` pin; otherwise use the configured run
+ * strategy (default `balanced`) so credit-exhausted / rate-limited accounts
+ * are skipped pre-flight, and synthesize a same-agent failover chain from the
+ * other healthy accounts for mid-run rate limits.
+ *
+ * Workflows are left alone — `agents run <workflow>` owns selection.
+ */
+export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
+    if (config.workflow) {
+        return { chain: [], rotation: null, pinned: false };
+    }
+    const agent = config.agent;
+    if (config.version) {
+        const version = config.version;
+        if (!isVersionInstalled(agent, version)) {
+            process.stderr.write(`[agents] routine ${config.name}: pinned ${agent}@${version} is not installed\n`);
+        }
+        return {
+            chain: [{ agent, version }],
+            rotation: null,
+            pinned: true,
+        };
+    }
+    const strategy = getConfiguredRunStrategy(agent, cwd);
+    let version;
+    let rotation = null;
+    try {
+        const resolved = await resolveRunVersion(agent, strategy, cwd);
+        version = resolved.version ?? undefined;
+        rotation = resolved.rotation;
+        if (rotation) {
+            const label = rotation.picked.email
+                ? `${rotation.picked.email} · ${agent}@${rotation.picked.version}`
+                : `${agent}@${rotation.picked.version}`;
+            const ratio = `${rotation.healthy.length} of ${rotation.healthy.length + rotation.excluded.length} healthy`;
+            process.stderr.write(`[agents] routine ${config.name}: ${strategy} picked ${label} (${ratio})\n`);
+            if (rotation.excluded.length > 0) {
+                const reasons = rotation.excluded
+                    .map((c) => {
+                    const r = readinessFromCandidate(c);
+                    const why = r.ready ? 'deduped' : r.reason;
+                    return `${c.agent}@${c.version}=${why}`;
+                })
+                    .join(', ');
+                process.stderr.write(`[agents] routine ${config.name}: skipped ${reasons}\n`);
+            }
+        }
+        else if (!version) {
+            process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} found no usable ${agent} version; ` +
+                `falling back to default pin\n`);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} skipped: ${err.message}\n`);
+    }
+    if (!version) {
+        version = resolveVersion(agent, cwd) ?? undefined;
+    }
+    if (!version) {
+        process.stderr.write(`[agents] routine ${config.name}: no version of ${agent} configured — ` +
+            `run: agents add ${agent}@<version> && agents use ${agent} <version>\n`);
+        return { chain: [{ agent }], rotation: null, pinned: false };
+    }
+    const failover = rotationFailoverChain(rotation, version);
+    if (failover.length > 0) {
+        const labels = failover.map((f) => `${f.agent}@${f.version}`).join(', ');
+        process.stderr.write(`[agents] routine ${config.name}: credit/rate-limit failover armed → ${labels}\n`);
+    }
+    return {
+        chain: [{ agent, version }, ...failover],
+        rotation,
+        pinned: false,
+    };
+}
+/**
+ * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
+ * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot
+ * surface as "agents: no version of X configured".
+ */
+export function pinJobBinary(cmd, agent, version) {
+    if (!version || cmd.length === 0)
+        return cmd;
+    if (!isVersionInstalled(agent, version))
+        return cmd;
+    const binary = getBinaryPath(agent, version);
+    if (!binary || !fs.existsSync(binary))
+        return cmd;
+    const next = [...cmd];
+    next[0] = binary;
+    return next;
+}
+/**
+ * Merge sandbox/base env with the canonical per-version exec env
+ * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
+ * with `agents run`.
+ */
+export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
+    const execEnv = buildExecEnv({
+        agent,
+        version,
+        mode: 'plan',
+        effort: 'auto',
+        headless: true,
+        env: baseEnv,
+    });
+    const out = {};
+    for (const [k, v] of Object.entries(execEnv)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    if (timezone)
+        out.TZ = timezone;
+    return out;
+}
+/**
+ * Spawn one attempt, capture logs to `attemptLogPath`, enforce timeout.
+ * Rate-limit scanning uses only this attempt's log (not prior failover output).
+ * The attempt log is also appended into `combinedLogPath` for a continuous trail.
+ */
+function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath) {
+    // Isolate this attempt's output so detectRateLimit never sees prior attempts.
+    fs.writeFileSync(attemptLogPath, '', { mode: 0o600 });
+    const stdoutFd = fs.openSync(attemptLogPath, 'a', 0o600);
+    return new Promise((resolve) => {
+        const child = spawn(cmd[0], cmd.slice(1), {
+            stdio: ['ignore', stdoutFd, stdoutFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+            env,
+        });
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                fs.closeSync(stdoutFd);
+            }
+            catch { /* fd already closed */ }
+            let logText = '';
+            try {
+                logText = fs.readFileSync(attemptLogPath, 'utf-8');
+            }
+            catch { /* missing log */ }
+            if (combinedLogPath) {
+                try {
+                    fs.appendFileSync(combinedLogPath, logText);
+                }
+                catch { /* best-effort trail */ }
+            }
+            resolve({ ...result, logText });
+        };
+        const timeoutTimer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* process already exited */ }
+            setTimeout(() => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* process already exited */ }
+            }, 5000);
+            finish({
+                exitCode: null,
+                status: 'timeout',
+                pid: child.pid || null,
+                logText: '',
+            });
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            clearTimeout(timeoutTimer);
+            finish({
+                exitCode: code,
+                status: code === 0 ? 'completed' : 'failed',
+                pid: child.pid || null,
+                logText: '',
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeoutTimer);
+            finish({
+                exitCode: 1,
+                status: 'failed',
+                error: err.message,
+                pid: child.pid || null,
+                logText: '',
+            });
+        });
+        child.unref();
+    });
+}
 /**
  * Execute a job synchronously (waits for completion or timeout before resolving).
  *
@@ -169,12 +373,17 @@ function generateRunId() {
  * workflow `loop:` blocks (issue #400). The optional `deps` parameter provides
  * injectable seams (runIteration, sleep, writeCheckpoint) used by tests; production
  * callers omit it and get the defaults.
+ *
+ * Single-shot path: pre-flight version/account selection + mid-run rate-limit
+ * failover across healthy same-agent accounts (RUSH-1016).
  */
 export async function executeJob(config, deps) {
     maybeRotate();
+    const launch = await resolveRoutineLaunch(config);
+    const primaryVersion = launch.chain[0]?.version ?? config.version;
     const timer = createTimer('agent.run', {
         agent: config.agent,
-        version: config.version,
+        version: primaryVersion,
         jobName: config.name,
         mode: config.mode,
         ...redactPrompt(config.prompt),
@@ -186,10 +395,9 @@ export async function executeJob(config, deps) {
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
-    let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
-    if (config.timezone) {
-        spawnEnv.TZ = config.timezone;
-    }
+    const baseEnv = useSandbox
+        ? buildSpawnEnv(overlayHome)
+        : { ...process.env };
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
@@ -208,9 +416,10 @@ export async function executeJob(config, deps) {
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
+        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone);
         const execOptions = {
             agent: effectiveAgent,
-            version: config.version,
+            version: primaryVersion,
             prompt: resolvedPrompt,
             mode: normalizeMode(config.mode),
             effort: config.effort,
@@ -229,7 +438,7 @@ export async function executeJob(config, deps) {
             runId,
             runDir,
             agent: effectiveAgent,
-            version: config.version,
+            version: primaryVersion,
         }, deps);
         meta.status = loopResult.stoppedBy === 'error' ? 'failed' : 'completed';
         meta.completedAt = new Date().toISOString();
@@ -238,83 +447,105 @@ export async function executeJob(config, deps) {
         timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
         return { meta, reportPath: null };
     }
-    // Single-shot path (no loop): build the command, open a log file, and spawn once.
-    const cmd = buildJobCommand(config, resolvedPrompt);
+    // Single-shot path: build the command once, then walk the launch chain on
+    // rate/usage-limit failures (same detectRateLimit patterns as agents run).
+    const baseCmd = buildJobCommand(config, resolvedPrompt);
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    return new Promise((resolve) => {
-        const child = spawn(cmd[0], cmd.slice(1), {
-            stdio: ['ignore', stdoutFd, stdoutFd],
-            ...backgroundSpawnOptions({ fdStdio: true }),
-            env: spawnEnv,
-        });
-        // Mark startup time (time from function call to process spawn)
-        timer.mark('startup');
-        meta.pid = child.pid || null;
+    // Truncate the log for a clean run; failover attempts append.
+    fs.writeFileSync(stdoutPath, '', { mode: 0o600 });
+    const chain = launch.chain.length > 0
+        ? launch.chain
+        : [{ agent: effectiveAgent, version: primaryVersion }];
+    timer.mark('startup');
+    for (let i = 0; i < chain.length; i++) {
+        const entry = chain[i];
+        const attemptAgent = entry.agent;
+        const attemptVersion = entry.version;
+        const label = attemptVersion ? `${attemptAgent}@${attemptVersion}` : attemptAgent;
+        if (i === 0) {
+            process.stderr.write(`[agents] routine ${config.name}: running ${label}\n`);
+        }
+        const cmd = config.workflow
+            ? baseCmd
+            : pinJobBinary(baseCmd, attemptAgent, attemptVersion);
+        const spawnEnv = config.workflow
+            ? (() => {
+                const e = { ...baseEnv };
+                if (config.timezone)
+                    e.TZ = config.timezone;
+                return e;
+            })()
+            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone);
+        // Remaining timeout budget shared across failover attempts.
+        const elapsed = Date.now() - Date.parse(meta.startedAt);
+        const remaining = Math.max(1_000, timeoutMs - (Number.isFinite(elapsed) ? elapsed : 0));
+        const attemptLogPath = path.join(runDir, `stdout.attempt-${i}.log`);
+        const attempt = await spawnJobAttempt(cmd, spawnEnv, attemptLogPath, remaining, stdoutPath);
+        meta.pid = attempt.pid;
         writeRunMeta(meta);
-        let settled = false;
-        const timeoutTimer = setTimeout(() => {
-            if (settled)
-                return;
-            settled = true;
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* process already exited */ }
-            setTimeout(() => {
-                try {
-                    if (child.pid)
-                        process.kill(-child.pid, 'SIGKILL');
-                }
-                catch { /* process already exited */ }
-            }, 5000);
+        if (attempt.status === 'timeout') {
             meta.status = 'timeout';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
             timer.end({ status: 'timeout', runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
-            resolve({ meta, reportPath });
-        }, timeoutMs);
-        child.on('exit', (code) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeoutTimer);
-            try {
-                fs.closeSync(stdoutFd);
-            }
-            catch { /* fd already closed */ }
-            meta.exitCode = code;
-            meta.status = code === 0 ? 'completed' : 'failed';
+            return { meta, reportPath };
+        }
+        if (attempt.status === 'completed') {
+            meta.exitCode = 0;
+            meta.status = 'completed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
-            timer.end({ status: meta.status, exitCode: code ?? undefined, runId });
+            timer.end({ status: 'completed', exitCode: 0, runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
-            resolve({ meta, reportPath });
-        });
-        child.on('error', (err) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeoutTimer);
-            try {
-                fs.closeSync(stdoutFd);
-            }
-            catch { /* fd already closed */ }
-            meta.status = 'failed';
-            meta.completedAt = new Date().toISOString();
-            writeRunMeta(meta);
-            timer.end({ status: 'failed', error: err.message, runId });
-            resolve({ meta, reportPath: null });
+            return { meta, reportPath };
+        }
+        // Failed — cascade only on rate/usage limit when more chain entries remain.
+        const isLast = i === chain.length - 1;
+        const rateLimited = detectRateLimit(attempt.logText) || (attempt.error ? detectRateLimit(attempt.error) : false);
+        if (!isLast && rateLimited) {
+            const next = chain[i + 1];
+            const nextLabel = next.version ? `${next.agent}@${next.version}` : next.agent;
+            process.stderr.write(`[agents] routine ${config.name}: ${label} failed with credit/rate limit, trying ${nextLabel}\n`);
+            fs.appendFileSync(stdoutPath, `\n[agents] ${label} hit rate/usage limit — failover → ${nextLabel}\n`);
+            continue;
+        }
+        if (attempt.error) {
+            process.stderr.write(`[agents] routine ${config.name}: spawn failed for ${label}: ${attempt.error}\n`);
+        }
+        meta.exitCode = attempt.exitCode ?? 1;
+        meta.status = 'failed';
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+        timer.end({
+            status: 'failed',
+            exitCode: meta.exitCode ?? undefined,
+            runId,
+            ...(attempt.error ? { error: attempt.error } : {}),
         });
-        child.unref();
-    });
+        const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
+        return { meta, reportPath };
+    }
+    // Unreachable: chain is always non-empty, but keep a safe fallback.
+    meta.status = 'failed';
+    meta.exitCode = 1;
+    meta.completedAt = new Date().toISOString();
+    writeRunMeta(meta);
+    timer.end({ status: 'failed', exitCode: 1, runId });
+    return { meta, reportPath: null };
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
+    // Pre-flight: pick a healthy version/account so the daemon does not launch
+    // into a credit-exhausted install. Detached cannot mid-run failover (no exit
+    // wait); the next schedule tick re-selects if this attempt still fails.
+    const launch = await resolveRoutineLaunch(config);
+    const version = launch.chain[0]?.version ?? config.version;
     const resolvedPrompt = resolveJobPrompt(config);
-    const cmd = buildJobCommand(config, resolvedPrompt);
+    let cmd = buildJobCommand(config, resolvedPrompt);
+    if (!config.workflow && version) {
+        cmd = pinJobBinary(cmd, config.agent, version);
+    }
     const useSandbox = config.sandbox !== false;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
     const runId = generateRunId();
@@ -322,10 +553,17 @@ export async function executeJobDetached(config) {
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
     const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
-    if (config.timezone) {
-        spawnEnv.TZ = config.timezone;
-    }
+    const baseEnv = useSandbox
+        ? buildSpawnEnv(overlayHome)
+        : { ...process.env };
+    const spawnEnv = config.workflow
+        ? (() => {
+            const e = { ...baseEnv };
+            if (config.timezone)
+                e.TZ = config.timezone;
+            return e;
+        })()
+        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -343,6 +581,17 @@ export async function executeJobDetached(config) {
         ...backgroundSpawnOptions({ fdStdio: true }),
         env: spawnEnv,
     });
+    child.on('error', (err) => {
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* fd already closed */ }
+        meta.status = 'failed';
+        meta.exitCode = 1;
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+        process.stderr.write(`[agents] daemon: spawn failed for job "${config.name}": ${err.message}\n`);
+    });
     child.unref();
     try {
         fs.closeSync(stdoutFd);

package/dist/lib/sandbox.js

@@ -43,6 +43,12 @@ const ENV_ALLOWLIST = [
     'VISUAL',
     'NO_COLOR',
     'FORCE_COLOR',
+    // Headless Claude auth: the routines daemon injects CLAUDE_CODE_OAUTH_TOKEN
+    // from the `claude` secrets bundle (see daemon.ts). Without this allowlist
+    // entry, sandboxed routine spawns drop the token and look "unconfigured".
+    // Intentionally NOT ANTHROPIC_API_KEY / other provider secrets — those stay
+    // stripped (see tests/sandbox.test.ts "does not include sensitive env vars").
+    'CLAUDE_CODE_OAUTH_TOKEN',
 ];
 /** Tools safe to grant as wildcards (no filesystem access). */
 const SAFE_TOOLS = {

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

@@ -50,6 +50,18 @@ export declare const META_CACHE_PREFIX = "!meta:";
  * cache on every bump and produced a recurring Touch ID storm.
  */
 export declare function shouldSelfHealForUpgrade(persistent: boolean, storeSize: number, runningVersion: string, onDiskVersion: string): boolean;
+/**
+ * Client-side twin of shouldSelfHealForUpgrade: whether ensureAgentRunning may
+ * tear down a reachable broker whose running version differs from the client's
+ * on-disk version. Only while it holds NO real unlocks — tearing down a hot
+ * broker wipes every held bundle, so the next read of each one re-prompts for
+ * Touch ID. On a machine where installed versions churn (dev builds stamp a
+ * fresh 0.0.0-dev.<sha> on every install; an npm copy and a dev copy invoke in
+ * turn), an unguarded teardown produced a rolling Touch ID storm — the exact
+ * failure #435 fixed on the server side. A hot, protocol-compatible broker
+ * keeps serving; its own sweep adopts the new code at the next quiet moment.
+ */
+export declare function shouldTeardownVersionSkewedBroker(realHeldBundles: number): boolean;
 export interface StoredBundle {
     bundle: SecretsBundle;
     env: Record<string, string>;
@@ -172,6 +184,15 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Synchronously evict one bundle from the broker. Called after a mutating
+ * keychain write (add / rotate / remove / rename / delete) so the broker never
+ * keeps serving the pre-write snapshot for up to the ~7d hold — the next read
+ * re-resolves from the keychain (one prompt) and re-caches fresh values.
+ * Best-effort: no broker, no socket, or any failure is a silent no-op.
+ * macOS only.
+ */
+export declare function agentEvictSync(name: string): void;
 /**
  * Read the cached `secrets list` metadata snapshot for the given keychain
  * name-set hash, or null on miss / no broker / off-darwin. Reuses the value

package/dist/lib/secrets/agent.js

@@ -74,6 +74,20 @@ export function shouldSelfHealForUpgrade(persistent, storeSize, runningVersion,
         return false;
     return onDiskVersion !== runningVersion;
 }
+/**
+ * Client-side twin of shouldSelfHealForUpgrade: whether ensureAgentRunning may
+ * tear down a reachable broker whose running version differs from the client's
+ * on-disk version. Only while it holds NO real unlocks — tearing down a hot
+ * broker wipes every held bundle, so the next read of each one re-prompts for
+ * Touch ID. On a machine where installed versions churn (dev builds stamp a
+ * fresh 0.0.0-dev.<sha> on every install; an npm copy and a dev copy invoke in
+ * turn), an unguarded teardown produced a rolling Touch ID storm — the exact
+ * failure #435 fixed on the server side. A hot, protocol-compatible broker
+ * keeps serving; its own sweep adopts the new code at the next quiet moment.
+ */
+export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
+    return realHeldBundles === 0;
+}
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -581,6 +595,50 @@ export function agentGetSync(name) {
         return null;
     }
 }
+/**
+ * Inline node program for the synchronous evict path. Mirrors SYNC_GET_PROGRAM:
+ * writeBundle is synchronous and called synchronously everywhere, so a stale
+ * broker entry must be evicted without awaiting a socket round-trip. Sends one
+ * {cmd:'lock', name} and exits 0 (evicted or nothing held) / 3 (agent down).
+ * argv after -e: [execPath, <socket>, <name>].
+ */
+const SYNC_LOCK_PROGRAM = `
+const net = require('net');
+const sock = process.argv[1], name = process.argv[2];
+const c = net.createConnection(sock);
+let buf = '';
+const down = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
+const timer = setTimeout(down, 2000);
+c.on('error', down);
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'lock', name }) + '\\n'));
+c.setEncoding('utf-8');
+c.on('data', (d) => {
+  buf += d;
+  const nl = buf.indexOf('\\n');
+  if (nl < 0) return;
+  clearTimeout(timer);
+  try { c.destroy(); } catch (e) {}
+  process.exit(0);
+});
+`;
+/**
+ * Synchronously evict one bundle from the broker. Called after a mutating
+ * keychain write (add / rotate / remove / rename / delete) so the broker never
+ * keeps serving the pre-write snapshot for up to the ~7d hold — the next read
+ * re-resolves from the keychain (one prompt) and re-caches fresh values.
+ * Best-effort: no broker, no socket, or any failure is a silent no-op.
+ * macOS only.
+ */
+export function agentEvictSync(name) {
+    if (!onDarwin())
+        return;
+    if (!agentSocketExists())
+        return;
+    try {
+        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name], { timeout: 3000 });
+    }
+    catch { /* best-effort */ }
+}
 // Key inside the cached entry's env that holds the JSON metadata snapshot.
 const META_SNAPSHOT_KEY = '__snapshot__';
 /**
@@ -733,11 +791,15 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     // Self-heal: if a broker is reachable but running pre-upgrade code (its
     // reported version != the version on disk now), tear it down so the paths
     // below bring up a fresh one on current code. A current, reachable broker is
-    // accepted immediately.
+    // accepted immediately — and so is a version-skewed one that still holds
+    // real unlocks (see shouldTeardownVersionSkewedBroker: wiping a hot cache
+    // re-prompts Touch ID for every held bundle).
     const ping = await agentPing();
     if (ping.reachable) {
         if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
             return true;
+        if (!shouldTeardownVersionSkewedBroker((await agentStatus()).length))
+            return true;
         await teardownStaleBroker();
     }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and