@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/runner.js

@@ -22,13 +22,16 @@ import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
-import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, } from './exec.js';
+import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, } from './exec.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
 import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { walkForFiles } from './fs-walk.js';
-import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
-import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
+import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
+import { claudeHomeHasOwnCredential } from './agents.js';
+import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
+import { readAuthHealth, isDeadVerdict } from './auth-health.js';
+import { machineId } from './machine-id.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'],
@@ -287,6 +290,19 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
             pinned: true,
         };
     }
+    // Account pin: resolve the login identity to the version slot that holds it and
+    // run pinned — no rotation, no failover onto other accounts — so concurrent
+    // unattended routines never share (and mutually revoke) one single-use OAuth
+    // 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 version = await resolveAccountVersion(agent, config.account);
+        if (version) {
+            return { chain: [{ agent, version }], rotation: null, pinned: true };
+        }
+        process.stderr.write(`[agents] routine ${config.name}: account '${config.account}' is not signed in for ${agent}; ` +
+            `falling back to strategy — pin a signed-in account to stop OAuth-rotation revocation\n`);
+    }
     const strategy = getConfiguredRunStrategy(agent, cwd);
     let version;
     let rotation = null;
@@ -383,6 +399,19 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
         if (v !== undefined)
             out[k] = v;
     }
+    // RUSH-1979: the daemon injects one ambient CLAUDE_CODE_OAUTH_TOKEN (RUSH-1759)
+    // so a token-less default account still authenticates. When balanced rotation
+    // pins THIS spawn to a specific account's CLAUDE_CONFIG_DIR that holds its own
+    // credential, that ambient token would shadow the account (Claude and the Linux
+    // shim both prefer the env var) — making the pool inert and 401ing on the one
+    // stale token. Drop it here so the pinned account authenticates itself; keep it
+    // when the account has no on-disk credential (the RUSH-1759 default).
+    if (agent === 'claude' &&
+        version &&
+        out.CLAUDE_CONFIG_DIR &&
+        claudeHomeHasOwnCredential(getVersionHomePath('claude', version))) {
+        delete out.CLAUDE_CODE_OAUTH_TOKEN;
+    }
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -536,6 +565,25 @@ export async function executeJob(config, deps) {
         exitCode: null,
     };
     writeRunMeta(meta);
+    // Auth preflight: if the last live probe rejected this (agent, version)'s
+    // token (verdict `revoked`), the run is guaranteed to fail auth — fail fast
+    // before spawning instead of producing a doomed run + poisoned report. Cache-
+    // only (the daemon refreshes it periodically); fail OPEN on any non-revoked or
+    // missing verdict so a stale/absent probe or a network blip never blocks a
+    // run, and agents with no live probe (codex/gemini/grok) are never blocked.
+    const preflightVersion = launch.chain[0]?.version;
+    if (preflightVersion) {
+        const health = readAuthHealth(machineId(), effectiveAgent, preflightVersion);
+        if (health && isDeadVerdict(health.verdict)) {
+            const reason = `auth_preflight: ${health.verdict}`;
+            process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} token ${health.verdict} — skipping run (re-login required)\n`);
+            finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
+            writeRunMeta(meta);
+            timer.end({ status: 'failed', exitCode: 1, runId, error: reason });
+            archiveRoutineTranscripts(meta, runDir, overlayHome);
+            return { meta, reportPath: null };
+        }
+    }
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
@@ -616,6 +664,21 @@ export async function executeJob(config, deps) {
             return { meta, reportPath };
         }
         if (attempt.status === 'completed') {
+            // Exit code alone is unreliable for auth: a logged-out Claude can exit 0
+            // with a `result` event carrying is_error:true (terminal_reason
+            // "completed"). Consult the SAME structural signal the detached path uses
+            // so both paths agree — raw text is deliberately NOT used here, so a
+            // genuinely-completed run that merely mentions an auth phrase stays a
+            // success (processFailed:false).
+            if (isAuthFailureFromLog(attempt.logText, effectiveAgent, { processFailed: false })) {
+                const reason = authFailureReason(attempt.logText) ?? 'authentication_failed';
+                finalizeRunMeta(meta, 'failed', attempt.exitCode ?? 1, { errorMessage: `auth_failed: ${reason}` });
+                writeRunMeta(meta);
+                timer.end({ status: 'failed', exitCode: meta.exitCode ?? undefined, runId, error: `auth_failed: ${reason}` });
+                // Never persist the login-error text as the report.
+                archiveRoutineTranscripts(meta, runDir, overlayHome);
+                return { meta, reportPath: null };
+            }
             finalizeRunMeta(meta, 'completed', 0);
             writeRunMeta(meta);
             timer.end({ status: 'completed', exitCode: 0, runId });
@@ -633,18 +696,36 @@ export async function executeJob(config, deps) {
             fs.appendFileSync(stdoutPath, `\n[agents] ${label} hit rate/usage limit — failover → ${nextLabel}\n`);
             continue;
         }
+        // Auth failure — the agent is logged out / token revoked. Unlike a rate
+        // limit it is not self-healing by failover (every chain entry on the same
+        // account fails identically), so rate-limit is classified first (above) and
+        // auth only when NOT rate-limited. Classified so the failure is visible and,
+        // critically, so the login-error text is never persisted as the report.
+        const authFailed = !rateLimited && (isAuthFailureFromLog(attempt.logText, effectiveAgent, { processFailed: true }) ||
+            (attempt.error ? detectAuthFailure(attempt.error) : false));
         if (attempt.error) {
             process.stderr.write(`[agents] routine ${config.name}: spawn failed for ${label}: ${attempt.error}\n`);
         }
-        finalizeRunMeta(meta, 'failed', attempt.exitCode ?? 1, attempt.error ? { errorMessage: attempt.error } : undefined);
+        const authReason = authFailed
+            ? (authFailureReason(attempt.logText)
+                ?? (attempt.error ? authFailureReason(attempt.error) : null)
+                ?? 'authentication_failed')
+            : null;
+        const failureErrorMessage = authReason
+            ? `auth_failed: ${authReason}`
+            : (attempt.error ?? undefined);
+        finalizeRunMeta(meta, 'failed', attempt.exitCode ?? 1, failureErrorMessage ? { errorMessage: failureErrorMessage } : undefined);
         writeRunMeta(meta);
         timer.end({
             status: 'failed',
             exitCode: meta.exitCode ?? undefined,
             runId,
-            ...(attempt.error ? { error: attempt.error } : {}),
+            ...(failureErrorMessage ? { error: failureErrorMessage } : {}),
         });
-        const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
+        // On auth failure the last assistant text IS the login error — never persist
+        // it as report.md; it would otherwise be injected into the next run's prompt
+        // via {last_report}.
+        const reportPath = authFailed ? null : extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
         return { meta, reportPath };
     }
@@ -876,10 +957,26 @@ export async function executeJobDetached(config) {
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
-        if (status !== 'timeout')
+        // Never persist the report on an auth failure — the last assistant text is
+        // the login error, which would poison the next run's {last_report} prompt.
+        const isAuthFailure = !!errorMessage && errorMessage.startsWith('auth_failed:');
+        if (status !== 'timeout' && !isAuthFailure)
             extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
     };
     child.on('exit', (code) => {
+        let logText = '';
+        try {
+            logText = fs.readFileSync(stdoutPath, 'utf-8');
+        }
+        catch { /* log unreadable */ }
+        // processFailed gates the raw-text fallback so a COMPLETED run (exit 0) that
+        // merely mentions an auth phrase is never misclassified; the structural
+        // marker still catches an exit-0 auth failure on its own.
+        if (isAuthFailureFromLog(logText, effectiveAgent, { processFailed: (code ?? 1) !== 0 })) {
+            const reason = authFailureReason(logText) ?? 'authentication_failed';
+            settle('failed', code ?? 1, `auth_failed: ${reason}`);
+            return;
+        }
         const inferred = inferFinalStatusFromLog(stdoutPath, effectiveAgent);
         if (inferred) {
             settle(inferred.status, inferred.exitCode);

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

@@ -40,6 +40,7 @@ export declare const DEFAULT_TTL_MS: number;
  * spawnSync argv (unlike a NUL byte); `status` hides these entries.
  */
 export declare const META_CACHE_PREFIX = "!meta:";
+export { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /**
  * Decide whether a persistent broker should self-heal onto freshly-installed
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
@@ -232,6 +233,38 @@ export declare function startHostedBroker(): Promise<{
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
+/**
+ * Spawn one of the `__secrets-*` sync clients and return its result.
+ *
+ * These three call sites used to hand-roll `spawnSync(process.execPath, ['-e',
+ * <inline node program>, …])`. That is correct only for a JS install, where
+ * `process.execPath` is `node`. Since 1.20.53 the shipped macOS `agents` is a
+ * **bun-compiled Mach-O**, where `process.execPath` is the CLI binary itself —
+ * so the spawn became `agents -e <program> …`, which commander rejects with
+ * `error: unknown option '-e'` and a non-zero exit. Every sync client then took
+ * its own failure path (`agentGetSync` → null, `agentReachableSync` → false,
+ * `agentEvictSync` → no-op), which reads as "broker down" and falls through to
+ * a real keychain read. Net effect on the standalone binary: the broker cache
+ * was never hit, so the `daily` policy's one-prompt-per-7d never applied and
+ * every bundle read re-popped Touch ID.
+ *
+ * Same defect class as the broker-launch bug fixed in 1.20.56 (see cliSpawn's
+ * doc comment); these three sites were simply never converted. Routing them
+ * through `getCliLaunch` fixes both install shapes at once and keeps a single
+ * code path.
+ *
+ * The subcommands are top-level `__secrets-*` tokens intercepted in index.ts
+ * BEFORE commander and before the CLI's startup work, exactly like
+ * `__daemon-run` and `__vault-age-helper`. That is load-bearing, not cosmetic:
+ * a normal command path runs `checkForUpdates()` and `spawnDetachedSync()` on
+ * every invocation (index.ts), so registering these as ordinary hidden
+ * subcommands would fire an update check and spawn a detached background sync
+ * on every cache hit — turning the hot read path into a process fork storm.
+ */
+export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
+    command: string;
+    args: string[];
+};
 /**
  * Synchronous read for the hot path. Returns the cached resolved bundle, or
  * null if the agent isn't running / doesn't hold this bundle / anything fails
@@ -241,6 +274,20 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Last non-empty line of a child's stdout — the payload line.
+ *
+ * The inline `node -e` client this replaced was a bare node process that could
+ * only ever emit its own JSON. The replacement boots the real CLI, so anything
+ * the CLI prints on the way up shares that stream. Today the known chatter (the
+ * `~/.agents/ is N commits behind` notice) correctly goes to stderr, but a
+ * single future stdout write anywhere in startup would make `JSON.parse` throw
+ * and turn every cache hit back into a silent miss — i.e. quietly reintroduce
+ * the Touch-ID-on-every-read bug this fix closes, with no failing test to catch
+ * it. Anchoring on the last line makes the payload the terminator of the
+ * stream rather than the whole of it, so preceding chatter is inert.
+ */
+export declare function lastLine(stdout: string): string;
 /**
  * Synchronous liveness check: is a broker actually LISTENING and answering (not
  * just a lingering socket file)? Used to decide whether the auto-cache may take
@@ -259,6 +306,25 @@ export declare function agentReachableSync(): boolean;
  * macOS only.
  */
 export declare function agentEvictSync(name: string): void;
+/** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
+ * cache hit. Exit 0 = hit, 3 = miss or broker down. */
+export declare function runAgentGetSync(name: string): Promise<number>;
+/** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
+ * our protocol, 3 = nothing there. Deliberately does NOT gate on
+ * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
+ * synchronous warm path, and a version-skewed broker still answers reads. That
+ * matches the inline program this replaced. */
+export declare function runAgentPingSync(): Promise<number>;
+/** Body of `__secrets-lock <name>`. Best-effort evict; exit 0 even when no
+ * broker answers, so a missing broker never fails the mutating write that
+ * triggered it (agentEvictSync discards this either way).
+ *
+ * An empty name is refused rather than forwarded: the broker treats a nameless
+ * lock as lock-ALL (handleAgentRequest), so a bare `__secrets-lock` would wipe
+ * every held bundle and re-prompt Touch ID for each. That was unreachable while
+ * this was an inline `node -e` string; as a top-level argv token it is one typo
+ * away, and agentEvictSync only ever locks by name. */
+export declare function runAgentLockSync(name: string): Promise<number>;
 /**
  * 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
@@ -364,4 +430,3 @@ export declare function agentPing(): Promise<{
  * gets starved under heavy load, so it's last.
  */
 export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;
-export {};

package/dist/lib/secrets/agent.js

@@ -35,6 +35,7 @@ import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
+import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
 const PROTOCOL_VERSION = 1;
@@ -58,6 +59,34 @@ export const META_CACHE_PREFIX = '!meta:';
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
 /** How often the broker sweeps expired entries. */
 const SWEEP_INTERVAL_MS = 30 * 1000;
+/**
+ * Timeouts for the three synchronous broker clients, split across the process
+ * boundary they now straddle.
+ *
+ * `SOCKET_*` bound the socket round-trip inside the spawned `__secrets-*`
+ * child, and carry over unchanged from the inline `node -e` programs these
+ * replaced. `SYNC_*` bound the parent's `spawnSync` and must additionally cover
+ * the child's boot, so each is its socket budget plus ~2s of headroom. A parent
+ * timeout that fired before the child's own timer would report "broker down"
+ * for a broker that is merely slow, which costs a Touch ID prompt — so the
+ * parent budget is deliberately the looser of the two.
+ *
+ * Boot cost, measured on the bun-compiled binary on an M-series Mac (median of
+ * 15, against a live broker): ~96ms via the index.ts intercept, ~165ms if the
+ * intercept is moved below the startup statements, ~44ms for the `node -e` this
+ * replaces. The intercept is what keeps the regression modest; see index.ts.
+ */
+const SOCKET_GET_TIMEOUT_MS = 2000;
+const SOCKET_PING_TIMEOUT_MS = 700;
+const SOCKET_LOCK_TIMEOUT_MS = 2000;
+const SYNC_GET_TIMEOUT_MS = 4000;
+const SYNC_PING_TIMEOUT_MS = 2500;
+const SYNC_LOCK_TIMEOUT_MS = 4000;
+// The argv tokens live in a leaf module so index.ts can bind the SAME values
+// without importing this one. Re-exported here for callers already reaching for
+// agent.js. See sync-commands.ts for why a shared binding rather than matching
+// literals: the drift it prevents is silent and costs a Touch ID prompt per read.
+export { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /**
  * Decide whether a persistent broker should self-heal onto freshly-installed
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
@@ -744,35 +773,52 @@ export function agentSocketExists() {
     return onDarwin() && fs.existsSync(socketPath());
 }
 /**
- * Inline node program for the synchronous read fast-path. `readAndResolveBundleEnv`
- * is synchronous and called synchronously everywhere, so we can't await a socket
- * round-trip — but spawning the full CLI to do it would load every command. This
- * minimal `node -e` client connects, asks for one bundle, prints the resolved
- * {bundle, env} as JSON, and exits 0 (hit) / 3 (miss or agent down). argv after
- * -e: [execPath, <socket>, <name>].
+ * Spawn one of the `__secrets-*` sync clients and return its result.
+ *
+ * These three call sites used to hand-roll `spawnSync(process.execPath, ['-e',
+ * <inline node program>, …])`. That is correct only for a JS install, where
+ * `process.execPath` is `node`. Since 1.20.53 the shipped macOS `agents` is a
+ * **bun-compiled Mach-O**, where `process.execPath` is the CLI binary itself —
+ * so the spawn became `agents -e <program> …`, which commander rejects with
+ * `error: unknown option '-e'` and a non-zero exit. Every sync client then took
+ * its own failure path (`agentGetSync` → null, `agentReachableSync` → false,
+ * `agentEvictSync` → no-op), which reads as "broker down" and falls through to
+ * a real keychain read. Net effect on the standalone binary: the broker cache
+ * was never hit, so the `daily` policy's one-prompt-per-7d never applied and
+ * every bundle read re-popped Touch ID.
+ *
+ * Same defect class as the broker-launch bug fixed in 1.20.56 (see cliSpawn's
+ * doc comment); these three sites were simply never converted. Routing them
+ * through `getCliLaunch` fixes both install shapes at once and keeps a single
+ * code path.
+ *
+ * The subcommands are top-level `__secrets-*` tokens intercepted in index.ts
+ * BEFORE commander and before the CLI's startup work, exactly like
+ * `__daemon-run` and `__vault-age-helper`. That is load-bearing, not cosmetic:
+ * a normal command path runs `checkForUpdates()` and `spawnDetachedSync()` on
+ * every invocation (index.ts), so registering these as ordinary hidden
+ * subcommands would fire an update check and spawn a detached background sync
+ * on every cache hit — turning the hot read path into a process fork storm.
  */
-const SYNC_GET_PROGRAM = `
-const net = require('net'), fs = require('fs');
-const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
-let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
-const c = net.createConnection(sock);
-let buf = '';
-const miss = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
-const timer = setTimeout(miss, 2000);
-c.on('error', miss);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name, token }) + '\\n'));
-c.setEncoding('utf-8');
-c.on('data', (d) => {
-  buf += d;
-  const nl = buf.indexOf('\\n');
-  if (nl < 0) return;
-  clearTimeout(timer);
-  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return miss(); }
-  try { c.destroy(); } catch (e) {}
-  if (r && r.ok && r.hit) { process.stdout.write(JSON.stringify({ bundle: r.bundle, env: r.env })); process.exit(0); }
-  process.exit(3);
-});
-`;
+export function syncClientLaunch(sub, agentsBin) {
+    return agentsBin ? getCliLaunch(sub, agentsBin) : getCliLaunch(sub);
+}
+function syncClient(sub, timeout) {
+    // Soft on every failure: bundles.ts's fast path promises "any failure falls
+    // through to the real keychain read below". spawnSync reports most failures
+    // via r.error rather than throwing, but getCliLaunch/getAgentsBinPath DO
+    // throw on a broken install — a bunfs entry whose execPath is gone, or a
+    // browser/computer shim with no sibling index.js. Without this catch those
+    // turn a graceful fallback into a crash, and only on already-degraded
+    // installs, which is the worst time for it.
+    try {
+        const { command, args } = syncClientLaunch(sub);
+        return spawnSync(command, args, { encoding: 'utf-8', timeout });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Synchronous read for the hot path. Returns the cached resolved bundle, or
  * null if the agent isn't running / doesn't hold this bundle / anything fails
@@ -781,14 +827,11 @@ c.on('data', (d) => {
 export function agentGetSync(name) {
     if (!agentSocketExists())
         return null;
-    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name, tokenPath()], {
-        encoding: 'utf-8',
-        timeout: 3000,
-    });
-    if (r.status !== 0 || !r.stdout)
+    const r = syncClient([SYNC_GET_CMD, name], SYNC_GET_TIMEOUT_MS);
+    if (!r || r.status !== 0 || !r.stdout)
         return null;
     try {
-        const o = JSON.parse(r.stdout);
+        const o = JSON.parse(lastLine(r.stdout));
         if (!o || typeof o !== 'object' || !o.env)
             return null;
         return { bundle: o.bundle, env: o.env };
@@ -797,30 +840,28 @@ export function agentGetSync(name) {
         return null;
     }
 }
-/** Inline node program for a synchronous liveness ping. Connects, sends one
- * `{cmd:'ping'}`, exits 0 iff a valid ping response comes back, else 3. A stale
- * socket file with no listener refuses the connection immediately, so this
- * fast-fails without riding any cold-start logic. argv after -e: [execPath, <socket>]. */
-const SYNC_PING_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1];
-const c = net.createConnection(sock);
-let buf = '';
-const dead = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
-const timer = setTimeout(dead, 700);
-c.on('error', dead);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'ping' }) + '\\n'));
-c.setEncoding('utf-8');
-c.on('data', (d) => {
-  buf += d;
-  const nl = buf.indexOf('\\n');
-  if (nl < 0) return;
-  clearTimeout(timer);
-  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return dead(); }
-  try { c.destroy(); } catch (e) {}
-  process.exit(r && r.ok && r.cmd === 'ping' ? 0 : 3);
-});
-`;
+/**
+ * Last non-empty line of a child's stdout — the payload line.
+ *
+ * The inline `node -e` client this replaced was a bare node process that could
+ * only ever emit its own JSON. The replacement boots the real CLI, so anything
+ * the CLI prints on the way up shares that stream. Today the known chatter (the
+ * `~/.agents/ is N commits behind` notice) correctly goes to stderr, but a
+ * single future stdout write anywhere in startup would make `JSON.parse` throw
+ * and turn every cache hit back into a silent miss — i.e. quietly reintroduce
+ * the Touch-ID-on-every-read bug this fix closes, with no failing test to catch
+ * it. Anchoring on the last line makes the payload the terminator of the
+ * stream rather than the whole of it, so preceding chatter is inert.
+ */
+export function lastLine(stdout) {
+    const lines = stdout.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const t = lines[i].trim();
+        if (t)
+            return t;
+    }
+    return '';
+}
 /**
  * Synchronous liveness check: is a broker actually LISTENING and answering (not
  * just a lingering socket file)? Used to decide whether the auto-cache may take
@@ -834,36 +875,9 @@ export function agentReachableSync() {
         return false;
     if (!agentSocketExists())
         return false;
-    const r = spawnSync(process.execPath, ['-e', SYNC_PING_PROGRAM, socketPath()], { timeout: 1500 });
-    return r.status === 0 && !r.error;
+    const r = syncClient([SYNC_PING_CMD], SYNC_PING_TIMEOUT_MS);
+    return r !== null && r.status === 0 && !r.error;
 }
-/**
- * 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'), fs = require('fs');
-const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
-let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
-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, token }) + '\\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
@@ -877,10 +891,60 @@ export function agentEvictSync(name) {
         return;
     if (!agentSocketExists())
         return;
-    try {
-        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name, tokenPath()], { timeout: 3000 });
+    // No try/catch: syncClient swallows its own failures and returns null.
+    syncClient([SYNC_LOCK_CMD, name], SYNC_LOCK_TIMEOUT_MS);
+}
+// ─── Top-level `__secrets-*` sync-client entrypoints ────────────────────────
+// The bodies behind the three spawns above. Each does one socket round-trip and
+// signals the parent through its exit code, mirroring the inline `node -e`
+// programs these replaced: 0 = hit/alive, 3 = miss/down. Lock deviates twice:
+// it reports 0 even when no broker answers, and 3 for an empty name, which it
+// refuses rather than forwarding as a lock-ALL (see runAgentLockSync).
+// Dispatched from index.ts BEFORE commander and before the startup statements,
+// so a cache hit never runs checkForUpdates() or forks a detached sync.
+/** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
+ * cache hit. Exit 0 = hit, 3 = miss or broker down. */
+export async function runAgentGetSync(name) {
+    const r = await request({ cmd: 'get', name }, SOCKET_GET_TIMEOUT_MS);
+    if (r?.ok === true && r.cmd === 'get' && r.hit) {
+        // Trailing newline: the parent reads the LAST line (see lastLine), so the
+        // payload must terminate the stream even if anything ever precedes it.
+        //
+        // Awaited on the write callback, not fire-and-forget: stdout is a pipe here
+        // (the parent captures it), pipe writes are asynchronous, and the caller
+        // exits the process the moment this resolves. An unflushed write would be
+        // truncated on exit — the parent would see a partial or empty payload, treat
+        // it as a miss, and fall through to a keychain read, silently costing the
+        // Touch ID prompt this whole path exists to avoid.
+        const payload = JSON.stringify({ bundle: r.bundle, env: r.env }) + '\n';
+        await new Promise((resolve) => { process.stdout.write(payload, () => resolve()); });
+        return 0;
     }
-    catch { /* best-effort */ }
+    return 3;
+}
+/** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
+ * our protocol, 3 = nothing there. Deliberately does NOT gate on
+ * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
+ * synchronous warm path, and a version-skewed broker still answers reads. That
+ * matches the inline program this replaced. */
+export async function runAgentPingSync() {
+    const r = await request({ cmd: 'ping' }, SOCKET_PING_TIMEOUT_MS);
+    return r?.ok === true && r.cmd === 'ping' ? 0 : 3;
+}
+/** Body of `__secrets-lock <name>`. Best-effort evict; exit 0 even when no
+ * broker answers, so a missing broker never fails the mutating write that
+ * triggered it (agentEvictSync discards this either way).
+ *
+ * An empty name is refused rather than forwarded: the broker treats a nameless
+ * lock as lock-ALL (handleAgentRequest), so a bare `__secrets-lock` would wipe
+ * every held bundle and re-prompt Touch ID for each. That was unreachable while
+ * this was an inline `node -e` string; as a top-level argv token it is one typo
+ * away, and agentEvictSync only ever locks by name. */
+export async function runAgentLockSync(name) {
+    if (!name)
+        return 3;
+    await request({ cmd: 'lock', name }, SOCKET_LOCK_TIMEOUT_MS);
+    return 0;
 }
 // Key inside the cached entry's env that holds the JSON metadata snapshot.
 const META_SNAPSHOT_KEY = '__snapshot__';

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

@@ -114,6 +114,32 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
  */
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
+/**
+ * Thrown by `readBundle` for the one state `readBundleIfDecryptable` may treat
+ * as "present but permanently unreadable": file-store ciphertext on disk that
+ * will not decrypt with the passphrase in effect (lost/rotated key or a tampered
+ * store). It is deliberately narrow — a bundle that is merely *locked for this
+ * run* (headless macOS without `AGENTS_SECRETS_PASSPHRASE`, or a vault that is
+ * not logged in) is recoverable and must not be collapsed into this.
+ */
+export declare class BundleUndecryptableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read a bundle, or return null when its metadata is present but genuinely
+ * cannot be decrypted — a lost or rotated file-store passphrase, or a tampered
+ * file store (signalled by `BundleUndecryptableError`).
+ *
+ * Deleting such a bundle is the only way out of that state, and deletion needs
+ * no plaintext, so it must not be gated behind a successful decrypt. Every other
+ * failure rethrows: a genuinely missing bundle ("not found"), and — critically —
+ * a bundle that is only *temporarily locked* for this run (headless macOS with no
+ * `AGENTS_SECRETS_PASSPHRASE`, or a not-logged-in vault). Collapsing that
+ * recoverable "set the env / log in" state into "unreadable, safe to delete"
+ * would let `secrets delete <name> --yes` silently destroy a perfectly healthy
+ * bundle from a cron/launchd run that merely forgot to export the passphrase.
+ */
+export declare function readBundleIfDecryptable(name: string): SecretsBundle | null;
 export declare function readBundle(name: string): SecretsBundle;
 /** The default prompt policy applied to bundles without an explicit per-bundle
  * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
@@ -147,6 +173,14 @@ export declare function shouldEvictAfterBundleWrite(skipRequested: boolean, noAg
 export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function writeBundleWithItems(bundle: SecretsBundle, items: Map<string, string>, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
+/**
+ * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
+ * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just
+ * batch-read, so writing it back only flips the ACL (via the helper's
+ * delete-then-add `set-no-acl`) — contents and updated_at are preserved and no
+ * extra keychain read is issued. Exported for tests. Returns the count healed.
+ */
+export declare function healKeychainBundleMetadata(metaJsonByName: Map<string, string>): number;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
     key: string;