@phnx-labs/agents-cli 1.22.1 → 1.22.4

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.
  *
@@ -344,6 +319,26 @@ export interface RotateOptions {
  * unless `clearMeta` or a `meta` patch is supplied.
  */
 export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions): void;
+/**
+ * Reconcile a bundle's keychain-backed VALUE items to its CURRENT policy, then
+ * write the (always no-ACL) metadata.
+ *
+ * `writeBundle` only rewrites the metadata item, so a policy change alone leaves
+ * every value item carrying the ACL it was created with — and macOS gates each
+ * read on the ITEM's ACL, not the bundle's declared tier (spec SEC-19). Without
+ * this reconcile, `agents secrets policy <b> never` reports "silent" while the
+ * still-ACL'd value keeps popping Touch ID on every read, forever.
+ *
+ *   hold/always -> never  strips the biometry ACL (helper `set-no-acl`: delete+add)
+ *   never -> hold/always  re-attaches it (helper `set`)
+ *
+ * The current values are read in ONE batch, so the reconcile costs at most a
+ * single Touch ID — the last prompt a hold->never bundle will ever raise (a
+ * never->* flip reads silently, since the items are already no-ACL). No-op on the
+ * ACL to write for non-keychain backends (file/vault have no biometry concept),
+ * and a metadata-only write when the bundle has no keychain-backed values.
+ */
+export declare function reAclBundleItems(bundle: SecretsBundle): void;
 /** Options for renameBundle. */
 export interface RenameOptions {
     /** When true, overwrite an existing destination bundle (purges its keychain items first). */

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);
@@ -1376,6 +1350,56 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     writeBundle(bundle);
 }
+/**
+ * Reconcile a bundle's keychain-backed VALUE items to its CURRENT policy, then
+ * write the (always no-ACL) metadata.
+ *
+ * `writeBundle` only rewrites the metadata item, so a policy change alone leaves
+ * every value item carrying the ACL it was created with — and macOS gates each
+ * read on the ITEM's ACL, not the bundle's declared tier (spec SEC-19). Without
+ * this reconcile, `agents secrets policy <b> never` reports "silent" while the
+ * still-ACL'd value keeps popping Touch ID on every read, forever.
+ *
+ *   hold/always -> never  strips the biometry ACL (helper `set-no-acl`: delete+add)
+ *   never -> hold/always  re-attaches it (helper `set`)
+ *
+ * The current values are read in ONE batch, so the reconcile costs at most a
+ * single Touch ID — the last prompt a hold->never bundle will ever raise (a
+ * never->* flip reads silently, since the items are already no-ACL). No-op on the
+ * ACL to write for non-keychain backends (file/vault have no biometry concept),
+ * and a metadata-only write when the bundle has no keychain-backed values.
+ */
+export function reAclBundleItems(bundle) {
+    if ((bundle.backend ?? 'keychain') !== 'keychain') {
+        // No biometry ACL off the keychain backend — only metadata needs persisting.
+        writeBundle(bundle);
+        return;
+    }
+    const store = itemStore('keychain');
+    // keychainItemsForBundle already returns ONLY keychain-backed value items
+    // (via parseBundleValue), so no extra ref-shape filtering here.
+    const entries = keychainItemsForBundle(bundle);
+    if (entries.length === 0) {
+        // Literal/ref-only bundle: nothing to re-ACL, just refresh metadata.
+        writeBundle(bundle);
+        return;
+    }
+    // One batched read = at most one Touch ID for the whole reconcile.
+    const values = store.getBatch(entries.map((e) => e.item));
+    const rewrite = new Map();
+    for (const { item } of entries) {
+        const value = values.get(item);
+        // A key present in metadata but with no readable value item is real
+        // corruption, not something to silently skip (no fallbacks — fail loud).
+        if (value === undefined) {
+            throw new Error(`Cannot change policy for '${bundle.name}': a keychain value is missing or unreadable. Rotate that key, then retry.`);
+        }
+        rewrite.set(item, value);
+    }
+    // writeBundleWithItems re-stores each value with { noAcl: policy === 'never' }
+    // and the metadata no-ACL (metadata-last), and evicts any broker-held copy.
+    writeBundleWithItems(bundle, rewrite);
+}
 /**
  * Rename a bundle: move metadata + every keychain-backed value to a new name.
  *

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;