@phnx-labs/agents-cli 1.22.3 → 1.22.5

package/dist/lib/model-tiers.js

@@ -1,11 +1,27 @@
 import { getModelCatalog } from './models.js';
 import { getModelPricing } from './pricing/index.js';
+import { resolveTierOverride } from './model-tier-overrides.js';
 /** The four cross-harness cost tiers, cheapest -> most capable. */
 export const MODEL_TIERS = ['cheap', 'default', 'best', 'ultra'];
 /** True if `s` is one of the four tier tokens (not a concrete model id). */
 export function isTierToken(s) {
     return !!s && MODEL_TIERS.includes(s);
 }
+/**
+ * Curated tier ladders for harnesses the auto-ranker can't order from names/price
+ * (subscription harnesses with no price signal). Each rung is `[tier, matcher]` in
+ * cheap -> best order; the newest catalog id matching each rung fills that tier,
+ * missing tiers clamp. Extend this table rather than adding per-harness branches.
+ */
+const CURATED_LADDERS = {
+    // Kimi: K2.7 Highspeed < K2.7 Coding < K3 (the 1M-context default; k3-256k folds
+    // into K3). No ultra. The name heuristic can't tell K3 > K2.7, so curate it.
+    kimi: [
+        { tier: 'cheap', match: /highspeed/i },
+        { tier: 'default', match: /for-coding(?!.*highspeed)/i },
+        { tier: 'best', match: /(^|[-/])k3\b/i }, // K3 family incl. k3-256k; the plain id represents it
+    ],
+};
 // --- single-model harnesses: the tier is reasoning effort, not a model ---------
 const TIER_EFFORT = {
     cheap: 'low',
@@ -169,29 +185,100 @@ function rankCatalog(agent, models) {
 function rungIndexFor(tierIndex, n) {
     return n >= 4 ? Math.round((tierIndex / 3) * (n - 1)) : Math.min(tierIndex, n - 1);
 }
+/** Bucket an ordered (cheap -> dear) rung list onto the four tiers, clamping when < 4. */
+function bucketRungs(rungs) {
+    const n = rungs.length;
+    const map = {};
+    if (n === 0) {
+        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
+        for (const t of MODEL_TIERS)
+            map[t] = { tier: t, model: null };
+        return map;
+    }
+    // A tier that shares the rung of the tier below has no distinct rung -> mark clamped.
+    for (let i = 0; i < MODEL_TIERS.length; i++) {
+        const t = MODEL_TIERS[i];
+        const idx = rungIndexFor(i, n);
+        const shared = i > 0 && rungIndexFor(i - 1, n) === idx;
+        map[t] = shared
+            ? { tier: t, model: rungs[idx].id, clampedFrom: MODEL_TIERS[i - 1], note: `no distinct ${t} rung; using ${MODEL_TIERS[i - 1]}`, source: 'auto' }
+            : { tier: t, model: rungs[idx].id, source: 'auto' };
+    }
+    return map;
+}
+/** Build a tier map from a curated ladder against a catalog (newest match per rung). */
+function tierizeFromLadder(ladder, models) {
+    const usable = models.filter((m) => !PSEUDO.test(m.id));
+    const rungs = [];
+    for (const rung of ladder) {
+        const matches = usable.filter((m) => rung.match.test(m.id));
+        if (matches.length === 0)
+            continue;
+        // Prefer a plain id over a context-size variant (k3 over k3-256k) -- the
+        // variant folds into the rung but the plain model represents it -- then newest.
+        const plain = matches.filter((m) => !/-\d+[km]\b/i.test(m.id));
+        const pool = plain.length ? plain : matches;
+        rungs.push({ id: pool.reduce((a, b) => (newer(b.id, a.id) > 0 ? b : a)).id });
+    }
+    const map = bucketRungs(rungs);
+    for (const t of MODEL_TIERS)
+        if (map[t].model)
+            map[t].source = 'curated';
+    return map;
+}
 /**
- * Resolve all four tiers for an (agent, version). The map is what `agents models`
- * prints and what `resolveTier` indexes into.
+ * Resolve all four tiers for an (agent, version) -- what `agents models` prints and
+ * `resolveTier` indexes. Precedence: user override -> curated ladder / auto-ranking.
  */
 export function resolveTierMap(agent, version) {
-    // Droid: curated credit-multiplier map (no live catalog).
+    let base;
+    let catalogIds;
     if (agent === 'droid') {
-        return {
-            cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x' },
-            default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x' },
-            best: { tier: 'best', model: DROID_TIERS.best, note: '2x' },
-            ultra: { tier: 'ultra', model: DROID_TIERS.ultra, clampedFrom: 'best', note: 'capped at 2x (4x models excluded)' },
+        // Droid: curated credit-multiplier map (no live catalog to validate against).
+        base = {
+            cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x', source: 'curated' },
+            default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x', source: 'curated' },
+            best: { tier: 'best', model: DROID_TIERS.best, note: '2x', source: 'curated' },
+            ultra: { tier: 'ultra', model: DROID_TIERS.ultra, clampedFrom: 'best', note: 'capped at 2x (4x excluded)', source: 'curated' },
         };
+        catalogIds = null;
     }
-    const catalog = getModelCatalog(agent, version);
-    return tierizeModels(agent, catalog?.models ?? []);
+    else {
+        const catalog = getModelCatalog(agent, version);
+        const models = catalog?.models ?? [];
+        const ladder = CURATED_LADDERS[agent];
+        base = ladder ? tierizeFromLadder(ladder, models) : tierizeModels(agent, models);
+        catalogIds = catalog ? new Set(models.map((m) => m.id)) : null;
+    }
+    const overrides = resolveTierOverride(agent, version);
+    return applyTierOverrides(overrides, `${agent}@${version}`, catalogIds, base);
+}
+/**
+ * Apply user overrides on top of the auto/curated map. Pure (takes the resolved
+ * override map, no config lookup) so it is directly testable. An overridden id is
+ * used only when the version actually ships it (or when there is no catalog to
+ * check, e.g. Droid); otherwise the tier keeps its base value with a note.
+ */
+export function applyTierOverrides(overrides, label, catalogIds, base) {
+    if (Object.keys(overrides).length === 0)
+        return base;
+    const out = { ...base };
+    for (const t of MODEL_TIERS) {
+        const id = overrides[t];
+        if (!id)
+            continue;
+        if (!catalogIds || catalogIds.has(id)) {
+            out[t] = { tier: t, model: id, source: 'override' };
+        }
+        else {
+            out[t] = { ...base[t], note: `override "${id}" not shipped by ${label}; kept the ${base[t].source ?? 'auto'} pick`, source: base[t].source ?? 'auto' };
+        }
+    }
+    return out;
 }
 /**
- * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup)
- * so it is directly testable with synthetic inputs. Ranks the models, collapses
- * variants, buckets onto cheap/default/best/ultra, and clamps absent tiers down
- * to the nearest lower one. A single-model harness maps the tiers to reasoning
- * effort instead of models.
+ * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup) so
+ * it is directly testable. A single-model harness maps the tiers to reasoning effort.
  */
 export function tierizeModels(agent, models) {
     const rungs = rankCatalog(agent, models);
@@ -200,28 +287,10 @@ export function tierizeModels(agent, models) {
         const only = rungs[0].id;
         const map = {};
         for (const t of MODEL_TIERS)
-            map[t] = { tier: t, model: only, effort: TIER_EFFORT[t], note: 'single model — tier maps to reasoning effort' };
-        return map;
-    }
-    const n = rungs.length;
-    const map = {};
-    if (n === 0) {
-        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
-        for (const t of MODEL_TIERS)
-            map[t] = { tier: t, model: null };
+            map[t] = { tier: t, model: only, effort: TIER_EFFORT[t], note: 'single model — tier maps to reasoning effort', source: 'auto' };
         return map;
     }
-    // Map each tier onto a rung; a tier that shares the rung of the tier below it
-    // has no distinct rung of its own, so mark it clamped for an honest display.
-    for (let i = 0; i < MODEL_TIERS.length; i++) {
-        const t = MODEL_TIERS[i];
-        const idx = rungIndexFor(i, n);
-        const shared = i > 0 && rungIndexFor(i - 1, n) === idx;
-        map[t] = shared
-            ? { tier: t, model: rungs[idx].id, clampedFrom: MODEL_TIERS[i - 1], note: `no distinct ${t} rung; using ${MODEL_TIERS[i - 1]}` }
-            : { tier: t, model: rungs[idx].id };
-    }
-    return map;
+    return bucketRungs(rungs);
 }
 /** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
 export function resolveTier(agent, version, tier) {

package/dist/lib/models.d.ts

@@ -60,6 +60,22 @@ export interface ModelSource {
  * Returns null if nothing usable is found.
  */
 export declare function locateModelSource(agent: AgentId, version: string): ModelSource | null;
+/**
+ * Extract Claude's model catalog from its bundle/binary.
+ *
+ * Bundle/binary contains:
+ *   - alias map: {opus:"claude-opus-4-7",sonnet:"claude-sonnet-4-6",haiku:"..."}
+ *   - per-cloud maps: {firstParty:"claude-opus-4-5-...",bedrock:"...",vertex:"...",...}
+ *   - constants: {OPUS_ID:"...",OPUS_NAME:"...",SONNET_ID:"...",...}
+ */
+/**
+ * Drop a bare `claude-<family>-<major>` (e.g. `claude-opus-4`) when a more specific
+ * sibling (`claude-opus-4-8`) is present. The bare form is only ever an internal
+ * `.includes("claude-opus-4")` prefix-check string in the binary, not a submittable
+ * id (issue #1892); a bare id with no sibling (e.g. `claude-sonnet-5`) is a real
+ * current model and is kept.
+ */
+export declare function dropBareLegacyIds(ids: string[]): string[];
 /**
  * Parse `grok models` stdout into a catalog. Exported for unit tests.
  *

package/dist/lib/models.js

@@ -21,7 +21,7 @@ const CACHE_PATH = getModelsCachePath();
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.
  */
-const CACHE_SCHEMA_VERSION = 3;
+const CACHE_SCHEMA_VERSION = 4;
 /**
  * How long a cached 0-model extraction is trusted before we retry it. Bounds
  * the self-healing window for a transient failure (mid-install, a broken
@@ -310,6 +310,19 @@ function extractStrings(filePath, minLen = 6) {
  *   - per-cloud maps: {firstParty:"claude-opus-4-5-...",bedrock:"...",vertex:"...",...}
  *   - constants: {OPUS_ID:"...",OPUS_NAME:"...",SONNET_ID:"...",...}
  */
+/**
+ * Drop a bare `claude-<family>-<major>` (e.g. `claude-opus-4`) when a more specific
+ * sibling (`claude-opus-4-8`) is present. The bare form is only ever an internal
+ * `.includes("claude-opus-4")` prefix-check string in the binary, not a submittable
+ * id (issue #1892); a bare id with no sibling (e.g. `claude-sonnet-5`) is a real
+ * current model and is kept.
+ */
+export function dropBareLegacyIds(ids) {
+    return ids.filter((id) => {
+        const bareMajor = /^claude-[a-z]+-\d+$/.test(id);
+        return !(bareMajor && ids.some((o) => o !== id && o.startsWith(`${id}-`)));
+    });
+}
 function extractClaudeCatalog(text) {
     const aliases = {};
     const aliasMapMatch = text.match(/\{opus:"(claude-[^"]+)",sonnet:"(claude-[^"]+)",haiku:"(claude-[^"]+)"\}/);
@@ -380,8 +393,9 @@ function extractClaudeCatalog(text) {
         let sm;
         while ((sm = idRe.exec(text)) !== null)
             scanned.add(sm[0]);
-        if (scanned.size >= 2)
-            models = build(scanned);
+        const filtered = dropBareLegacyIds([...scanned]);
+        if (filtered.length >= 2)
+            models = build(filtered);
     }
     return { models, aliases };
 }

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

@@ -279,37 +279,12 @@ export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, h
 export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveBundleOptions): Record<string, string>;
 /**
  * True when the current process is a background / non-interactive context that
- * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
- * a prompt nobody is watching. Two signals, either sufficient:
- *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
- *     launch, interactive included, and inherited by everything spawned beneath
- *     one (set on the child env by `agents run --headless`, scheduled routines,
- *     teammates, and interactive runs — see exec.ts:430, runner.ts,
- *     teams/agents.ts).
- *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
- *     stdio is redirected to a log — e.g. a release script run in the
- *     background as `( ... ) >log 2>&1 </dev/null`).
- * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
- *
- * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
- * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
- * the Windows credential store resolve without any prompt. So off-darwin this
- * ALWAYS returns false: forcing broker-only there would break every headless
- * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
- * release flow) for no benefit — there is no prompt to suppress.
- *
- * A read in a macOS headless context resolves broker-only (agentOnly) and fails
- * fast with an actionable error instead of hijacking Touch ID. This generalizes
- * the per-caller broker-only pattern used across the headless secrets readers.
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen.
+ * Re-exported from ./headless.js — the detector lives there so the raw-read
+ * path in index.ts can share it without a bundles↔index import cycle. See that
+ * module for the full contract.
  */
-export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
-    stdin?: boolean;
-    stdout?: boolean;
-}): boolean;
+export { isHeadlessSecretsContext } from './headless.js';
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *

package/dist/lib/secrets/bundles.js

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

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

@@ -0,0 +1,39 @@
+/**
+ * The headless-context detector shared by every secrets read path that could
+ * raise a macOS Touch ID sheet: bundle resolution (bundles.ts) and raw item
+ * reads (index.ts). It lives in its own module so index.ts can use it without
+ * importing bundles.ts (which already imports index.ts).
+ */
+/**
+ * True when the current process is a background / non-interactive context that
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
+ * a prompt nobody is watching. Two signals, either sufficient:
+ *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, runner.ts,
+ *     teams/agents.ts).
+ *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
+ *     stdio is redirected to a log — e.g. a release script run in the
+ *     background as `( ... ) >log 2>&1 </dev/null`).
+ * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
+ * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
+ *
+ * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
+ * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
+ * the Windows credential store resolve without any prompt. So off-darwin this
+ * ALWAYS returns false: forcing broker-only there would break every headless
+ * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
+ * release flow) for no benefit — there is no prompt to suppress.
+ *
+ * A read in a macOS headless context resolves broker-only (agentOnly) and fails
+ * fast with an actionable error instead of hijacking Touch ID. This generalizes
+ * the per-caller broker-only pattern used across the headless secrets readers.
+ */
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
+    stdin?: boolean;
+    stdout?: boolean;
+}): boolean;

package/dist/lib/secrets/headless.js

@@ -0,0 +1,63 @@
+/**
+ * The headless-context detector shared by every secrets read path that could
+ * raise a macOS Touch ID sheet: bundle resolution (bundles.ts) and raw item
+ * reads (index.ts). It lives in its own module so index.ts can use it without
+ * importing bundles.ts (which already imports index.ts).
+ */
+/**
+ * True when the current process is a background / non-interactive context that
+ * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
+ * a prompt nobody is watching. Two signals, either sufficient:
+ *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, runner.ts,
+ *     teams/agents.ts).
+ *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
+ *     stdio is redirected to a log — e.g. a release script run in the
+ *     background as `( ... ) >log 2>&1 </dev/null`).
+ * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
+ * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
+ *
+ * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
+ * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
+ * the Windows credential store resolve without any prompt. So off-darwin this
+ * ALWAYS returns false: forcing broker-only there would break every headless
+ * Linux/Windows read (CI, `agents run --headless`, routines, the Linux-driven
+ * release flow) for no benefit — there is no prompt to suppress.
+ *
+ * A read in a macOS headless context resolves broker-only (agentOnly) and fails
+ * fast with an actionable error instead of hijacking Touch ID. This generalizes
+ * the per-caller broker-only pattern used across the headless secrets readers.
+ */
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
+// Injected so the TTY branch below is testable: it is the branch that decides a
+// plain human shell still prompts, which is this guard's entire safety argument,
+// and reading process.* directly made it unreachable from a test.
+tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
+    if (platform !== 'darwin')
+        return false; // no biometry prompt to suppress off-darwin
+    const override = env.AGENTS_SECRETS_NO_PROMPT;
+    if (override === '1')
+        return true;
+    if (override === '0')
+        return false;
+    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
+    // `terminal` was missing, which made an agent terminal the one launch path
+    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
+    // interactive run (exec.ts:430), that fell through to the TTY check below, and
+    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
+    // opening a terminal is not a request to authenticate, and a launch that needs
+    // a locked bundle should say so and point at `agents secrets unlock`, not grab
+    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
+    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
+    // correctly: there the agent, not the human, is the caller. A plain shell carries
+    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
+    const runtime = env.AGENTS_RUNTIME;
+    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
+        return true;
+    return !tty.stdin && !tty.stdout;
+}

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

@@ -91,6 +91,21 @@ export declare function setKeychainBackendForTest(b: KeychainBackend | null): Ke
  * fast-path must not engage. Always false in production (`backend` is null). */
 export declare function isKeychainBackendOverridden(): boolean;
 export declare const HMAC_KEY_ITEM = "agents-cli.hmackey";
+interface HmacKeyRecord {
+    v: number;
+    /** 64 hex chars — the raw HMAC-SHA256 key. */
+    k: string;
+    /** True once the one-time re-key has moved every cleartext-named item. */
+    migrated: boolean;
+    /** Old cleartext services whose hashed copies are verified but whose
+     * originals are not yet deleted (crash-resume list; deletes are silent). */
+    pendingDeletes?: string[];
+    /** True once this record has been re-stored no-ACL to heal a hmackey item that
+     * an OLD helper (pre the metadata/hmackey no-ACL migration fix) re-stamped with
+     * a biometry ACL. Set on the first read that heals it, so the heal runs exactly
+     * once per machine and never churns the keychain afterward. */
+    healedNoAcl?: boolean;
+}
 /** Force hashed service names on with a fixed key (test only). Pass null to
  * restore lazy production resolution. Composes with setKeychainBackendForTest
  * so unit tests exercise the exact transform production uses. */
@@ -106,6 +121,20 @@ export declare function withRawKeychainServiceNames<T>(fn: () => T): T;
  * the re-key migration and tests; runtime callers go through the primitives,
  * which apply this transparently. */
 export declare function hashedServiceName(item: string, key: Buffer): string;
+/**
+ * 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 declare function healHmacKeyNoAclOnce(rec: HmacKeyRecord): boolean;
 /**
  * The storage-layer service name for `item`: hashed when hashing is active,
  * the item itself otherwise. For callers that mix helper-enumerated
@@ -217,7 +246,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;
 /**