@phnx-labs/agents-cli 1.22.3 → 1.22.5

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;
@@ -254,6 +257,25 @@ function writeHmacKeyRecord(rec) {
     setKeychainToken(HMAC_KEY_ITEM, JSON.stringify(rec), { noAcl: true });
     hashStateCache = null;
 }
+/**
+ * Heal a `hmackey` item that an OLD helper (pre the metadata/hmackey no-ACL
+ * migration fix) re-stamped with a biometry ACL. Such an item makes EVERY hashed
+ * keychain lookup pop the generic "Agents CLI needs to authenticate" sheet,
+ * because the HMAC key is read before every hashed name resolves. The migration
+ * fix stopped the re-stamping but never un-stamped an already-damaged item, and
+ * nothing else re-stores it once hashing is already active — so it prompts forever.
+ *
+ * This re-stores the record no-ACL exactly once per machine (guarded by
+ * `healedNoAcl`), turning every future read silent. The read that produced `rec`
+ * has already happened (and already prompted if it was ACL'd); this only writes.
+ * Returns true if it healed. Exported for tests. No-op when already healed.
+ */
+export function healHmacKeyNoAclOnce(rec) {
+    if (rec.healedNoAcl)
+        return false;
+    writeHmacKeyRecord({ ...rec, healedNoAcl: true });
+    return true;
+}
 function resolveHashState() {
     if (forcedTestKey)
         return { active: true, key: forcedTestKey, record: null };
@@ -401,6 +423,19 @@ function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
+        // Heal an already-active machine whose hmackey was re-stamped ACL'd by an old
+        // helper (its read popped the generic Touch ID sheet on every hashed lookup).
+        // Runs once per machine; mutate the local so a later finishPendingDeletes write
+        // preserves the healed flag.
+        if (st.record && !st.record.healedNoAcl) {
+            try {
+                healHmacKeyNoAclOnce(st.record);
+                st.record.healedNoAcl = true;
+            }
+            catch {
+                /* next process retries */
+            }
+        }
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);
@@ -707,6 +742,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 +809,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 +821,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 +837,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 +893,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 +932,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 +941,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 +1022,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 +1074,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 +1096,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 +1112,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/mcp.js

@@ -24,7 +24,7 @@
  * unit-testable in-process.
  */
 import * as readline from 'readline';
-import { listBundles, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, validateBundleName, } from './bundles.js';
+import { listBundles, readAndResolveBundleEnv, readBundle, validateBundleName, } from './bundles.js';
 /** MCP protocol revision this server negotiates. */
 export const MCP_PROTOCOL_VERSION = '2024-11-05';
 /** The single tool this server exposes. */
@@ -68,9 +68,13 @@ export function resolveSecret(bundle, key) {
         throw new Error(`Key '${key}' not found in bundle '${bundle}'.` +
             (available.length ? ` Available keys: ${available.join(', ')}.` : ' Bundle has no keys.'));
     }
-    // The MCP get_secret tool is typically served by a background/headless agent
-    // process; resolve broker-only there so it never raises an unwatched prompt.
-    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+    // An MCP `get_secret` tool call is a program asking for a value, never a human
+    // at a Touch ID sheet — so the read is always `agentOnly` (SEC-13: never pop
+    // biometry on its own). A `never`/no-ACL or broker-held bundle resolves
+    // silently; a locked bundle THROWS the actionable "unlock <name>" message,
+    // which propagates as the MCP tool error (the caller surfaces it) rather than
+    // popping an unanswerable prompt.
+    const { env } = readAndResolveBundleEnv(bundle, { caller: 'secrets-mcp', keys: [key], keyMode: 'storage', agentOnly: true });
     const value = env[key];
     if (value === undefined) {
         throw new Error(`Key '${key}' in bundle '${bundle}' could not be resolved.`);

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/session/sync/config.d.ts

@@ -29,24 +29,25 @@ export interface R2Config {
      */
     syncEncKey?: string;
 }
-/** Window after a prompt-bearing resolution failure during which we skip
- *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
-export declare const RESOLVE_RETRY_COOLDOWN_MS: number;
 /** Drop the cached resolution so the next call reads the bundle fresh. Called on
  *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
 export declare function clearR2ConfigCache(): void;
 /**
  * Resolve R2 credentials, reading the keychain at most once per process. The
- * first call reads (and may prompt for Touch ID); every later call returns the
- * memoized result. Throws if the bundle/keys are missing — failures are not
- * memoized, but see isSyncConfigured for the re-prompt cooldown.
+ * read is `agentOnly` (resolveR2Config), so it never prompts: a `never`/no-ACL or
+ * broker-held bundle resolves silently and is memoized; a locked `hold`/`always`
+ * bundle throws the actionable "unlock r2.backups" error. Throws (not memoized)
+ * when the bundle/keys are missing or locked — isSyncConfigured catches the throw
+ * and degrades to no-transport.
  */
 export declare function loadR2Config(): R2Config;
 /**
- * True when the sync bundle exists and resolves, without throwing. After a
- * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
- * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
- * does not re-storm every cycle. `now` is injectable for tests.
+ * True when the sync bundle exists and resolves, without throwing. A missing OR
+ * locked bundle resolves to false (session-sync degrades to no-transport) and,
+ * because the `agentOnly` read never prompts, it is re-checked each cycle — so a
+ * later `agents secrets add` / `agents secrets unlock r2.backups` is picked up
+ * promptly with no daemon restart. `now` is accepted for a stable test signature
+ * but no longer gates a cooldown (there is no prompt-bearing failure to back off).
  */
-export declare function isSyncConfigured(now?: number): boolean;
+export declare function isSyncConfigured(_now?: number): boolean;
 export { machineId, normalizeHost } from '../../machine-id.js';

package/dist/lib/session/sync/config.js

@@ -11,7 +11,7 @@
  * actually wired. Credentials come from the `r2.backups` secrets bundle (OS
  * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../../secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
 /**
@@ -20,13 +20,17 @@ export const SYNC_BUNDLE = 'r2.backups';
  * without real credentials (no silent fallback).
  */
 function resolveR2Config() {
-    // A headless caller (no TTY — e.g. a routine or SSH-dispatched command) must
-    // resolve broker-only: isHeadlessSecretsContext() true means a broker miss
-    // can never pop an unattended Touch ID sheet on the user's screen (the same
-    // broker-only-when-headless rationale the secrets readers use). Using the
-    // shared predicate rather than a literal keeps it consistent with the other
-    // callers and lets any interactive caller of loadR2Config still prompt.
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: isHeadlessSecretsContext() });
+    // Session-sync is a BACKGROUND read: the daemon's ~90s cycle (and the ~2-min
+    // watchdog) resolve this on their own, never at a human's request — so it must
+    // NEVER pop a Touch ID sheet, on the interactive launcher included (SEC-13: an
+    // agent launch never raises biometry on its own). The read is always
+    // `agentOnly`: a `never`/no-ACL or broker-held `r2.backups` bundle resolves
+    // silently; a locked `hold`/`always` bundle THROWS the actionable "unlock
+    // r2.backups" message instead of prompting. isSyncConfigured catches that throw
+    // and degrades to no-transport (sync disabled) with no prompt and no crash —
+    // unlock once (`agents secrets unlock r2.backups`) or set it no-ACL
+    // (`agents secrets policy r2.backups never`) for silent zero-friction sync.
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: true });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
@@ -55,31 +59,32 @@ function resolveR2Config() {
     };
 }
 // ── Resolution cache ────────────────────────────────────────────────────────
-// The daemon calls isSyncConfigured() + syncSessions() every ~90s, and each used
-// to trigger a fresh read of the biometry-gated `r2.backups` keychain items —
-// one Touch ID prompt per gated item, every cycle, forever. We instead resolve
-// at most once per process: a success is memoized for the process lifetime
-// (cleared on daemon SIGHUP via clearR2ConfigCache), so subsequent cycles never
-// touch the keychain again. A *prompt-bearing* failure (cancelled Touch ID, etc.)
-// starts a cooldown so a dismissed prompt is not re-issued every cycle. A simply
-// absent bundle never prompts, so it is re-checked each cycle (fast pickup when
-// the user later adds credentials).
+// The daemon calls isSyncConfigured() + syncSessions() every ~90s. The read is
+// now `agentOnly` (resolveR2Config) so it can NEVER pop Touch ID — a locked bundle
+// throws a cheap, deterministic "unlock r2.backups" error instead. We still resolve
+// at most once per process: a success is memoized for the process lifetime (cleared
+// on daemon SIGHUP via clearR2ConfigCache), so subsequent cycles never touch the
+// keychain again. A failure (absent bundle, or a LOCKED `hold`/`always` bundle) is
+// NOT memoized and never prompts, so it is re-checked each cycle — session-sync
+// degrades to no-transport until the bundle is added / unlocked, then picks it up
+// promptly with no restart.
+//
+// The historical prompt-backoff cooldown (a cancelled Touch ID sheet) is gone: with
+// agentOnly there is no sheet to cancel, so no failure is prompt-bearing and none
+// needs a backoff.
 let cachedConfig = null;
-let lastPromptFailureAt = 0;
-/** Window after a prompt-bearing resolution failure during which we skip
- *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
-export const RESOLVE_RETRY_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
 /** Drop the cached resolution so the next call reads the bundle fresh. Called on
  *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
 export function clearR2ConfigCache() {
     cachedConfig = null;
-    lastPromptFailureAt = 0;
 }
 /**
  * Resolve R2 credentials, reading the keychain at most once per process. The
- * first call reads (and may prompt for Touch ID); every later call returns the
- * memoized result. Throws if the bundle/keys are missing — failures are not
- * memoized, but see isSyncConfigured for the re-prompt cooldown.
+ * read is `agentOnly` (resolveR2Config), so it never prompts: a `never`/no-ACL or
+ * broker-held bundle resolves silently and is memoized; a locked `hold`/`always`
+ * bundle throws the actionable "unlock r2.backups" error. Throws (not memoized)
+ * when the bundle/keys are missing or locked — isSyncConfigured catches the throw
+ * and degrades to no-transport.
  */
 export function loadR2Config() {
     if (cachedConfig)
@@ -88,26 +93,23 @@ export function loadR2Config() {
     return cachedConfig;
 }
 /**
- * True when the sync bundle exists and resolves, without throwing. After a
- * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
- * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
- * does not re-storm every cycle. `now` is injectable for tests.
+ * True when the sync bundle exists and resolves, without throwing. A missing OR
+ * locked bundle resolves to false (session-sync degrades to no-transport) and,
+ * because the `agentOnly` read never prompts, it is re-checked each cycle — so a
+ * later `agents secrets add` / `agents secrets unlock r2.backups` is picked up
+ * promptly with no daemon restart. `now` is accepted for a stable test signature
+ * but no longer gates a cooldown (there is no prompt-bearing failure to back off).
  */
-export function isSyncConfigured(now = Date.now()) {
+export function isSyncConfigured(_now = Date.now()) {
     if (cachedConfig)
         return true;
-    if (lastPromptFailureAt && now - lastPromptFailureAt < RESOLVE_RETRY_COOLDOWN_MS)
-        return false;
     try {
         loadR2Config();
         return true;
     }
-    catch (err) {
-        // A missing bundle never prompts, so keep re-checking it each cycle (so a
-        // later `agents secrets add` is picked up quickly). Any other failure may
-        // have cost a prompt (cancelled Touch ID, keychain error) — back off.
-        if (!/not found/i.test(err.message))
-            lastPromptFailureAt = now;
+    catch {
+        // Absent or locked bundle — never prompted (agentOnly), so no backoff: keep
+        // re-checking each cycle for fast pickup once the bundle is added / unlocked.
         return false;
     }
 }

package/dist/lib/share/config.js

@@ -76,6 +76,9 @@ export function storeWriteToken(token) {
 export function readWriteTokenFromBundle() {
     const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
         caller: 'share',
+        // Explicit `agents share` command (a human published a file): a headless agent
+        // subprocess resolves broker-only, an interactive human may unlock. This is NOT
+        // an agent LAUNCH read (that is exec.ts's --secrets injection, always agentOnly).
         agentOnly: isHeadlessSecretsContext(),
     });
     const token = env[SHARE_TOKEN_KEY];
@@ -133,6 +136,7 @@ export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
     }
     const { env } = readAndResolveBundleEnv(bundle, {
         caller: 'share',
+        // Explicit `agents share setup` provisioning read — not an agent launch.
         agentOnly: isHeadlessSecretsContext(),
     });
     const find = (re) => {

package/dist/lib/types.d.ts

@@ -764,6 +764,16 @@ export interface Meta {
      */
     isolatedAgents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /**
+     * Cost-tier overrides for `--model cheap|default|best|ultra`. Keyed by the same
+     * `<agent>:<version>` selector run.defaults uses (`kimi:*`, `kimi:0.19.2`); each
+     * value maps a tier to a concrete model id. Written by `agents models tier set`,
+     * never hand-edited. Resolution: exact version selector wins over `<agent>:*`,
+     * which wins over the auto-ranking. See lib/model-tier-overrides.ts.
+     */
+    model?: {
+        tiers?: Record<string, Partial<Record<'cheap' | 'default' | 'best' | 'ultra', string>>>;
+    };
     /**
      * Daemon watchdog config. `rotate` (default `on`) lets the watchdog rotate a
      * rate-limited session IN PLACE onto a healthy account/harness via

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();