@phnx-labs/agents-cli 1.20.64 → 1.20.66

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

@@ -23,6 +23,7 @@
  * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
  * deduplicate — every entry point here no-ops off darwin.
  */
+import * as net from 'net';
 import type { SecretsBundle } from './bundles.js';
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
@@ -74,6 +75,13 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
 }
+/**
+ * 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
+ * restart mints a new token, so a stale read simply fails authorization and the
+ * caller falls back to a direct keychain read (soft, never a hard error).
+ */
+export declare function readAgentToken(): string | null;
 /** True if a legacy standalone-broker launchd plist is still installed. */
 export declare function secretsAgentServiceInstalled(): boolean;
 /**
@@ -97,17 +105,21 @@ export type Request = {
 } | {
     cmd: 'get';
     name: string;
+    token?: string;
 } | {
     cmd: 'load';
     name: string;
     bundle: SecretsBundle;
     env: Record<string, string>;
     ttlMs: number;
+    token?: string;
 } | {
     cmd: 'lock';
     name?: string;
+    token?: string;
 } | {
     cmd: 'status';
+    token?: string;
 };
 export type Response = {
     ok: true;
@@ -164,6 +176,28 @@ export declare function handleAgentRequest(store: Map<string, StoredBundle>, req
  * has direct regression coverage (the inline stdout handler isn't unit-testable).
  */
 export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
+/**
+ * Authorization gate applied to every request BEFORE handleAgentRequest touches
+ * the store (RUSH-1760). A bare same-UID socket connection is no longer trusted
+ * to load/get arbitrary bundle env: each command except the liveness `ping` must
+ * carry the per-broker capability token, which lives in a 0600 file inside the
+ * 0700 agent dir and so is readable only by the UID that owns the broker.
+ *
+ * Fail closed: a missing/empty expected token (no token file) rejects every
+ * command but ping. `ping` stays unauthenticated — it exposes only the protocol
+ * and cli version, and clients need it to detect a reachable broker before they
+ * have any reason to read the token. Pure + exported for direct unit testing.
+ */
+export declare function isRequestAuthorized(req: Request, expectedToken: string | null): boolean;
+type BrokerConnectionHandler = (conn: net.Socket) => void;
+/**
+ * Build the socket `connection` handler shared by both brokers (standalone and
+ * daemon-hosted): newline-framed JSON in, one response line out, with the
+ * authorization gate (isRequestAuthorized) applied before `handle`. `token`
+ * resolves the currently-expected capability token per request so a token
+ * rotation on broker restart is picked up without rebuilding the handler.
+ */
+export declare function makeConnectionHandler(handle: (req: Request) => Response, token: () => string | null): BrokerConnectionHandler;
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
@@ -207,6 +241,15 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * 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
+ * the synchronous warm path — a dead broker whose socket outlived it (crash,
+ * OOM, version-skew teardown) must NOT drag a foreground read through the
+ * worker's 20s cold-start budget. A stale socket refuses instantly, so this is
+ * fast in both the alive and dead cases. macOS only.
+ */
+export declare function agentReachableSync(): boolean;
 /**
  * Synchronously evict one bundle from the broker. Called after a mutating
  * keychain write (add / rotate / remove / rename / delete) so the broker never
@@ -237,25 +280,54 @@ export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: Secr
  * per ~7d), so auto-caching is ON by default; opt out with
  * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export declare function secretsAgentAutoEnabled(): boolean;
+/** Minimum / maximum bounds for the configurable hold window. A too-small value
+ * would defeat the broker (constant re-prompts); a too-large one pins secrets in
+ * memory far longer than intended. */
+export declare const MIN_HOLD_MS: number;
+export declare const MAX_HOLD_MS: number;
+/**
+ * How long an unlocked / auto-cached bundle is held before the next read
+ * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with
+ * `secrets.agent.holdMs` (milliseconds) in agents.yaml — e.g. 86400000 for a 24h
+ * cap. Clamped to [MIN_HOLD_MS, MAX_HOLD_MS] so a typo can neither disable the
+ * hold nor pin a secret in memory indefinitely. Best-effort: an unreadable or
+ * non-numeric value falls back to the 7d default. Pure except for the meta read.
+ */
+export declare function secretsHoldMs(): number;
+/** Pure clamp for a configured `holdMs`: a positive finite number is bounded to
+ * [MIN_HOLD_MS, MAX_HOLD_MS]; anything else (absent, 0, negative, NaN, non-number)
+ * falls back to the 7d default. Exported for direct unit testing. */
+export declare function clampHoldMs(v: unknown): number;
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
- * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
- * over stdin, never argv) and returns immediately.
+ * real keychain read of a `daily`-policy bundle, so the NEXT concurrent read is
+ * silent. Env travels over stdin, never argv.
+ *
+ * Reliability (this is what makes `daily` actually "stick"): when a broker is
+ * ALREADY listening, warm it SYNCHRONOUSLY with a bounded wait so the bundle is
+ * held by the time this process exits. The old detached-only path lost the race
+ * under load — a short-lived reader (`agents secrets export`, a release-script
+ * loop) exited before the unref'd worker connected, so the cache silently never
+ * populated and every read re-prompted despite the `daily` policy. Only when the
+ * broker must COLD-START (no socket yet) do we fall back to the detached worker,
+ * so a first-ever read never blocks on a multi-second broker boot.
  *
- * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
- * generous budget) rather than a tight inline retry loop: under heavy load the
- * broker is itself a cold-starting full CLI and can take several seconds to bind
- * the socket, so a short fixed budget would give up before it's ready and the
- * cache would silently never populate. Best-effort; never throws. macOS only.
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
+ * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
 export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
- * budget), and loads the bundle into it. Detached from the originating read, so
- * its latency is invisible — which is why it can afford a long ensure budget.
+ * budget), and loads the bundle into it.
+ *
+ * Exit code is load-truthful: 0 ONLY when the bundle was actually loaded into a
+ * reachable broker; non-zero on any failure (malformed payload, broker couldn't
+ * be brought up, or the load transport failed). The synchronous caller
+ * (agentAutoLoadSync) relies on this to decide whether to skip the detached
+ * fallback — a bare "process exited 0" would otherwise be a false-positive
+ * success that silently reintroduces the very re-prompt storm this path fixes.
  */
 export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
@@ -287,3 +359,4 @@ 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

@@ -27,6 +27,7 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { randomBytes } from 'crypto';
 import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
 import { isAlive } from '../platform/process.js';
@@ -109,6 +110,42 @@ function socketPath() {
 function pidPath() {
     return path.join(agentDir(), 'agent.pid');
 }
+/**
+ * Path of the per-broker capability token. It lives in the 0700 agent dir and is
+ * written 0600, so only the same UID that owns the broker can read it — the file
+ * permission IS the authorization boundary. See isRequestAuthorized.
+ */
+function tokenPath() {
+    return path.join(agentDir(), 'agent.token');
+}
+/**
+ * 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
+ * restart mints a new token, so a stale read simply fails authorization and the
+ * caller falls back to a direct keychain read (soft, never a hard error).
+ */
+export function readAgentToken() {
+    try {
+        const t = fs.readFileSync(tokenPath(), 'utf-8').trim();
+        return t.length > 0 ? t : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Mint + persist a fresh capability token (0600) at socket-bind time. Only the
+ * process that actually binds the socket calls this, so a losing starter never
+ * clobbers the live owner's token. Returns the token for in-memory comparison. */
+function writeAgentToken() {
+    const token = randomBytes(32).toString('hex');
+    const fp = tokenPath();
+    fs.writeFileSync(fp, token, { mode: 0o600 });
+    try {
+        fs.chmodSync(fp, 0o600);
+    }
+    catch { /* dir 0700 already gates it */ }
+    return token;
+}
 /**
  * Argv for re-invoking THIS cli with a hidden subcommand, so a side-by-side dev
  * build spawns its own helpers rather than the registry-installed one. We always
@@ -272,6 +309,60 @@ export function handleAgentRequest(store, req, now = Date.now()) {
 export function shouldWipeOnWatchEvent(chunk) {
     return /\bSLEEP\b/.test(chunk);
 }
+/**
+ * Authorization gate applied to every request BEFORE handleAgentRequest touches
+ * the store (RUSH-1760). A bare same-UID socket connection is no longer trusted
+ * to load/get arbitrary bundle env: each command except the liveness `ping` must
+ * carry the per-broker capability token, which lives in a 0600 file inside the
+ * 0700 agent dir and so is readable only by the UID that owns the broker.
+ *
+ * Fail closed: a missing/empty expected token (no token file) rejects every
+ * command but ping. `ping` stays unauthenticated — it exposes only the protocol
+ * and cli version, and clients need it to detect a reachable broker before they
+ * have any reason to read the token. Pure + exported for direct unit testing.
+ */
+export function isRequestAuthorized(req, expectedToken) {
+    if (req.cmd === 'ping')
+        return true;
+    if (!expectedToken)
+        return false;
+    return req.token === expectedToken;
+}
+/**
+ * Build the socket `connection` handler shared by both brokers (standalone and
+ * daemon-hosted): newline-framed JSON in, one response line out, with the
+ * authorization gate (isRequestAuthorized) applied before `handle`. `token`
+ * resolves the currently-expected capability token per request so a token
+ * rotation on broker restart is picked up without rebuilding the handler.
+ */
+export function makeConnectionHandler(handle, token) {
+    return (conn) => {
+        conn.setEncoding('utf-8');
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let resp;
+                try {
+                    const req = JSON.parse(line);
+                    resp = isRequestAuthorized(req, token())
+                        ? handle(req)
+                        : { ok: false, error: 'unauthorized' };
+                }
+                catch (err) {
+                    resp = { ok: false, error: err.message };
+                }
+                conn.write(JSON.stringify(resp) + '\n');
+            }
+        });
+        conn.on('error', () => { });
+    };
+}
 /**
  * Bind the shared broker socket without stealing it from another live owner.
  * Both the standalone service and daemon-hosted broker use this single path so
@@ -293,6 +384,13 @@ async function bindBrokerSocket(sock, onConnection) {
                 fs.chmodSync(sock, 0o600);
             }
             catch { /* dir 0700 already gates it */ }
+            // Mint the capability token here — the one moment this process is the
+            // confirmed socket owner — so a losing starter never clobbers the live
+            // owner's token (RUSH-1760).
+            try {
+                writeAgentToken();
+            }
+            catch { /* dir 0700 gates the socket regardless */ }
             resolve(server);
         });
     });
@@ -428,29 +526,7 @@ export async function runSecretsAgent(opts = {}) {
             emptySince = Date.now();
         return resp;
     };
-    const onConnection = (conn) => {
-        conn.setEncoding('utf-8');
-        let buf = '';
-        conn.on('data', (chunk) => {
-            buf += chunk;
-            let nl;
-            while ((nl = buf.indexOf('\n')) >= 0) {
-                const line = buf.slice(0, nl);
-                buf = buf.slice(nl + 1);
-                if (!line.trim())
-                    continue;
-                let resp;
-                try {
-                    resp = handle(JSON.parse(line));
-                }
-                catch (err) {
-                    resp = { ok: false, error: err.message };
-                }
-                conn.write(JSON.stringify(resp) + '\n');
-            }
-        });
-        conn.on('error', () => { });
-    };
+    const onConnection = makeConnectionHandler(handle, readAgentToken);
     let server = null;
     do {
         try {
@@ -558,29 +634,7 @@ export async function startHostedBroker() {
     const store = new Map();
     const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
     const handle = (req) => handleAgentRequest(store, req);
-    const onConn = (conn) => {
-        conn.setEncoding('utf-8');
-        let buf = '';
-        conn.on('data', (chunk) => {
-            buf += chunk;
-            let nl;
-            while ((nl = buf.indexOf('\n')) >= 0) {
-                const line = buf.slice(0, nl);
-                buf = buf.slice(nl + 1);
-                if (!line.trim())
-                    continue;
-                let resp;
-                try {
-                    resp = handle(JSON.parse(line));
-                }
-                catch (err) {
-                    resp = { ok: false, error: err.message };
-                }
-                conn.write(JSON.stringify(resp) + '\n');
-            }
-        });
-        conn.on('error', () => { });
-    };
+    const onConn = makeConnectionHandler(handle, readAgentToken);
     const server = await bindBrokerSocket(sock, onConn);
     if (!server)
         return null;
@@ -632,6 +686,9 @@ export async function startHostedBroker() {
 /** Open the socket, send one request, resolve the one response. Async path —
  * used by the unlock/lock/status commands, which already run in async actions. */
 function request(req, timeoutMs = 2000) {
+    // Attach the capability token to every command except ping (the auth gate;
+    // RUSH-1760). ping stays tokenless so a client can probe reachability first.
+    const authedReq = req.cmd === 'ping' ? req : { ...req, token: readAgentToken() ?? undefined };
     return new Promise((resolve) => {
         const conn = net.createConnection(socketPath());
         let buf = '';
@@ -649,7 +706,7 @@ function request(req, timeoutMs = 2000) {
         };
         const timer = setTimeout(() => finish(null), timeoutMs);
         conn.on('error', () => finish(null));
-        conn.on('connect', () => conn.write(JSON.stringify(req) + '\n'));
+        conn.on('connect', () => conn.write(JSON.stringify(authedReq) + '\n'));
         conn.setEncoding('utf-8');
         conn.on('data', (chunk) => {
             buf += chunk;
@@ -679,14 +736,15 @@ export function agentSocketExists() {
  * -e: [execPath, <socket>, <name>].
  */
 const SYNC_GET_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1], name = process.argv[2];
+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 }) + '\\n'));
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name, token }) + '\\n'));
 c.setEncoding('utf-8');
 c.on('data', (d) => {
   buf += d;
@@ -707,7 +765,7 @@ c.on('data', (d) => {
 export function agentGetSync(name) {
     if (!agentSocketExists())
         return null;
-    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name], {
+    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name, tokenPath()], {
         encoding: 'utf-8',
         timeout: 3000,
     });
@@ -723,6 +781,46 @@ 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);
+});
+`;
+/**
+ * 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
+ * the synchronous warm path — a dead broker whose socket outlived it (crash,
+ * OOM, version-skew teardown) must NOT drag a foreground read through the
+ * worker's 20s cold-start budget. A stale socket refuses instantly, so this is
+ * fast in both the alive and dead cases. macOS only.
+ */
+export function agentReachableSync() {
+    if (!onDarwin())
+        return false;
+    if (!agentSocketExists())
+        return false;
+    const r = spawnSync(process.execPath, ['-e', SYNC_PING_PROGRAM, socketPath()], { timeout: 1500 });
+    return 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
@@ -731,14 +829,15 @@ export function agentGetSync(name) {
  * argv after -e: [execPath, <socket>, <name>].
  */
 const SYNC_LOCK_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1], name = process.argv[2];
+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 }) + '\\n'));
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'lock', name, token }) + '\\n'));
 c.setEncoding('utf-8');
 c.on('data', (d) => {
   buf += d;
@@ -763,7 +862,7 @@ export function agentEvictSync(name) {
     if (!agentSocketExists())
         return;
     try {
-        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name], { timeout: 3000 });
+        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name, tokenPath()], { timeout: 3000 });
     }
     catch { /* best-effort */ }
 }
@@ -817,26 +916,81 @@ export function secretsAgentAutoEnabled() {
         return true;
     }
 }
+/** Minimum / maximum bounds for the configurable hold window. A too-small value
+ * would defeat the broker (constant re-prompts); a too-large one pins secrets in
+ * memory far longer than intended. */
+export const MIN_HOLD_MS = 60 * 1000; // 1m
+export const MAX_HOLD_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+/**
+ * How long an unlocked / auto-cached bundle is held before the next read
+ * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with
+ * `secrets.agent.holdMs` (milliseconds) in agents.yaml — e.g. 86400000 for a 24h
+ * cap. Clamped to [MIN_HOLD_MS, MAX_HOLD_MS] so a typo can neither disable the
+ * hold nor pin a secret in memory indefinitely. Best-effort: an unreadable or
+ * non-numeric value falls back to the 7d default. Pure except for the meta read.
+ */
+export function secretsHoldMs() {
+    try {
+        return clampHoldMs(readMeta().secrets?.agent?.holdMs);
+    }
+    catch {
+        return DEFAULT_TTL_MS;
+    }
+}
+/** Pure clamp for a configured `holdMs`: a positive finite number is bounded to
+ * [MIN_HOLD_MS, MAX_HOLD_MS]; anything else (absent, 0, negative, NaN, non-number)
+ * falls back to the 7d default. Exported for direct unit testing. */
+export function clampHoldMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) {
+        return Math.min(Math.max(Math.floor(v), MIN_HOLD_MS), MAX_HOLD_MS);
+    }
+    return DEFAULT_TTL_MS;
+}
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
- * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
- * over stdin, never argv) and returns immediately.
+ * real keychain read of a `daily`-policy bundle, so the NEXT concurrent read is
+ * silent. Env travels over stdin, never argv.
+ *
+ * Reliability (this is what makes `daily` actually "stick"): when a broker is
+ * ALREADY listening, warm it SYNCHRONOUSLY with a bounded wait so the bundle is
+ * held by the time this process exits. The old detached-only path lost the race
+ * under load — a short-lived reader (`agents secrets export`, a release-script
+ * loop) exited before the unref'd worker connected, so the cache silently never
+ * populated and every read re-prompted despite the `daily` policy. Only when the
+ * broker must COLD-START (no socket yet) do we fall back to the detached worker,
+ * so a first-ever read never blocks on a multi-second broker boot.
  *
- * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
- * generous budget) rather than a tight inline retry loop: under heavy load the
- * broker is itself a cold-starting full CLI and can take several seconds to bind
- * the socket, so a short fixed budget would give up before it's ready and the
- * cache would silently never populate. Best-effort; never throws. macOS only.
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
+ * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
 export function agentAutoLoadSync(name, bundle, env, ttlMs) {
     if (!onDarwin())
         return;
+    const payload = JSON.stringify({ name, bundle, env, ttlMs });
+    // Broker actually LISTENING → deterministic synchronous warm (bounded; the read
+    // already paid a Touch ID, so <1s here is invisible). We gate on a real liveness
+    // ping, NOT mere socket-file existence: a broker that died leaving its socket
+    // behind (crash, OOM, or the version-skew teardown in this file) would otherwise
+    // drag this FOREGROUND read through the worker's 20s cold-start budget on every
+    // read. A dead/stale socket fails the ping fast, so we drop straight to the
+    // detached path (which does the cold-start + stale-socket cleanup off the hot
+    // path) — restoring "a dead broker costs the foreground read nothing".
+    if (agentReachableSync()) {
+        try {
+            const { cmd, args } = cliSpawn(['secrets', '_agent-load']);
+            const r = spawnSync(cmd, args, { input: payload, timeout: 3000, stdio: ['pipe', 'ignore', 'ignore'] });
+            if (!r.error && r.status === 0)
+                return;
+        }
+        catch {
+            // fall through to the detached best-effort path
+        }
+    }
     try {
         const { cmd, args } = cliSpawn(['secrets', '_agent-load']);
         const worker = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
-        worker.stdin?.write(JSON.stringify({ name, bundle, env, ttlMs }));
+        worker.stdin?.write(payload);
         worker.stdin?.end();
         worker.unref();
     }
@@ -847,8 +1001,14 @@ export function agentAutoLoadSync(name, bundle, env, ttlMs) {
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
- * budget), and loads the bundle into it. Detached from the originating read, so
- * its latency is invisible — which is why it can afford a long ensure budget.
+ * budget), and loads the bundle into it.
+ *
+ * Exit code is load-truthful: 0 ONLY when the bundle was actually loaded into a
+ * reachable broker; non-zero on any failure (malformed payload, broker couldn't
+ * be brought up, or the load transport failed). The synchronous caller
+ * (agentAutoLoadSync) relies on this to decide whether to skip the detached
+ * fallback — a bare "process exited 0" would otherwise be a false-positive
+ * success that silently reintroduces the very re-prompt storm this path fixes.
  */
 export async function runAgentLoadFromStdin() {
     if (!onDarwin())
@@ -861,15 +1021,22 @@ export async function runAgentLoadFromStdin() {
         payload = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
     }
     catch {
-        return; // malformed payload — nothing to load
+        process.exitCode = 1; // malformed payload — nothing loaded
+        return;
     }
-    if (!payload || !payload.name || !payload.bundle || !payload.env)
+    if (!payload || !payload.name || !payload.bundle || !payload.env) {
+        process.exitCode = 1;
         return;
+    }
     // Generous budget: the broker is a cold-starting full CLI; under load it can
     // take several seconds to bind. We're detached, so waiting costs nothing.
-    if (!(await ensureAgentRunning(20000)))
+    if (!(await ensureAgentRunning(20000))) {
+        process.exitCode = 1; // broker couldn't be brought up — did NOT load
         return;
-    await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+    }
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+    if (!loaded)
+        process.exitCode = 1; // transport failed — did NOT load
 }
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
 export async function agentLoad(name, bundle, env, ttlMs) {

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

@@ -221,6 +221,32 @@ export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, h
     allowExpiredFlag: string;
 }): void;
 export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveBundleOptions): Record<string, string>;
+/**
+ * True when the current process is a background / non-interactive context that
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
+ * a prompt nobody is watching. Two signals, either sufficient:
+ *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
+ *     `agents run --headless`, scheduled routines, and teammates — see
+ *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
+ *     stdio is redirected to a log — e.g. a release script run in the
+ *     background as `( ... ) >log 2>&1 </dev/null`).
+ * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
+ * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
+ * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ *
+ * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
+ * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
+ * the Windows credential store resolve without any prompt. So off-darwin this
+ * ALWAYS returns false: forcing broker-only there would break every headless
+ * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
+ * release flow) for no benefit — there is no prompt to suppress.
+ *
+ * A read in a macOS headless context resolves broker-only (agentOnly) and fails
+ * fast with an actionable error instead of hijacking Touch ID. This generalizes
+ * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
+ */
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *