@phnx-labs/agents-cli 1.22.3 → 1.22.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.22.4
+
+- **Background processes no longer storm macOS Touch ID sheets (secrets-touchid-storm).**
+  Raw keychain item reads — a profile's provider token on `agents run <profile>`,
+  the Claude OAuth read behind `agents view`, any `getKeychainToken` caller — now
+  fail fast with an actionable error naming the item when the process is
+  non-interactive (an agent runtime, or a TTY-less background spawn like the
+  Factory extension host's `agents view` poll), instead of raising a sheet nobody
+  is watching. A cancelled or failed interactive read opens a 5-minute back-off
+  memo (`~/.agents/.cache/keychain-read-backoff/`) so a polling caller can't
+  re-prompt every few seconds; any successful read or write clears it. Reads that
+  are prompt-free by construction (bundle metadata, `never`-policy bundles, the
+  unlock session store, the OAuth token cache) attest their no-ACL write and are
+  unaffected. crabbox's tailscale key is now read at most once per process
+  instead of on every `crabboxEnv` call (list/wait/spawn/stop). Source:
+  `apps/cli/src/lib/secrets/index.ts`, `apps/cli/src/lib/secrets/headless.ts`,
+  `apps/cli/src/lib/secrets/read-backoff.ts`,
+  `apps/cli/src/lib/secrets/bundles.ts`, `apps/cli/src/lib/crabbox/cli.ts`,
+  `apps/cli/docs/specifications.md` (SEC-13, SEC-27).
+
 ## 1.22.3
 
 - **Menubar home-base self-test accepts `MenubarHelper-universal`.** The

package/dist/lib/crabbox/cli.d.ts

@@ -83,6 +83,8 @@ export declare function pickTailscaleBundleFromList(bundles: SecretsBundle[]): {
     name: string;
     key: string;
 } | undefined;
+/** Test seam: drop every crabboxEnv secrets memo so each test resolves fresh. */
+export declare function resetCrabboxSecretsMemosForTest(): void;
 /** A resolved lease bundle: its name, plus (auto-detect only) the exact keys to inject. */
 export interface ResolvedLeaseBundle {
     name: string;

package/dist/lib/crabbox/cli.js

@@ -67,6 +67,42 @@ function resolveTailscaleBundleMemo() {
     }
     return tailscaleBundleMemo.value;
 }
+/**
+ * Process-lifetime memo for the RESOLVED tailscale key value, next to the pick
+ * memo above. `crabboxEnv` runs several times per lease (list/wait/spawn/stop),
+ * and the single-key subset read (`keys: [ts.key]`) is rejected by
+ * `canCacheResolvedEnv` for broker auto-cache — so without this memo a
+ * non-broker-held tailscale bundle re-read the keychain on EVERY call (and,
+ * pre-guard, could pop a Touch ID sheet each time). One read per process,
+ * success or failure (a failed read memoizes as undefined: the catch below
+ * already degrades to a public-network lease, retrying mid-process only
+ * repeats the same failure).
+ */
+let tailscaleValueMemo;
+function resolveTailscaleKeyValueMemo(ts) {
+    if (!tailscaleValueMemo) {
+        let value;
+        try {
+            const { env } = readAndResolveBundleEnv(ts.name, {
+                caller: 'agents run --lease (crabbox tailscale)',
+                keys: [ts.key],
+                agentOnly: isHeadlessSecretsContext(),
+            });
+            value = env[ts.key];
+        }
+        catch {
+            /* best-effort — tailscale is opt-in plumbing, never blocks a public lease */
+        }
+        tailscaleValueMemo = { value };
+    }
+    return tailscaleValueMemo.value;
+}
+/** Test seam: drop every crabboxEnv secrets memo so each test resolves fresh. */
+export function resetCrabboxSecretsMemosForTest() {
+    tailscaleBundleMemo = undefined;
+    tailscaleValueMemo = undefined;
+    leaseBundleMemo = undefined;
+}
 /**
  * The secrets bundle to feed crabbox, resolved in priority order:
  *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
@@ -151,23 +187,15 @@ export function crabboxEnv(opts) {
     // declares a tailscale auth key, when the ambient env doesn't already set one.
     // Best-effort and opt-in — a missing/unreadable tailscale bundle never fails a
     // public-network lease; `crabboxWarmup({ netMode: 'tailscale' })` is what decides
-    // whether the key is actually used.
+    // whether the key is actually used. The resolved value is memoized per process
+    // (see resolveTailscaleKeyValueMemo) so repeated crabboxEnv calls read the
+    // keychain at most once.
     if (!out.CRABBOX_TAILSCALE_AUTH_KEY) {
         const ts = resolveTailscaleBundleMemo();
         if (ts) {
-            try {
-                const { env } = readAndResolveBundleEnv(ts.name, {
-                    caller: 'agents run --lease (crabbox tailscale)',
-                    keys: [ts.key],
-                    agentOnly: isHeadlessSecretsContext(),
-                });
-                const value = env[ts.key];
-                if (value)
-                    out.CRABBOX_TAILSCALE_AUTH_KEY = value;
-            }
-            catch {
-                /* best-effort — tailscale is opt-in plumbing, never blocks a public lease */
-            }
+            const value = resolveTailscaleKeyValueMemo(ts);
+            if (value)
+                out.CRABBOX_TAILSCALE_AUTH_KEY = value;
         }
     }
     return out;

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

@@ -279,37 +279,12 @@ export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, h
 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`, `teams`, or `terminal` — i.e. ANY agent
- *     launch, interactive included, and inherited by everything spawned beneath
- *     one (set on the child env by `agents run --headless`, scheduled routines,
- *     teammates, and interactive runs — see exec.ts:430, 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 `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
- *
- * 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 broker-only pattern used across the headless secrets readers.
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen.
+ * Re-exported from ./headless.js — the detector lives there so the raw-read
+ * path in index.ts can share it without a bundles↔index import cycle. See that
+ * module for the full contract.
  */
-export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
-    stdin?: boolean;
-    stdout?: boolean;
-}): boolean;
+export { isHeadlessSecretsContext } from './headless.js';
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *

package/dist/lib/secrets/bundles.js

@@ -271,7 +271,14 @@ export function readBundle(name) {
         assertVaultBackendUsable(name);
     let json;
     try {
-        json = itemStore(backend).get(bundleMetaItem(name));
+        // Bundle metadata carries no biometry ACL (SEC-4), so this read is silent
+        // even in a headless context — attest that to the raw-read storm guard so
+        // a headless `readBundle` never trips the fail-fast. (A legacy
+        // pre-metadata-heal ACL'd metadata item can still prompt once; it heals on
+        // the next interactive read.)
+        json = backend === 'keychain'
+            ? getKeychainToken(bundleMetaItem(name), { silentNoAcl: true })
+            : itemStore(backend).get(bundleMetaItem(name));
     }
     catch (err) {
         // A file-backed bundle whose metadata is on disk but fails to decrypt is a
@@ -669,7 +676,13 @@ export function listBundles() {
                     out.push(bundle);
             }
             else {
-                const fetched = getKeychainTokens(keychainServices);
+                // Metadata enumeration must stay silent in ANY context (SEC-11):
+                // bundle metadata items are no-ACL by contract (SEC-4), so attest that
+                // to the raw-read storm guard — a headless `listBundles` (session
+                // start, crabbox env, devices fan-out) must never fail fast on the
+                // guard nor pop a sheet. (A legacy pre-heal ACL'd metadata item can
+                // still prompt once; it heals on the next interactive scan.)
+                const fetched = getKeychainTokens(keychainServices, { silentNoAcl: true });
                 const keychainBundles = [];
                 const metaJsonByName = new Map();
                 for (const service of keychainServices) {
@@ -958,8 +971,14 @@ export function resolveBundleEnv(bundle, _opts = {}) {
         }
     }
     const store = itemStore(bundle.backend ?? 'keychain');
+    // keychainStore.getBatch IS getKeychainTokens — call it directly so a
+    // `never`-policy bundle (no biometry ACL on its items) attests `silentNoAcl`
+    // and stays readable in a headless context, while an ACL'd policy hits the
+    // raw-read storm guard and fails fast there.
     const fetched = keychainItemsToFetch.length > 0
-        ? store.getBatch(keychainItemsToFetch)
+        ? (bundle.backend ?? 'keychain') === 'keychain'
+            ? getKeychainTokens(keychainItemsToFetch, { silentNoAcl: bundlePolicy(bundle) === 'never' })
+            : store.getBatch(keychainItemsToFetch)
         : new Map();
     const env = {};
     const owners = new Map();
@@ -998,61 +1017,12 @@ export function resolveBundleEnv(bundle, _opts = {}) {
 }
 /**
  * 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`, `teams`, or `terminal` — i.e. ANY agent
- *     launch, interactive included, and inherited by everything spawned beneath
- *     one (set on the child env by `agents run --headless`, scheduled routines,
- *     teammates, and interactive runs — see exec.ts:430, 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 `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
- *
- * 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 broker-only pattern used across the headless secrets readers.
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen.
+ * Re-exported from ./headless.js — the detector lives there so the raw-read
+ * path in index.ts can share it without a bundles↔index import cycle. See that
+ * module for the full contract.
  */
-export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
-// Injected so the TTY branch below is testable: it is the branch that decides a
-// plain human shell still prompts, which is this guard's entire safety argument,
-// and reading process.* directly made it unreachable from a test.
-tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
-    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;
-    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
-    // `terminal` was missing, which made an agent terminal the one launch path
-    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
-    // interactive run (exec.ts:430), that fell through to the TTY check below, and
-    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
-    // opening a terminal is not a request to authenticate, and a launch that needs
-    // a locked bundle should say so and point at `agents secrets unlock`, not grab
-    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
-    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
-    // correctly: there the agent, not the human, is the caller. A plain shell carries
-    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
-    const runtime = env.AGENTS_RUNTIME;
-    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
-        return true;
-    return !tty.stdin && !tty.stdout;
-}
+export { isHeadlessSecretsContext } from './headless.js';
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -1142,13 +1112,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     // guard never fires, and they still get their prompt. No caller passes this flag;
     // it remains the seam for a future unlock path that wants the sheet on purpose.
     const interactiveUnlock = opts.interactiveUnlock ?? false;
+    // A `never`-policy bundle's items carry no biometry ACL, so once the policy
+    // check below proves that, the batch read is silent even in a headless
+    // context — attest it to the raw-read storm guard via `silentNoAcl`.
+    let verifiedNoAclBundle = false;
     if (opts.agentOnly && backend === 'keychain' && !interactiveUnlock) {
-        let noAclBundle = false;
         try {
-            noAclBundle = bundlePolicy(readBundle(name)) === 'never';
+            verifiedNoAclBundle = bundlePolicy(readBundle(name)) === 'never';
         }
         catch { /* fail closed */ }
-        if (!noAclBundle) {
+        if (!verifiedNoAclBundle) {
             throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent. ` +
                 `Run 'agents secrets unlock ${name}' in a terminal first — an agent launch ` +
                 `never raises a Touch ID sheet on its own.`);
@@ -1184,6 +1157,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
             defaultPolicy: secretsDefaultPolicy(),
             forceDuration: Boolean(opts.duration),
+            silentNoAcl: verifiedNoAclBundle,
         })
         : store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);

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

@@ -0,0 +1,39 @@
+/**
+ * The headless-context detector shared by every secrets read path that could
+ * raise a macOS Touch ID sheet: bundle resolution (bundles.ts) and raw item
+ * reads (index.ts). It lives in its own module so index.ts can use it without
+ * importing bundles.ts (which already imports index.ts).
+ */
+/**
+ * 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`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, 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 `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
+ *
+ * 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 broker-only pattern used across the headless secrets readers.
+ */
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
+    stdin?: boolean;
+    stdout?: boolean;
+}): boolean;

package/dist/lib/secrets/headless.js

@@ -0,0 +1,63 @@
+/**
+ * The headless-context detector shared by every secrets read path that could
+ * raise a macOS Touch ID sheet: bundle resolution (bundles.ts) and raw item
+ * reads (index.ts). It lives in its own module so index.ts can use it without
+ * importing bundles.ts (which already imports index.ts).
+ */
+/**
+ * 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`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, 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 `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
+ *
+ * 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 broker-only pattern used across the headless secrets readers.
+ */
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
+// Injected so the TTY branch below is testable: it is the branch that decides a
+// plain human shell still prompts, which is this guard's entire safety argument,
+// and reading process.* directly made it unreachable from a test.
+tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
+    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;
+    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
+    // `terminal` was missing, which made an agent terminal the one launch path
+    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
+    // interactive run (exec.ts:430), that fell through to the TTY check below, and
+    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
+    // opening a terminal is not a request to authenticate, and a launch that needs
+    // a locked bundle should say so and point at `agents secrets unlock`, not grab
+    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
+    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
+    // correctly: there the agent, not the human, is the caller. A plain shell carries
+    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
+    const runtime = env.AGENTS_RUNTIME;
+    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
+        return true;
+    return !tty.stdin && !tty.stdout;
+}

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

@@ -217,7 +217,17 @@ export interface KeychainReadContext {
     duration?: string;
     defaultPolicy?: 'hold' | 'always' | 'never';
     forceDuration?: boolean;
+    /**
+     * The caller attests the item(s) carry NO biometry ACL (it wrote them with
+     * `setKeychainToken(..., { noAcl: true })`, or they are bundle metadata /
+     * `never`-policy bundle items, which are no-ACL by contract) — so the read
+     * is silent even when no one is at the screen. Skips the headless fail-fast
+     * and the back-off memo. Never pass this for an ACL-protected item: that
+     * re-opens the background Touch ID storm the guard exists to stop.
+     */
+    silentNoAcl?: boolean;
 }
+export declare function setKeychainHeadlessDetectorForTest(detector: (() => boolean) | null): void;
 export declare function keychainOperationPrompt(context?: KeychainReadContext): string;
 export declare function getKeychainToken(item: string, context?: KeychainReadContext): string;
 /**

package/dist/lib/secrets/index.js

@@ -29,6 +29,8 @@ import * as os from 'os';
 import * as path from 'path';
 import { linuxBackend, usesFileFallback as linuxUsesFileFallback, importNativeSecretToolItems } from './linux.js';
 import { windowsBackend, usesFileFallback as windowsUsesFileFallback, importNativeCredManItems } from './windows.js';
+import { isHeadlessSecretsContext } from './headless.js';
+import { KEYCHAIN_READ_BACKOFF_TTL_MS, clearKeychainReadBackoff, isKeychainReadBackedOff, noteKeychainReadFailure, } from './read-backoff.js';
 import { getKeychainHelperPath } from './install-helper.js';
 import { deriveShortId } from '../session/short-id.js';
 const SERVICE_PREFIX = 'agents-cli';
@@ -236,10 +238,11 @@ function parseHmacKeyRecord(raw) {
 function readHmacKeyRecord() {
     // HMAC_KEY_ITEM is exempt from the transform, so this routes to the helper
     // (or the test backend) under its literal name. The item is no-ACL, so the
-    // read is silent.
+    // read is silent — attest that to the storm guard so a headless hashed-name
+    // resolution never trips the fail-fast.
     let raw;
     try {
-        raw = getKeychainToken(HMAC_KEY_ITEM);
+        raw = getKeychainToken(HMAC_KEY_ITEM, { silentNoAcl: true });
     }
     catch {
         return null;
@@ -707,6 +710,56 @@ export function hasKeychainToken(item) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
+/**
+ * The detector the raw-read storm guard consults, overridable so tests on any
+ * platform exercise the fail-fast path — the real detector self-gates to
+ * darwin (the only platform with a Touch ID sheet to suppress), which would
+ * make the throw unreachable from a Linux CI run. Same parameterization
+ * argument as the injected env/platform/tty on isHeadlessSecretsContext.
+ */
+let rawReadHeadlessDetector = () => isHeadlessSecretsContext();
+export function setKeychainHeadlessDetectorForTest(detector) {
+    rawReadHeadlessDetector = detector ?? (() => isHeadlessSecretsContext());
+}
+/**
+ * The raw-read storm guard, consulted by every getKeychainToken /
+ * getKeychainTokens read that could reach a prompting keychain query. Two
+ * fail-fast gates, both skipped for `silentNoAcl` (provably prompt-free)
+ * reads:
+ *
+ *  1. Headless fail-fast. A non-interactive process (AGENTS_RUNTIME set, or
+ *     no TTY — see isHeadlessSecretsContext) must NEVER raise a Touch ID sheet
+ *     on the interactive user's screen: the sheet has no one to answer it, a
+ *     polling caller re-raises it every few seconds, and a cancel just feeds
+ *     the next poll. Throw an actionable error naming the item instead.
+ *  2. Back-off. A read whose prompt recently failed or was cancelled is
+ *     suppressed for KEYCHAIN_READ_BACKOFF_TTL_MS so an interactive-context
+ *     poller (TTY but unwatched — a tmux pane, a VS Code task terminal) can't
+ *     storm sheets either. A successful read or write clears the memo.
+ *
+ * Placement note: this runs BEFORE the platform branches so the back-off memo
+ * is honored identically everywhere, and the headless gate is a no-op off
+ * darwin (the detector returns false there) — Linux/Windows reads never
+ * prompt, so there is nothing to guard.
+ */
+function assertRawKeychainReadAllowed(key, context, label) {
+    if (context.silentNoAcl)
+        return;
+    const what = label ?? `Keychain item '${key}'`;
+    if (rawReadHeadlessDetector()) {
+        const hint = context.bundle
+            ? `Run 'agents secrets unlock ${context.bundle}' in a terminal first`
+            : `Provision a prompt-free credential for headless use (a file-based setup token, or an item stored without the biometry ACL), ` +
+                `or read it once from an interactive terminal`;
+        throw new Error(`${what} requires Touch ID, but this process is non-interactive — ` +
+            `a prompt would appear on screen with no one to answer it. ${hint}.`);
+    }
+    if (isKeychainReadBackedOff(key)) {
+        throw new Error(`${what} is in read back-off: a Touch ID prompt for it failed or was cancelled within the last ` +
+            `${Math.round(KEYCHAIN_READ_BACKOFF_TTL_MS / 60000)} minutes, and retrying is suppressed so a polling caller can't storm prompts. ` +
+            `Read it once interactively or wait out the back-off.`);
+    }
+}
 export function keychainOperationPrompt(context = {}) {
     const agent = context.agent || 'Agents CLI';
     const bundle = context.bundle ? ` the '${context.bundle}' bundle` : ' secrets';
@@ -724,6 +777,7 @@ export function getKeychainToken(item, context = {}) {
     item = prepareServiceName(item, { autoRekey: true });
     if (backend)
         return backend.get(item);
+    assertRawKeychainReadAllowed(requested, context);
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.get(item);
@@ -735,8 +789,10 @@ export function getKeychainToken(item, context = {}) {
         });
         if (sec.status === 0) {
             const token = sec.stdout?.toString().trim();
-            if (token)
+            if (token) {
+                clearKeychainReadBackoff(requested);
                 return token;
+            }
         }
         throw new Error(`Keychain item '${requested}' not found.`);
     }
@@ -749,17 +805,24 @@ export function getKeychainToken(item, context = {}) {
         },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
+    // Exit 1 is a plain miss — no prompt was raised, so it opens no back-off.
     if (result.status === 1)
         throw new Error(`Keychain item '${requested}' not found.`);
-    if (result.status === 4)
-        throw new Error(`Touch ID cancelled while reading '${requested}'.`);
     if (result.status !== 0) {
+        // A cancel (4) or helper failure after a prompted read: open the back-off
+        // window BEFORE throwing, so the next poll of the same item fails fast
+        // instead of re-raising the sheet.
+        if (!context.silentNoAcl)
+            noteKeychainReadFailure(requested);
+        if (result.status === 4)
+            throw new Error(`Touch ID cancelled while reading '${requested}'.`);
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to read keychain item '${requested}'.`);
     }
     const token = result.stdout?.toString();
     if (!token)
         throw new Error(`Keychain item '${requested}' exists but is empty.`);
+    clearKeychainReadBackoff(requested);
     return token;
 }
 /**
@@ -798,6 +861,13 @@ export function getKeychainTokens(items, context = {}) {
         }
         return result;
     }
+    // One back-off memo covers the whole batch: the batch raises at most one
+    // prompt, so a cancel/failure suppresses retrying the same batch, keyed by
+    // the requested names (never the storage hashes) for a stable identity. The
+    // guard runs before the platform branches so the headless fail-fast is
+    // exercisable on any platform (the real detector self-gates to darwin).
+    const backoffKey = `batch:${items.join('\n')}`;
+    assertRawKeychainReadAllowed(backoffKey, context, `Batch read of ${items.length} keychain item(s)`);
     assertSupportedPlatform();
     if (isLinux()) {
         for (const storage of storageItems) {
@@ -830,6 +900,8 @@ export function getKeychainTokens(items, context = {}) {
         },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
+    if (child.status !== 0 && !context.silentNoAcl)
+        noteKeychainReadFailure(backoffKey);
     if (child.status === 4) {
         throw new Error(`Touch ID cancelled while reading ${items.length} keychain item(s).`);
     }
@@ -837,6 +909,7 @@ export function getKeychainTokens(items, context = {}) {
         const msg = child.stderr?.toString().trim();
         throw new Error(msg || `Failed to batch-read ${items.length} keychain items.`);
     }
+    clearKeychainReadBackoff(backoffKey);
     const out = child.stdout?.toString() ?? '';
     parseBatchRecords(out, record);
     return result;
@@ -917,6 +990,7 @@ export function setKeychainToken(item, value, opts) {
     // resolve the storage name.
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
+    const requested = item;
     item = prepareServiceName(item, { autoRekey: true });
     if (backend) {
         backend.set(item, value, opts);
@@ -968,6 +1042,7 @@ export function setKeychainToken(item, value, opts) {
             const msg = sec.stderr?.toString().trim();
             throw new Error(msg || `Failed to write keychain item '${item}'.`);
         }
+        clearKeychainReadBackoff(requested);
         return;
     }
     const bin = getKeychainHelperPath();
@@ -989,9 +1064,13 @@ export function setKeychainToken(item, value, opts) {
         }
         throw new Error(msg || `Failed to write keychain item '${item}'.`);
     }
+    // A successful write supersedes any open back-off: the item is known-good
+    // now, so the next read must not be suppressed by a stale failure memo.
+    clearKeychainReadBackoff(requested);
 }
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export function deleteKeychainToken(item) {
+    const requested = item;
     item = prepareServiceName(item);
     if (backend)
         return backend.delete(item);
@@ -1001,9 +1080,14 @@ export function deleteKeychainToken(item) {
     if (isWindows())
         return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
-    return spawnSync(bin, ['delete', item, os.userInfo().username], {
+    const deleted = spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
+    // A deleted item must fail its next read as plain "not found", not with a
+    // stale back-off error left over from a pre-delete cancel.
+    if (deleted)
+        clearKeychainReadBackoff(requested);
+    return deleted;
 }
 /**
  * True when the active keychain backend transparently routes reads/writes to

package/dist/lib/secrets/read-backoff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Negative memo for failed/cancelled macOS keychain reads (the "back-off").
+ *
+ * A cancelled Touch ID sheet is the user saying "not now" — but a polling
+ * caller (the Factory extension host's `agents view` loop, a watch script)
+ * retries the same read a few seconds later and pops the sheet again, forever.
+ * The headless guard (index.ts `assertRawKeychainReadAllowed`) covers the
+ * no-TTY case; this memo covers a context that CAN prompt but just had its
+ * prompt cancelled or fail: the next read of the same item within the TTL
+ * throws the back-off error instead of re-prompting. Any successful read (or
+ * write) of the item clears the memo.
+ *
+ * Stored as regenerable state under `~/.agents/.cache/keychain-read-backoff/`,
+ * one file per item (filename is a hash of the item name; the file carries no
+ * secret material — a name and a deadline only). All operations are
+ * best-effort: a lost memo costs at most one extra prompt, never a read.
+ */
+/** How long a failed/cancelled read suppresses retries of the same item. */
+export declare const KEYCHAIN_READ_BACKOFF_TTL_MS: number;
+/** Test seam: point the memo at a temp dir so tests never touch the real cache. */
+export declare function setKeychainReadBackoffDirForTest(dir: string | null): void;
+/** True while `key` is inside the back-off window opened by a failed/cancelled read. */
+export declare function isKeychainReadBackedOff(key: string, now?: number): boolean;
+/** Open (or refresh) the back-off window for `key` after a failed/cancelled read. */
+export declare function noteKeychainReadFailure(key: string, now?: number): void;
+/** Clear the memo: a successful read or write of the item resets the back-off. */
+export declare function clearKeychainReadBackoff(key: string): void;

package/dist/lib/secrets/read-backoff.js

@@ -0,0 +1,64 @@
+/**
+ * Negative memo for failed/cancelled macOS keychain reads (the "back-off").
+ *
+ * A cancelled Touch ID sheet is the user saying "not now" — but a polling
+ * caller (the Factory extension host's `agents view` loop, a watch script)
+ * retries the same read a few seconds later and pops the sheet again, forever.
+ * The headless guard (index.ts `assertRawKeychainReadAllowed`) covers the
+ * no-TTY case; this memo covers a context that CAN prompt but just had its
+ * prompt cancelled or fail: the next read of the same item within the TTL
+ * throws the back-off error instead of re-prompting. Any successful read (or
+ * write) of the item clears the memo.
+ *
+ * Stored as regenerable state under `~/.agents/.cache/keychain-read-backoff/`,
+ * one file per item (filename is a hash of the item name; the file carries no
+ * secret material — a name and a deadline only). All operations are
+ * best-effort: a lost memo costs at most one extra prompt, never a read.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** How long a failed/cancelled read suppresses retries of the same item. */
+export const KEYCHAIN_READ_BACKOFF_TTL_MS = 5 * 60 * 1000;
+let dirOverride = null;
+/** Test seam: point the memo at a temp dir so tests never touch the real cache. */
+export function setKeychainReadBackoffDirForTest(dir) {
+    dirOverride = dir;
+}
+function backoffDir() {
+    return dirOverride ?? path.join(os.homedir(), '.agents', '.cache', 'keychain-read-backoff');
+}
+function backoffFile(key) {
+    const digest = createHash('sha256').update(key).digest('hex').slice(0, 24);
+    return path.join(backoffDir(), `${digest}.json`);
+}
+/** True while `key` is inside the back-off window opened by a failed/cancelled read. */
+export function isKeychainReadBackedOff(key, now = Date.now()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(backoffFile(key), 'utf8'));
+        return typeof parsed.until === 'number' && parsed.until > now;
+    }
+    catch {
+        return false; // absent or malformed memo → no back-off
+    }
+}
+/** Open (or refresh) the back-off window for `key` after a failed/cancelled read. */
+export function noteKeychainReadFailure(key, now = Date.now()) {
+    try {
+        fs.mkdirSync(backoffDir(), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(backoffFile(key), JSON.stringify({ item: key, until: now + KEYCHAIN_READ_BACKOFF_TTL_MS }), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort — the cache dir is regenerable; a lost memo costs one prompt */
+    }
+}
+/** Clear the memo: a successful read or write of the item resets the back-off. */
+export function clearKeychainReadBackoff(key) {
+    try {
+        fs.rmSync(backoffFile(key), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}

package/dist/lib/secrets/session-store.js

@@ -89,7 +89,8 @@ function sessionBlobItem(name, harness) {
 /** Read the session index by its fixed name. `{bundles:{}}` when absent/unreadable. */
 export function readIndex() {
     try {
-        const raw = getKeychainToken(SESSION_INDEX_ITEM);
+        // Written no-ACL (writeIndex below) — attest so a headless resolve stays silent.
+        const raw = getKeychainToken(SESSION_INDEX_ITEM, { silentNoAcl: true });
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && parsed.bundles)
             return parsed;
@@ -145,7 +146,8 @@ export function loadSession(name, now = Date.now(), harness = GLOBAL_HARNESS) {
     if (!shouldPersist())
         return null;
     try {
-        const raw = getKeychainToken(sessionBlobItem(name, harness));
+        // Written no-ACL (saveSession) — attest so a headless resolve stays silent.
+        const raw = getKeychainToken(sessionBlobItem(name, harness), { silentNoAcl: true });
         const entry = JSON.parse(raw);
         if (!entry || typeof entry !== 'object' || !entry.bundle || !entry.env)
             return null;
@@ -227,7 +229,7 @@ export function rehydrateSessions(now = Date.now()) {
             if (key.includes(':'))
                 continue;
             try {
-                const raw = getKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                const raw = getKeychainToken(`${SESSION_ITEM_PREFIX}${key}`, { silentNoAcl: true });
                 const legacy = JSON.parse(raw);
                 setKeychainToken(sessionBlobItem(key, GLOBAL_HARNESS), JSON.stringify({ ...legacy, harness: GLOBAL_HARNESS }), { noAcl: true });
                 deleteKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
@@ -265,7 +267,7 @@ export function rehydrateSessions(now = Date.now()) {
                 continue;
             }
             try {
-                const raw = getKeychainToken(sessionBlobItem(bundleName, 'cli'));
+                const raw = getKeychainToken(sessionBlobItem(bundleName, 'cli'), { silentNoAcl: true });
                 const legacy = JSON.parse(raw);
                 setKeychainToken(sessionBlobItem(bundleName, GLOBAL_HARNESS), JSON.stringify({ ...legacy, harness: GLOBAL_HARNESS }), { noAcl: true });
                 deleteKeychainToken(sessionBlobItem(bundleName, 'cli'));

package/dist/lib/secrets/vault.js

@@ -209,7 +209,9 @@ export function clearVaultKey() {
 export function getVaultSession() {
     let raw;
     try {
-        raw = getKeychainToken(VAULT_SESSION_ITEM);
+        // Written no-ACL (cacheVaultKey) — the vault session probe runs inside bundleBackend
+        // for EVERY bundle op, headless included, so it must stay silent.
+        raw = getKeychainToken(VAULT_SESSION_ITEM, { silentNoAcl: true });
     }
     catch {
         return { loggedIn: false };

package/dist/lib/usage.js

@@ -1246,7 +1246,9 @@ function claudeOauthCacheActive() {
  * or the token itself has expired — in which case the stale entry is dropped. */
 function readCachedClaudeOauth(service) {
     try {
-        const entry = JSON.parse(getKeychainToken(claudeOauthCacheItem(service)));
+        // The cache item is written no-ACL (writeCachedClaudeOauth) — its whole purpose is
+        // serving the token prompt-free, so attest that to the raw-read storm guard.
+        const entry = JSON.parse(getKeychainToken(claudeOauthCacheItem(service), { silentNoAcl: true }));
         if (!entry || typeof entry.accessToken !== 'string' || !entry.accessToken)
             return null;
         const now = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.3",
+  "version": "1.22.4",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",