@phnx-labs/agents-cli 1.20.74 → 1.20.77

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

@@ -114,6 +114,32 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
  */
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
+/**
+ * Thrown by `readBundle` for the one state `readBundleIfDecryptable` may treat
+ * as "present but permanently unreadable": file-store ciphertext on disk that
+ * will not decrypt with the passphrase in effect (lost/rotated key or a tampered
+ * store). It is deliberately narrow — a bundle that is merely *locked for this
+ * run* (headless macOS without `AGENTS_SECRETS_PASSPHRASE`, or a vault that is
+ * not logged in) is recoverable and must not be collapsed into this.
+ */
+export declare class BundleUndecryptableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read a bundle, or return null when its metadata is present but genuinely
+ * cannot be decrypted — a lost or rotated file-store passphrase, or a tampered
+ * file store (signalled by `BundleUndecryptableError`).
+ *
+ * Deleting such a bundle is the only way out of that state, and deletion needs
+ * no plaintext, so it must not be gated behind a successful decrypt. Every other
+ * failure rethrows: a genuinely missing bundle ("not found"), and — critically —
+ * a bundle that is only *temporarily locked* for this run (headless macOS with no
+ * `AGENTS_SECRETS_PASSPHRASE`, or a not-logged-in vault). Collapsing that
+ * recoverable "set the env / log in" state into "unreadable, safe to delete"
+ * would let `secrets delete <name> --yes` silently destroy a perfectly healthy
+ * bundle from a cron/launchd run that merely forgot to export the passphrase.
+ */
+export declare function readBundleIfDecryptable(name: string): SecretsBundle | null;
 export declare function readBundle(name: string): SecretsBundle;
 /** The default prompt policy applied to bundles without an explicit per-bundle
  * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
@@ -147,6 +173,14 @@ export declare function shouldEvictAfterBundleWrite(skipRequested: boolean, noAg
 export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function writeBundleWithItems(bundle: SecretsBundle, items: Map<string, string>, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
+/**
+ * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
+ * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just
+ * batch-read, so writing it back only flips the ACL (via the helper's
+ * delete-then-add `set-no-acl`) — contents and updated_at are preserved and no
+ * extra keychain read is issued. Exported for tests. Returns the count healed.
+ */
+export declare function healKeychainBundleMetadata(metaJsonByName: Map<string, string>): number;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
     key: string;
@@ -164,6 +198,12 @@ export interface ResolveBundleOptions {
      * about to read the bundle.
      */
     caller?: string;
+    /** Harness type whose unlock may be reused (claude, codex, kimi, ...). */
+    agent?: string;
+    /** Human duration rendered in the Touch ID prompt. */
+    duration?: string;
+    /** Explicitly permit this agent request to raise interactive authentication. */
+    interactiveUnlock?: boolean;
     /**
      * Skip the secrets-agent fast-path and read straight from the keychain
      * (popping Touch ID). Set by callers that must NOT serve a cached snapshot —
@@ -238,15 +278,19 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  * 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).
+ *   - `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 interactive `eval "$(agents secrets export X)"`
- * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ * 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) /
@@ -259,7 +303,10 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  * 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;
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
+    stdin?: boolean;
+    stdout?: boolean;
+}): boolean;
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -277,6 +324,7 @@ export declare function readAndResolveBundleEnv(name: string, opts?: ResolveBund
     bundle: SecretsBundle;
     env: Record<string, string>;
 };
+export declare function humanUnlockDuration(ms: number): string;
 export declare function keychainRef(key: string): string;
 /** Options for rotateBundleSecret. */
 export interface RotateOptions {

package/dist/lib/secrets/bundles.js

@@ -28,7 +28,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { getVaultSession, vaultDeleteItem, vaultExists, vaultGetItems, vaultGetItem, vaultHasItem, vaultListItems, vaultSetItems, vaultSetItem, } from './vault.js';
 import { emit } from '../events.js';
-import { readMeta } from '../state.js';
+import { readMeta, getHelpersDir } from '../state.js';
 import { assertNameActiveInResourceProfile, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
 import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
 import { loadSession, deleteSession } from './session-store.js';
@@ -243,6 +243,44 @@ export function bundleExists(name) {
     validateBundleName(name);
     return itemStore(bundleBackend(name)).has(bundleMetaItem(name));
 }
+/**
+ * Thrown by `readBundle` for the one state `readBundleIfDecryptable` may treat
+ * as "present but permanently unreadable": file-store ciphertext on disk that
+ * will not decrypt with the passphrase in effect (lost/rotated key or a tampered
+ * store). It is deliberately narrow — a bundle that is merely *locked for this
+ * run* (headless macOS without `AGENTS_SECRETS_PASSPHRASE`, or a vault that is
+ * not logged in) is recoverable and must not be collapsed into this.
+ */
+export class BundleUndecryptableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BundleUndecryptableError';
+    }
+}
+/**
+ * Read a bundle, or return null when its metadata is present but genuinely
+ * cannot be decrypted — a lost or rotated file-store passphrase, or a tampered
+ * file store (signalled by `BundleUndecryptableError`).
+ *
+ * Deleting such a bundle is the only way out of that state, and deletion needs
+ * no plaintext, so it must not be gated behind a successful decrypt. Every other
+ * failure rethrows: a genuinely missing bundle ("not found"), and — critically —
+ * a bundle that is only *temporarily locked* for this run (headless macOS with no
+ * `AGENTS_SECRETS_PASSPHRASE`, or a not-logged-in vault). Collapsing that
+ * recoverable "set the env / log in" state into "unreadable, safe to delete"
+ * would let `secrets delete <name> --yes` silently destroy a perfectly healthy
+ * bundle from a cron/launchd run that merely forgot to export the passphrase.
+ */
+export function readBundleIfDecryptable(name) {
+    try {
+        return readBundle(name);
+    }
+    catch (err) {
+        if (err instanceof BundleUndecryptableError)
+            return null;
+        throw err;
+    }
+}
 export function readBundle(name) {
     validateBundleName(name);
     const backend = bundleBackend(name);
@@ -258,7 +296,7 @@ export function readBundle(name) {
         // A file-backed bundle whose metadata is on disk but fails to decrypt is a
         // wrong-passphrase error, not a missing bundle — surface that clearly.
         if (backend === 'file' && fileStore.has(bundleMetaItem(name))) {
-            throw new Error(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
+            throw new BundleUndecryptableError(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
         }
         if (vaultExists() && !getVaultSession().loggedIn) {
             throw new Error(`Synced secrets are locked. Run: agents login`);
@@ -429,18 +467,40 @@ function finishBundleWrite(bundle, opts) {
 }
 export function writeBundle(bundle, opts = {}) {
     const prepared = prepareBundleWrite(bundle);
-    // A `never` bundle's metadata is stored without the biometry ACL too, so
-    // `view` and the metadata half of a read resolve silently — the whole point
-    // of the tier. On an un-updated pinned helper this write fails loudly (the
-    // no-ACL command is missing) rather than silently landing an ACL'd item.
-    itemStore(prepared.backend).set(prepared.metadataItem, prepared.metadataJson, { noAcl: bundle.policy === 'never' });
+    // Bundle metadata (name, description, policy, var names + refs, and any
+    // non-sensitive `--value` literals) is stored WITHOUT the biometry ACL at
+    // EVERY tier. It is non-sensitive by contract — the real secret values live in
+    // separate agents-cli.secrets.* items that keep the bundle's policy ACL — so a
+    // no-ACL metadata item is what lets `secrets list` and crabbox's `agents
+    // devices list` enumerate bundles with no Touch ID prompt (RUSH-1759). On an
+    // un-updated pinned helper this write fails loudly (the no-ACL command is
+    // missing) rather than silently landing an ACL'd item.
+    itemStore(prepared.backend).set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
     finishBundleWrite(bundle, opts);
 }
 export function writeBundleWithItems(bundle, items, opts = {}) {
     const prepared = prepareBundleWrite(bundle);
-    const batch = new Map(items);
-    batch.set(prepared.metadataItem, prepared.metadataJson);
-    itemStore(prepared.backend).setBatch(batch, { noAcl: bundle.policy === 'never' });
+    const store = itemStore(prepared.backend);
+    if (prepared.backend === 'keychain') {
+        // Only the keychain backend has a biometry ACL. Secret VALUE items carry the
+        // bundle's policy ACL (`never` ⇒ no-ACL); the metadata item is ALWAYS no-ACL
+        // (see writeBundle). The two must NOT ride one batch flag — a single noAcl
+        // over both would either strip biometry off the real secrets or re-ACL the
+        // metadata. Write the values first, then the metadata last: bundle discovery
+        // keys on the metadata item's presence, so metadata-last means a partial
+        // write reads as "no bundle yet", never as a bundle with missing values.
+        if (items.size > 0) {
+            store.setBatch(new Map(items), { noAcl: bundle.policy === 'never' });
+        }
+        store.set(prepared.metadataItem, prepared.metadataJson, { noAcl: true });
+    }
+    else {
+        // file / vault: no ACL concept (noAcl is ignored), so one batched write is
+        // both correct and cheaper — e.g. a single age re-encrypt for the vault.
+        const batch = new Map(items);
+        batch.set(prepared.metadataItem, prepared.metadataJson);
+        store.setBatch(batch, { noAcl: bundle.policy === 'never' });
+    }
     finishBundleWrite(bundle, opts);
 }
 export function deleteBundle(name) {
@@ -503,6 +563,79 @@ function parseBundleMeta(nameHint, json, backend) {
     }
     return bundle;
 }
+// Sentinel marking the one-time RUSH-1759 metadata-ACL heal as done. Lives under
+// the regenerable helpers dir (same tree as the secrets-agent runtime state), so
+// a cache wipe just re-runs the heal — harmless, since it is idempotent.
+const METADATA_NOACL_SENTINEL = 'bundles-metadata-noacl-healed';
+function metadataNoAclSentinelPath() {
+    return path.join(getHelpersDir(), 'secrets-agent', METADATA_NOACL_SENTINEL);
+}
+function bundleMetadataAclHealed() {
+    try {
+        return fs.existsSync(metadataNoAclSentinelPath());
+    }
+    catch {
+        return false;
+    }
+}
+function markBundleMetadataAclHealed() {
+    try {
+        const file = metadataNoAclSentinelPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, '', 'utf8');
+    }
+    catch {
+        // Best effort — a missing sentinel just means the (idempotent) heal re-runs
+        // on the next broker-miss listing.
+    }
+}
+/**
+ * Re-write already-read keychain bundle metadata items WITHOUT the biometry ACL.
+ * `metaJsonByName` maps bundle name → the exact metadata JSON listBundles just
+ * batch-read, so writing it back only flips the ACL (via the helper's
+ * delete-then-add `set-no-acl`) — contents and updated_at are preserved and no
+ * extra keychain read is issued. Exported for tests. Returns the count healed.
+ */
+export function healKeychainBundleMetadata(metaJsonByName) {
+    let healed = 0;
+    for (const [name, json] of metaJsonByName) {
+        try {
+            // Cleartext meta-item name → hashed by keychainStore.set (#316) to the same
+            // service the read enumerated, so this overwrites the existing item in
+            // place, no-ACL. A per-item failure (e.g. a pinned helper without
+            // set-no-acl) must not abort the rest.
+            keychainStore.set(bundleMetaItem(name), json, { noAcl: true });
+            healed++;
+        }
+        catch {
+            /* keep healing the remaining items */
+        }
+    }
+    return healed;
+}
+/**
+ * One-time driver around healKeychainBundleMetadata (RUSH-1759). macOS + real
+ * keychain only — libsecret/CredMan have no biometry ACL to shed, and a test
+ * backend has no real keychain — and gated by a sentinel so it runs at most
+ * once. Best-effort: a heal failure never breaks bundle listing.
+ */
+function healKeychainBundleMetadataAclOnce(metaJsonByName) {
+    if (metaJsonByName.size === 0)
+        return;
+    if (process.platform !== 'darwin')
+        return;
+    if (isKeychainBackendOverridden())
+        return;
+    if (bundleMetadataAclHealed())
+        return;
+    try {
+        if (healKeychainBundleMetadata(metaJsonByName) > 0)
+            markBundleMetadataAclHealed();
+    }
+    catch {
+        /* never let a heal failure break `secrets list` */
+    }
+}
 export function listBundles() {
     const out = [];
     // Keychain-backed bundles: batch all metadata reads behind ONE Touch ID
@@ -558,6 +691,7 @@ export function listBundles() {
             else {
                 const fetched = getKeychainTokens(keychainServices);
                 const keychainBundles = [];
+                const metaJsonByName = new Map();
                 for (const service of keychainServices) {
                     const json = fetched.get(service);
                     if (json === undefined)
@@ -566,8 +700,10 @@ export function listBundles() {
                         ? service.slice(BUNDLE_META_PREFIX.length)
                         : undefined;
                     const bundle = parseBundleMeta(nameHint, json, 'keychain');
-                    if (bundle)
+                    if (bundle) {
                         keychainBundles.push(bundle);
+                        metaJsonByName.set(bundle.name, json);
+                    }
                 }
                 for (const bundle of keychainBundles)
                     out.push(bundle);
@@ -578,6 +714,13 @@ export function listBundles() {
                 if (useAgent && keychainBundles.length > 0) {
                     agentAutoLoadMetaSync(nameSetHash, keychainBundles, secretsHoldMs());
                 }
+                // One-time RUSH-1759 heal: bundles written before the metadata-no-ACL
+                // change carry an ACL'd metadata item, so this fresh read (a broker miss)
+                // popped Touch ID just to enumerate them. Re-home each metadata item
+                // no-ACL now — reusing the JSON we just read, so the heal adds no extra
+                // prompt — and every later enumeration is silent. Runs at most once (a
+                // sentinel under the regenerable helpers dir).
+                healKeychainBundleMetadataAclOnce(metaJsonByName);
             }
         }
     }
@@ -877,15 +1020,19 @@ 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` or `teams` (set on the child env by
- *     `agents run --headless`, scheduled routines, and teammates — see
- *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - `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 interactive `eval "$(agents secrets export X)"`
- * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ * 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) /
@@ -898,7 +1045,11 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  * 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) {
+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;
@@ -906,10 +1057,21 @@ export function isHeadlessSecretsContext(env = process.env, platform = process.p
         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')
+    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
         return true;
-    return !process.stdin.isTTY && !process.stdout.isTTY;
+    return !tty.stdin && !tty.stdout;
 }
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
@@ -935,7 +1097,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     // file-backed bundle has none to dedup. The never-unlocked path is a single
     // stat (agentSocketExists) so it costs nothing when the agent isn't running.
     if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
-        const hit = agentGetSync(name);
+        const harness = opts.agent || process.env.AGENTS_AGENT_NAME || 'cli';
+        const hit = agentGetSync(name, harness);
         if (hit) {
             // The agent stores the FULL bundle env. Apply the same subset filter and
             // expiry gate as the slow path — without this, `--secrets-keys X` would
@@ -959,13 +1122,13 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         // Touch ID. Serve from it and re-warm the broker, so a warm bundle stays warm
         // across restart — this fixes BOTH the interactive re-prompt and the headless
         // throw below (which now fires only when there is genuinely no session).
-        const session = loadSession(name);
+        const session = loadSession(name, Date.now(), harness);
         if (session) {
             const filtered = filterAgentHitBySubsetAndExpiry({ bundle: session.bundle, env: session.env }, opts);
             stampLastUsed(filtered.bundle);
             // Re-warm the broker with the remaining TTL so later reads hit RAM and
             // `agents secrets status` is honest. Best-effort; no-ops off darwin.
-            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()));
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), harness);
             emit('secrets.get', {
                 module: 'secrets',
                 bundle: name,
@@ -977,15 +1140,30 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    // 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.`);
+    // Never/no-ACL bundles remain prompt-free regardless. No agent launch — harness,
+    // teammate, routine, or the always-on daemon — may raise the sheet itself.
+    // Explicit opt-in ONLY — a deliberate NARROWING of the agent-triggered approval
+    // added in RUSH-2032 (b99796f8 removed this throw so an agent could raise the
+    // sheet itself; 4eeada68 generalized the daemon rule into `!interactiveUnlock`).
+    // That default — true whenever an agent name was present — was the spec, not a
+    // bug. It is unwanted: each keychain read runs in its own helper process, so the
+    // biometric assertion never reuses and one agent launch meant one sheet per
+    // bundle. `agentOnly` decides alone now; a human in a plain shell carries no
+    // AGENTS_RUNTIME, so isHeadlessSecretsContext() is false, agentOnly is false, the
+    // 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;
+    if (opts.agentOnly && backend === 'keychain' && !interactiveUnlock) {
+        let noAclBundle = false;
+        try {
+            noAclBundle = bundlePolicy(readBundle(name)) === 'never';
+        }
+        catch { /* fail closed */ }
+        if (!noAclBundle) {
+            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.`);
+        }
     }
     if (backend === 'file')
         assertFileBackendUsable(name);
@@ -1004,12 +1182,20 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const reason = opts.caller
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
-    void reason;
     // secretItems are storage names as enumerated (opaque hashed names on macOS
     // with #316 hashing active, cleartext elsewhere); metaItem is cleartext and
     // hashed inside getBatch. Deduped because the hashed enumeration spans the
     // bundle's whole namespace.
-    const fetched = store.getBatch([...new Set([metaItem, ...secretItems])]);
+    const fetched = backend === 'keychain'
+        ? getKeychainTokens([...new Set([metaItem, ...secretItems])], {
+            agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
+            bundle: name,
+            reason: opts.caller ? `to ${opts.caller}` : reason,
+            duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
+            defaultPolicy: secretsDefaultPolicy(),
+            forceDuration: Boolean(opts.duration),
+        })
+        : store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
         // For a file-backed bundle the metadata item is on disk (that's how
@@ -1137,7 +1323,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
-            agentAutoLoadSync(name, bundle, env, secretsHoldMs());
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || 'cli');
         }
         return { bundle, env };
     }
@@ -1146,6 +1332,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         throw err;
     }
 }
+export function humanUnlockDuration(ms) {
+    const days = Math.round(ms / (24 * 60 * 60 * 1000));
+    if (days >= 1)
+        return `${days} day${days === 1 ? '' : 's'}`;
+    const hours = Math.round(ms / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    const minutes = Math.max(1, Math.round(ms / (60 * 1000)));
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
 // Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;

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

@@ -187,7 +187,21 @@ export declare function rekeyStatus(): {
      * count is then meaningless. Only probeable once the key record exists. */
     enumerationOk: boolean;
 };
-/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+/**
+ * Check if a keychain/keyring item exists. Never prompts for biometry.
+ *
+ * Throws when the item cannot be reached — on macOS, when the signed helper is
+ * unavailable. That is deliberate: this primitive gates destructive writes as
+ * well as reads. Through `bundleExists()` it guards the `--force` overwrite
+ * checks in `agents secrets create` (`../../commands/secrets.ts`), the
+ * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
+ * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
+ * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
+ * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ *
+ * Tests needing this path without a helper install a backend via
+ * `setKeychainBackendForTest()`, which short-circuits on the next line.
+ */
 export declare function hasKeychainToken(item: string): boolean;
 /**
  * Retrieve a secret value from the keychain/keyring. Throws if not found.
@@ -196,7 +210,16 @@ export declare function hasKeychainToken(item: string): boolean;
  * call in the same process). For bundles, prefer getKeychainTokens() so a
  * single biometric prompt covers every key in the batch.
  */
-export declare function getKeychainToken(item: string): string;
+export interface KeychainReadContext {
+    agent?: string;
+    bundle?: string;
+    reason?: string;
+    duration?: string;
+    defaultPolicy?: 'daily' | 'always' | 'never';
+    forceDuration?: boolean;
+}
+export declare function keychainOperationPrompt(context?: KeychainReadContext): string;
+export declare function getKeychainToken(item: string, context?: KeychainReadContext): string;
 /**
  * Batch-read multiple keychain items behind a single Touch ID prompt. The
  * macOS helper holds one LAContext for its whole process: the first protected
@@ -207,7 +230,7 @@ export declare function getKeychainToken(item: string): string;
  * On Linux or when a test backend is installed, falls back to individual
  * lookups — no biometric prompt path on those platforms.
  */
-export declare function getKeychainTokens(items: string[]): Map<string, string>;
+export declare function getKeychainTokens(items: string[], context?: KeychainReadContext): Map<string, string>;
 /** Store or update a secret value in the keychain/keyring. Device-local;
  * biometry-gated on macOS. `opts.noAcl` (the `never` prompt-policy) writes our
  * item WITHOUT the biometry access control so later reads are fully silent — it

package/dist/lib/secrets/index.js

@@ -481,8 +481,12 @@ export function computeRekeyPlan(services, values, key) {
         try {
             const parsed = JSON.parse(value);
             if (parsed && typeof parsed === 'object') {
-                const tier = parsed.tier;
-                noAcl = tier === 'none' || tier === 'never';
+                // Bundle metadata is non-sensitive by contract and stored no-ACL at
+                // EVERY tier (matches writeBundle in bundles.ts), so `secrets list` /
+                // crabbox's `agents devices list` enumerate bundles with no Touch ID
+                // (RUSH-1759). Re-home metadata no-ACL regardless of the bundle's policy;
+                // the real secret values (second loop) still carry their per-bundle ACL.
+                noAcl = true;
                 payload = JSON.stringify({ ...parsed, name });
             }
         }
@@ -669,7 +673,21 @@ export function rekeyStatus() {
         enumerationOk,
     };
 }
-/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+/**
+ * Check if a keychain/keyring item exists. Never prompts for biometry.
+ *
+ * Throws when the item cannot be reached — on macOS, when the signed helper is
+ * unavailable. That is deliberate: this primitive gates destructive writes as
+ * well as reads. Through `bundleExists()` it guards the `--force` overwrite
+ * checks in `agents secrets create` (`../../commands/secrets.ts`), the
+ * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
+ * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
+ * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
+ * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ *
+ * Tests needing this path without a helper install a backend via
+ * `setKeychainBackendForTest()`, which short-circuits on the next line.
+ */
 export function hasKeychainToken(item) {
     item = prepareServiceName(item);
     if (backend)
@@ -689,14 +707,14 @@ export function hasKeychainToken(item) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-/**
- * Retrieve a secret value from the keychain/keyring. Throws if not found.
- *
- * On macOS this triggers Touch ID (or reuses an assertion held by an earlier
- * call in the same process). For bundles, prefer getKeychainTokens() so a
- * single biometric prompt covers every key in the batch.
- */
-export function getKeychainToken(item) {
+export function keychainOperationPrompt(context = {}) {
+    const agent = context.agent || 'Agents CLI';
+    const bundle = context.bundle ? ` the '${context.bundle}' bundle` : ' secrets';
+    const duration = context.duration ? ` for ${context.duration}` : '';
+    const reason = context.reason ? ` ${context.reason}` : '';
+    return `${agent} is requesting to unlock${bundle}${duration}${reason}.`;
+}
+export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
     // an opaque hash.
     const requested = item;
@@ -721,6 +739,11 @@ export function getKeychainToken(item) {
     }
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['get', item, os.userInfo().username], {
+        env: {
+            ...process.env,
+            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.status === 1)
@@ -746,7 +769,7 @@ export function getKeychainToken(item) {
  * On Linux or when a test backend is installed, falls back to individual
  * lookups — no biometric prompt path on those platforms.
  */
-export function getKeychainTokens(items) {
+export function getKeychainTokens(items, context = {}) {
     const result = new Map();
     if (items.length === 0)
         return result;
@@ -793,6 +816,13 @@ export function getKeychainTokens(items) {
     }
     const bin = getKeychainHelperPath();
     const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...storageItems], {
+        env: {
+            ...process.env,
+            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_DEFAULT_POLICY: context.defaultPolicy || 'daily',
+            AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (child.status === 4) {