@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/runner.js

@@ -23,6 +23,8 @@ import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
 import { normalizeMode, buildExecEnv, detectRateLimit, } 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 { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
@@ -448,6 +450,12 @@ export async function executeJob(config, deps) {
     if (eligibility) {
         throw new Error(eligibility.message);
     }
+    // `host:` placement — the job body runs on another machine over SSH; local
+    // version selection / sandbox / spawn do not apply. Sync callers (manual
+    // `routines run`, catchup) follow the remote run to completion.
+    if (config.host) {
+        return executeJobOnHost(config, { detached: false });
+    }
     // Command-mode: run a plain shell command directly (no agent, no rotation,
     // no pinning, no sandbox overlay). Reuses the run-record machinery so
     // list/runs/overdue keep working.
@@ -617,15 +625,67 @@ export async function executeJob(config, deps) {
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
-/**
- * Foreground execution for a command-mode routine (`config.command`). Runs a
- * plain shell command in the REAL environment (no sandbox), captures stdout+
- * stderr to `stdout.log`, awaits completion, and honors `config.timeout` with
- * the same SIGTERM→SIGKILL kill mechanism the agent path uses. No agent is
- * spawned; the run record carries `command` instead of `agent`. There is no
- * agent report to extract, so `reportPath` is always null (the stdout log is
- * the artifact — same location the agent path writes).
- */
+async function executeJobOnHost(config, opts) {
+    if (config.workflow) {
+        throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
+    }
+    if (config.loop) {
+        throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute on a host yet — remove 'host:' or 'loop:'.`);
+    }
+    if (config.command) {
+        throw new Error(`Routine '${config.name}' uses 'command:', which can't execute on a host yet — remove 'host:' or 'command:'.`);
+    }
+    const { resolveHostRunTarget, dispatchPromptToHost } = await import('./hosts/run-target.js');
+    const host = await resolveHostRunTarget(config.host);
+    const timer = createTimer('agent.run', {
+        agent: config.agent,
+        jobName: config.name,
+        mode: config.mode,
+        host: host.name,
+        ...redactPrompt(config.prompt),
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const meta = {
+        jobName: config.name,
+        runId,
+        agent: config.agent,
+        pid: null, // no local process — the run lives on the host
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+        host: host.name,
+    };
+    writeRunMeta(meta);
+    const { task, exitCode } = await dispatchPromptToHost(host, {
+        agent: config.agent,
+        prompt: resolveJobPrompt(config),
+        mode: normalizeMode(config.mode),
+        effort: config.effort,
+        model: config.config?.model,
+        timeout: config.timeout, // enforced by the REMOTE agents run
+        remoteCwd: config.remoteCwd,
+        name: config.name,
+        cwd: runDir,
+        follow: !opts.detached,
+    });
+    meta.hostTaskId = task.id;
+    // Sync path: a real exit code finalizes now. -1 (follow window closed) and
+    // the detached path leave the meta `running` for the monitor to reconcile.
+    if (!opts.detached && exitCode !== null && exitCode !== undefined && exitCode !== -1) {
+        meta.status = exitCode === 0 ? 'completed' : 'failed';
+        meta.exitCode = exitCode;
+        meta.completedAt = new Date().toISOString();
+    }
+    writeRunMeta(meta);
+    timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
+    return { meta, reportPath: null };
+}
+/** Spawn a job as a detached process and return immediately with run metadata. */
 async function executeCommandJobForeground(config) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
@@ -712,12 +772,18 @@ async function executeCommandJobForeground(config) {
     return { meta, reportPath: null };
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const eligibility = checkJobDeviceEligibility(config);
     if (eligibility) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    // `host:` placement — dispatch over SSH and return; the monitor finalizes.
+    if (config.host) {
+        const { meta } = await executeJobOnHost(config, { detached: true });
+        return meta;
+    }
     // Command-mode: fire a plain shell command detached (no agent, no rotation,
     // no pinning, no sandbox overlay). Still writes a run record so the daemon,
     // list/runs, and overdue tracking keep working.
@@ -994,6 +1060,26 @@ function isPidOurs(pid, spawnedAt) {
         return true;
     }
 }
+/**
+ * Finalize one `host:`-placed run by healing its host-task sidecar against the
+ * remote `.exit` (lib/hosts/reconcile.ts). Mutates + persists the meta only
+ * when the sidecar reached a terminal state.
+ */
+function finalizeHostRun(meta) {
+    try {
+        const task = loadHostTask(meta.hostTaskId);
+        if (!task)
+            return;
+        const healed = reconcileHostTask(task);
+        if (healed.status !== 'completed' && healed.status !== 'failed')
+            return;
+        meta.status = healed.status;
+        meta.exitCode = healed.exitCode ?? (healed.status === 'completed' ? 0 : 1);
+        meta.completedAt = healed.finishedAt ?? new Date().toISOString();
+        writeRunMeta(meta);
+    }
+    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+}
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
@@ -1013,6 +1099,13 @@ export function monitorRunningJobs() {
                 const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
                 if (meta.status !== 'running')
                     continue;
+                // `host:`-placed run — no local pid to watch. Reconcile against the
+                // remote `.exit` (completion is confirmed, never guessed: an
+                // unreachable host leaves the run `running` for the next sweep).
+                if (meta.hostTaskId) {
+                    finalizeHostRun(meta);
+                    continue;
+                }
                 if (!meta.pid)
                     continue;
                 const runDirPath = path.join(jobRunsPath, runDirEntry.name);

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

@@ -207,6 +207,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 +246,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. */

package/dist/lib/secrets/agent.js

@@ -723,6 +723,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
@@ -817,26 +857,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.
  *
- * 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.
+ * 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) 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 +942,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 +962,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.
  *

package/dist/lib/secrets/bundles.js

@@ -25,7 +25,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
-import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -492,8 +492,11 @@ export function listBundles() {
                 for (const bundle of keychainBundles)
                     out.push(bundle);
                 // Populate the broker for the rest of the hold window (fire-and-forget).
+                // Same configurable cap as the value read-path — otherwise `secrets list`
+                // would keep serving a stale metadata snapshot for 7d even when the user
+                // capped the hold at 24h via secrets.agent.holdMs.
                 if (useAgent && keychainBundles.length > 0) {
-                    agentAutoLoadMetaSync(nameSetHash, keychainBundles, DEFAULT_TTL_MS);
+                    agentAutoLoadMetaSync(nameSetHash, keychainBundles, secretsHoldMs());
                 }
             }
         }
@@ -705,6 +708,44 @@ export function resolveBundleEnv(bundle, _opts = {}) {
     void _opts.caller;
     return env;
 }
+/**
+ * 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 function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
+    if (platform !== 'darwin')
+        return false; // no biometry prompt to suppress off-darwin
+    const override = env.AGENTS_SECRETS_NO_PROMPT;
+    if (override === '1')
+        return true;
+    if (override === '0')
+        return false;
+    const runtime = env.AGENTS_RUNTIME;
+    if (runtime === 'headless' || runtime === 'teams')
+        return true;
+    return !process.stdin.isTTY && !process.stdout.isTTY;
+}
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -747,8 +788,15 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    if (opts.agentOnly) {
-        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent.`);
+    // Only keychain-backed bundles can pop a Touch ID prompt and are the only ones
+    // the broker ever holds. A file-backed bundle resolves via passphrase with no
+    // prompt, so agentOnly must never block it — the broker never holds file
+    // bundles, so the throw would fire unconditionally and break a legitimate read.
+    if (opts.agentOnly && backend === 'keychain') {
+        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent, and this is a ` +
+            `headless/background process that must not raise a Touch ID prompt on the ` +
+            `interactive user's screen. Run 'agents secrets unlock ${name}' in a terminal ` +
+            `first, or set AGENTS_SECRETS_NO_PROMPT=0 to force an interactive prompt.`);
     }
     if (backend === 'file')
         assertFileBackendUsable(name);
@@ -881,15 +929,18 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         emitReadAudit('success');
         // Auto-cache: this was a real keychain read (the agent fast-path returned
         // earlier on a hit). If the bundle opts into the `daily` policy and the user
-        // enabled `secrets.agent.auto`, populate the broker in the background so the
-        // next concurrent run reads silently. Skipped when noAgent (e.g. `unlock`,
-        // which loads the agent itself). Fire-and-forget — never blocks this read.
+        // enabled `secrets.agent.auto`, populate the broker so the next concurrent
+        // run reads silently. Skipped when noAgent (e.g. `unlock`, which loads the
+        // agent itself). When a broker is already up this warms it synchronously
+        // (bounded ~3s) so `daily` reliably sticks; only a cold-start broker uses the
+        // detached fire-and-forget path (see agentAutoLoadSync). The costly Touch ID
+        // prompt already happened, so the bounded wait is invisible.
         if (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
             bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled()) {
-            agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs());
         }
         return { bundle, env };
     }

package/dist/lib/secrets/mcp.js

@@ -24,7 +24,7 @@
  * unit-testable in-process.
  */
 import * as readline from 'readline';
-import { listBundles, readAndResolveBundleEnv, readBundle, validateBundleName, } from './bundles.js';
+import { listBundles, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, validateBundleName, } from './bundles.js';
 /** MCP protocol revision this server negotiates. */
 export const MCP_PROTOCOL_VERSION = '2024-11-05';
 /** The single tool this server exposes. */
@@ -68,7 +68,9 @@ export function resolveSecret(bundle, key) {
         throw new Error(`Key '${key}' not found in bundle '${bundle}'.` +
             (available.length ? ` Available keys: ${available.join(', ')}.` : ' Bundle has no keys.'));
     }
-    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp' });
+    // The MCP get_secret tool is typically served by a background/headless agent
+    // process; resolve broker-only there so it never raises an unwatched prompt.
+    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp', agentOnly: isHeadlessSecretsContext() });
     const value = env[key];
     if (value === undefined) {
         throw new Error(`Key '${key}' in bundle '${bundle}' could not be resolved.`);

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

@@ -16,6 +16,23 @@
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
+/**
+ * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
+ * is untrusted input: a compromised or misconfigured host could return keys that
+ * silently reshape THIS process's behavior once merged into the agent env
+ * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
+ * never the remote bundle). Block the dangerous-override classes here — at the
+ * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
+ * protected, not just one call site:
+ *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
+ *     (reuses the canonical bundles.ts predicate);
+ *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
+ *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
+ *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
+ * These keys are already rejected on the ADD side (validateEnvKey for loaders),
+ * so a legitimate bundle never carries them — only a hostile peer would.
+ */
+export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
  * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
  * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,