@phnx-labs/agents-cli 1.22.4 → 1.22.5

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.22.5
+
+- **`agents events` can now filter by `--session <id>` and `--bundle <name>` — trace which agent/session triggered a secret access.** Every event already carries the provenance `sessionId`, and secrets events carry the `bundle` in their payload, but neither was queryable: you could see *that* the `share` bundle was read, not *which session* read it. `--session` (wired to the engine's existing `sessionId` filter) and `--bundle` (a new payload filter across both the operational log and the activity stream) close that gap. `agents events --module secrets --bundle share --session <id>` answers "which agent read the share bundle" — the attribution the Touch ID storm investigation needed, since the macOS biometric sheet itself emits no event. Source: `apps/cli/src/lib/event-stream.ts`, `apps/cli/src/commands/events.ts`, `apps/cli/docs/06-observability.md`.
+
+- **`agents feed post --blocked` records now survive the agent's next Stop.** The feed-publish hook cleared the per-session block file on every `Stop`/`SessionEnd`/`PostToolUse`, which silently dropped a declared (`--blocked`) block the moment the agent parked it and its turn ended — exactly when the owner still needs to see and answer it. Declared blocks are now exempt from the lifecycle clear and stay in `agents feed` until they are actually answered (a terminal reply or `recordAnswer`); question/notification/approval blocks still clear as before. Source: `apps/cli/src/lib/feed.ts`.
+
+- **`agents add grok@latest` no longer lets a second grok account silently displace a first account's install.** Grok's version directories are keyed by upstream release number alone, not by account — so two different grok accounts that both self-update to the same identical release ("latest") were landing on the SAME on-disk `versions/grok/<version>/` directory. The second account's credentials would overwrite the first's in that shared directory, even though `agents view grok` still listed both accounts as separately installed. `installVersion` now detects this before finalizing the install: if the target version's home already has a signed-in account whose identity differs from the account driving the current update, it refuses with a clear error instead of silently corrupting the first account's install. Source: `apps/cli/src/lib/versions.ts`.
+
+- **The stray "Agents CLI needs to authenticate to continue" Touch ID sheet now heals itself.** An old keychain helper (before the metadata/hmackey no-ACL migration fix) could re-stamp the internal HMAC-key item (`agents-cli.hmackey`) with a biometry ACL. That item is read *before every hashed keychain lookup*, so a damaged copy popped a generic, context-less Touch ID sheet on nearly any command that touched secrets — `agents devices list`, a background agent, a session hook — at seemingly random times. The migration fix stopped the re-stamping but never un-stamped an already-damaged item, and once hashed naming is active nothing re-stored it, so it prompted forever. Now, on the first read where hashing is active, an un-healed HMAC-key record is re-stored no-ACL exactly once (`healHmacKeyNoAclOnce`, gated by a `healedNoAcl` flag so it never churns the keychain afterward) — one last prompt on the read that heals it, then silent. Existing damaged machines can also fix it immediately with `agents secrets rekey`. Source: `apps/cli/src/lib/secrets/index.ts`.
+
+- **`agents inspect` and `view --json` now report isolation honestly.** Found by diffing
+  every command's output between an isolated-only and a normal install. `inspect` printed
+  the bare-shim path unconditionally, so an isolated copy — which deliberately has no
+  shim, that being the guarantee — was shown sitting on the user's PATH; it now reports
+  `(none — isolated installs stay off PATH)` and `shim: null` in JSON. `inspect` also
+  showed only `default: false` for an isolated copy, hiding that it *was* the selected
+  one; it now carries `isolated` and `isolatedDefault`, and the header reads
+  `[isolated default]`. `view --json` had no isolation signal at all, so tooling could not
+  distinguish a sandboxed copy from one that owns the launcher and real config — its
+  version entries gain `isolated` and `isIsolatedDefault`. Source:
+  `apps/cli/src/commands/inspect.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents models` is now a scannable tier menu, and you can override a tier with a command.** The tier map (`cheap|default|best|ultra` → model + `~$/Mtok`) prints for every installed harness by default; the raw model list moved behind `--all`. When the auto-guess is wrong (subscription harnesses with no price signal), pin the right model without hand-editing YAML: `agents models tier set <agent[@version]> <tier> <model>` (e.g. `agents models tier set kimi best kimi-code/k3`), `tier clear`, `tier list`. Overrides live under `model.tiers` in `agents.yaml` (same selector shape as `run.defaults`) and resolve most-specific-first — `<agent>:<version>` → `<agent>:*` → auto; an overridden id a version doesn't ship falls back to auto, and `agents models` marks a pinned tier `[override]`. Ships a curated Kimi ladder (`k2.7-highspeed` < `k2.7-coding` < `k3`) so it's right by default. Also fixes two extraction bugs: bumps the model-catalog cache schema so a freshly-upgraded box re-extracts instead of serving a stale "No models extracted" for 24h, and stops the id-scan from listing bare legacy ids like `claude-opus-4` (#1892). Source: `apps/cli/src/lib/model-tier-overrides.ts`, `apps/cli/src/lib/model-tiers.ts`, `apps/cli/src/commands/models.ts`, `apps/cli/src/lib/models.ts`, `apps/cli/docs/model-tiers.md`.
+
+- **`agents run --secrets <bundle>` never raises a Touch ID sheet on launch — even with a tty (a second storm source).** The `--secrets` injection read gated on `isHeadlessSecretsContext()`, which is FALSE for an interactive run — so an `agents run … --interactive` launch (the watchdog fires `agents run auto --interactive` every ~2 min via routine + menu-bar tick) could pop Touch ID for a keychain `hold` bundle, piling up helper sheets. An agent launch must never prompt regardless of tty (SEC-13): the read is now always `agentOnly` — it resolves from the broker (or a no-ACL bundle) and otherwise fails fast naming `agents secrets unlock <bundle>`, matching the behavior the code's own comment already described. Unchanged: the explicit `agents share` / `agents share setup` commands (`readWriteTokenFromBundle`, `readCloudflareCreds`) still honor the interactive/headless gate — those are user-initiated, not agent launches. Source: `apps/cli/src/commands/exec.ts`.
+
+- **Background and read-only secret reads never raise Touch ID (SEC-13).** Every non-user-initiated secret read now resolves `agentOnly` — from the secrets broker or a no-ACL bundle — and, on a locked `hold`/`always` keychain bundle, fails fast naming `agents secrets unlock <bundle>` instead of popping a Touch ID sheet on the interactive launcher. This closes the rest of the per-launch prompt storm that #1905 fixed only for `--secrets` injection. Covered: session-sync (`r2.backups`, read on every daemon cycle — degrades to no-transport when locked, re-checked each cycle for fast pickup once unlocked), the `--lease` crabbox provider token (resolved once up front and memoized, so a locked bundle fails loud once and the ready-wait poll never re-issues the read), browser-profile secrets on launch (skipped silently, launch proceeds), cloud dispatch (`cloud:antigravity`, fails loud with the unlock hint), the `webhook serve` receiver, and the `get_secret` MCP tool (throws as the tool error). Unchanged and still interactive-gated: the user-initiated `agents secrets get/export`, `agents browser type`, `agents exec --secrets`, the `ssh` askpass, and the explicit `agents share` / `agents share setup` provisioning reads — a human running those in a plain terminal still gets a prompt. Source: `apps/cli/src/lib/session/sync/config.ts`, `apps/cli/src/lib/crabbox/cli.ts`, `apps/cli/src/lib/browser/chrome.ts`, `apps/cli/src/lib/cloud/antigravity.ts`, `apps/cli/src/lib/secrets/mcp.ts`, `apps/cli/src/commands/webhook.ts`.
+
 ## 1.22.4
 
 - **Background processes no longer storm macOS Touch ID sheets (secrets-touchid-storm).**

package/dist/commands/events.js

@@ -192,6 +192,8 @@ export function registerEventsCommand(program) {
         .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
         .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get, secrets.unlocked, pr.opened)', collect, [])
         .option('--agent <name>', 'Only events tagged with this agent')
+        .option('--session <id>', 'Only events from this session (the provenance sessionId) — e.g. trace which session read a secret')
+        .option('--bundle <name>', 'Only events carrying this bundle in their payload — e.g. `--module secrets --bundle share` for every read of the share bundle')
         .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
         .option('--audit', 'Operational events only (skip agent activity)')
         .option('--limit <n>', 'Max records to show; 0 for no cap (default 50)', '50')
@@ -204,6 +206,10 @@ Examples:
   agents events --audit                  Operational events only (secrets / teams / ...)
   agents events --event pr.opened --since 7d
   agents events --module secrets         Every secret accessed or revealed
+  agents events --module secrets --bundle share
+                                         Every read of the share bundle (which agent, which session)
+  agents events --bundle share --session <id>
+                                         Trace one session's reads of a bundle
   agents events -f                       Live tail (operational)
   agents events --event pr.opened --since 30d --limit 0 --json
                                          Every match — use --limit 0 whenever you
@@ -228,6 +234,8 @@ Examples:
             startDate,
             eventTypes: options.event && options.event.length ? options.event : undefined,
             agent: options.agent,
+            sessionId: options.session,
+            bundle: options.bundle,
             command: options.command,
             module: options.module,
             limit: limit === undefined ? undefined : limit + 1,

package/dist/commands/exec.js

@@ -1567,7 +1567,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -2239,11 +2239,13 @@ export function registerRunCommand(program) {
                         agent,
                         keys: secretsKeysSubset,
                         allowExpired: options.allowExpired,
-                        // The harness identity scopes any cached grant. It no longer lets the
-                        // requesting agent wait for interactive approval — an agent launch
+                        // The harness identity scopes any cached grant. An agent launch
                         // resolves broker-only and fails fast naming
-                        // `agents secrets unlock <bundle>` (bundles.ts:interactiveUnlock).
-                        agentOnly: isHeadlessSecretsContext(),
+                        // `agents secrets unlock <bundle>` (bundles.ts:interactiveUnlock) — it
+                        // MUST NOT raise a Touch ID sheet regardless of tty (SEC-13). Gating on
+                        // isHeadlessSecretsContext() left `--interactive` launches (the watchdog's
+                        // `agents run auto --interactive`) able to prompt, piling up helper sheets.
+                        agentOnly: true,
                     });
                     const entries = describeBundle(bundle);
                     const counts = {};

package/dist/commands/inspect.js

@@ -24,7 +24,7 @@ import { supports } from '../lib/capabilities.js';
 import { resolveConfiguredModel } from '../lib/models.js';
 import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
-import { getVersionHomePath } from '../lib/versions.js';
+import { getVersionHomePath, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
 import { listHookEntriesFromDir } from '../lib/hooks.js';
@@ -560,8 +560,19 @@ async function renderSummary(agent, version, versionHome, options) {
     const cliState = await getCliState(agent).catch(() => null);
     const configSymlink = path.join(os.homedir(), `.${agent}`);
     const configTarget = readSymlinkSafe(configSymlink);
-    const shimPath = path.join(getShimsDir(), AGENTS[agent].cliCommand);
+    // Report the bare shim only when it is actually there. An isolated install
+    // deliberately has none — that is the promise — so printing the path
+    // unconditionally told the user this copy sits on their PATH when it does not.
+    // Same failure mode as `agents view` claiming an isolated copy was `(global)`.
+    const shimPathIfPresent = fs.existsSync(path.join(getShimsDir(), AGENTS[agent].cliCommand))
+        ? path.join(getShimsDir(), AGENTS[agent].cliCommand)
+        : null;
     const aliasPath = getVersionedAliasPath(agent, version);
+    const isolated = isVersionIsolated(agent, version);
+    // `default` means the GLOBAL default, which an isolated copy can never be. Report
+    // the isolated pointer separately rather than leaving it invisible: it is what a
+    // bare `agents run <agent>` resolves to, so "default: false" alone is misleading.
+    const isIsolatedDefault = isolated && getIsolatedDefault(agent) === version;
     const capabilities = collectCapabilities(agent, version);
     const itemsByKind = options.brief ? null : collectItemsByKind(agent, versionHome);
     const hookByScript = options.brief ? null : hookManifestByScript(loadCentralHookManifest());
@@ -574,9 +585,11 @@ async function renderSummary(agent, version, versionHome, options) {
             agent,
             version,
             default: isDefault,
+            isolated,
+            isolatedDefault: isIsolatedDefault,
             home: versionHome,
             configSymlink: configTarget ? { from: configSymlink, to: configTarget } : null,
-            shim: shimPath,
+            shim: shimPathIfPresent,
             alias: aliasPath,
             strategy,
             installedShim: cliState?.installed === true ? cliState.path : null,
@@ -590,12 +603,12 @@ async function renderSummary(agent, version, versionHome, options) {
     // Plain text — model sits right beside the version, same priority (no label).
     const configuredModel = resolveConfiguredModel(agent, version)?.model;
     const modelPart = configuredModel ? '  ' + chalk.yellow(configuredModel) : '';
-    const head = `${chalk.bold(agent)} ${chalk.gray('@')} ${chalk.cyan(version)}${modelPart}${isDefault ? '  ' + chalk.green('[default]') : ''}`;
+    const head = `${chalk.bold(agent)} ${chalk.gray('@')} ${chalk.cyan(version)}${modelPart}${isDefault ? '  ' + chalk.green('[default]') : ''}${isolated ? '  ' + chalk.gray(isIsolatedDefault ? '[isolated default]' : '[isolated]') : ''}`;
     console.log('\n' + head + '\n');
     const rows = [
         ['install', versionHome],
         ['config', configTarget ? `${configSymlink}  ${chalk.gray('→')}  ${configTarget}` : chalk.gray('(no symlink)')],
-        ['shim', shimPath],
+        ['shim', shimPathIfPresent ?? chalk.gray(isolated ? '(none — isolated installs stay off PATH)' : '(none)')],
         ['alias', aliasPath],
         ['strategy', strategy],
     ];

package/dist/commands/models.d.ts

@@ -6,7 +6,7 @@
  * each agent's CLI bundle and displays IDs, aliases, and metadata.
  */
 import type { Command } from 'commander';
-/** Register the hidden `agents models` command. */
+/** Register the `agents models` command + its `tier` override subcommands. */
 export declare function registerModelsCommand(program: Command): void;
 export declare function formatModelSourceLine(kind: string, sourcePath: string, width?: number): string;
 export declare function formatModelAliasLines(parts: string[], width?: number): string[];

package/dist/commands/models.js

@@ -12,6 +12,7 @@ import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.j
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
 import { resolveTierMap, MODEL_TIERS } from '../lib/model-tiers.js';
+import { setTierOverride, clearTierOverride, listTierOverrides } from '../lib/model-tier-overrides.js';
 import { getModelPricing } from '../lib/pricing/index.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { wrapJoined } from './inspect.js';
@@ -37,14 +38,15 @@ function fallbackPathVersion(agent) {
     const m = real.match(/\/versions\/([^/]+)\//);
     return m ? m[1] : 'installed';
 }
-/** Register the hidden `agents models` command. */
+/** Register the `agents models` command + its `tier` override subcommands. */
 export function registerModelsCommand(program) {
-    program
-        .command('models [agentSpec]', { hidden: true })
-        .description('List models supported by an installed agent version (internal/debug)')
-        .option('--cloud', 'Show per-cloud IDs (Claude only)')
-        .option('--reasoning', 'Show reasoning levels per model (Codex only)')
-        .option('--json', 'Output catalog as JSON')
+    const models = program
+        .command('models [agentSpec]')
+        .description('Show the cost-tier map (cheap|default|best|ultra) for installed harnesses; pin overrides with `tier set`.')
+        .option('--all', 'Show the full raw model catalog, not just the tier map')
+        .option('--cloud', 'Show per-cloud IDs (Claude only; implies --all)')
+        .option('--reasoning', 'Show reasoning levels per model (Codex only; implies --all)')
+        .option('--json', 'Output catalog + tiers as JSON')
         .action(async (agentSpec, options) => {
         const targets = await resolveTargets(agentSpec);
         if (targets.length === 0)
@@ -59,13 +61,63 @@ export function registerModelsCommand(program) {
             console.log(JSON.stringify(out, null, 2));
             return;
         }
+        const all = options.all || options.cloud || options.reasoning;
         let printed = 0;
         for (const { agent, version, isDefault } of targets) {
             if (printed > 0)
                 console.log();
-            printCatalog(agent, version, isDefault, options);
+            printCatalog(agent, version, isDefault, { ...options, all });
             printed++;
         }
+        if (!agentSpec && !all) {
+            console.log(chalk.gray('\n  `agents models <agent>` for one harness · `--all` for the full model list'));
+            console.log(chalk.gray('  `agents models tier set <agent> <tier> <model>` to override a tier'));
+        }
+    });
+    // Override subcommands. These WRITE agents.yaml so the user never hand-edits it;
+    // resolution is exact `<agent>@<version>` over `<agent>` over the auto guess.
+    const tier = models
+        .command('tier')
+        .description('Override which model a cost tier resolves to (per harness, or per agent@version).');
+    tier
+        .command('set <selector> <tier> <model>')
+        .description('Pin a tier to a model. selector: <agent> or <agent>@<version> (e.g. kimi, kimi@0.19.2).')
+        .action((selector, tierName, model) => {
+        try {
+            const entry = setTierOverride(selector, tierName, model);
+            console.log(chalk.green(`✓ ${entry.selector}  ${chalk.cyan(tierName.toLowerCase())} → ${chalk.bold(model)}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    tier
+        .command('clear <selector> [tier]')
+        .description('Clear one tier (or all tiers) back to the auto guess.')
+        .action((selector, tierName) => {
+        try {
+            const changed = clearTierOverride(selector, tierName);
+            console.log(changed ? chalk.green(`✓ cleared ${selector}${tierName ? ` ${tierName}` : ''}`) : chalk.gray('nothing to clear'));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    tier
+        .command('list')
+        .description('List all configured tier overrides.')
+        .action(() => {
+        const entries = listTierOverrides();
+        if (entries.length === 0) {
+            console.log(chalk.gray('No tier overrides — every tier uses the auto guess. Set one with `agents models tier set`.'));
+            return;
+        }
+        for (const e of entries) {
+            const parts = Object.entries(e.tiers).map(([t, m]) => `${chalk.cyan(t)}=${m}`);
+            console.log(`${chalk.bold(e.selector.padEnd(18))} ${parts.join('  ')}`);
+        }
     });
 }
 /** Resolve the agent spec into one or more (agent, version) pairs to inspect. */
@@ -144,6 +196,12 @@ function printCatalog(agent, version, isDefault, options) {
         console.log(chalk.yellow(`  No models extracted from ${src.kind} at ${src.path}.`));
         return;
     }
+    // The tier map above is what an agent reads. Keep the raw catalog behind --all
+    // so `agents models` stays a scannable menu instead of a 30-id dump.
+    if (!options.all) {
+        console.log(chalk.gray(`  ${catalog.models.length} models · \`agents models ${agent} --all\` for the full list`));
+        return;
+    }
     console.log(chalk.gray(formatModelSourceLine(src.kind, shortPath(src.path))));
     if (Object.keys(catalog.aliases).length > 0) {
         const parts = Object.entries(catalog.aliases).map(([alias, id]) => `${chalk.cyan(alias)}=${id}`);
@@ -202,7 +260,8 @@ function printTiers(agent, version) {
             continue;
         const eff = r.effort ? chalk.gray(` @${r.effort}`) : '';
         const clamp = r.clampedFrom ? chalk.gray(' (clamped)') : '';
-        console.log(`    ${chalk.cyan(t.padEnd(8))} ${chalk.bold(r.model)}${eff}${priceLabel(r.model)}${clamp}`);
+        const over = r.source === 'override' ? chalk.yellow(' [override]') : '';
+        console.log(`    ${chalk.cyan(t.padEnd(8))} ${chalk.bold(r.model)}${eff}${priceLabel(r.model)}${clamp}${over}`);
     }
     console.log();
 }

package/dist/commands/view.d.ts

@@ -51,6 +51,18 @@ export declare function renderHarnessBlocks(harnesses: ProfileSummary[], install
 export interface ViewJsonVersion {
     version: string;
     isDefault: boolean;
+    /**
+     * Installed with `--isolated`. The human view has shown this since the isolated
+     * tag landed, but JSON carried no signal at all, so tooling could not tell a
+     * sandboxed copy from one that owns the user's launcher and real config.
+     */
+    isolated: boolean;
+    /**
+     * The isolated copy a bare `agents run <agent>` resolves to. Separate from
+     * `isDefault`, which is the GLOBAL default an isolated version can never be —
+     * reporting only `isDefault: false` hid the fact that this one is selected.
+     */
+    isIsolatedDefault: boolean;
     signedIn: boolean;
     email: string | null;
     accountId?: string | null;

package/dist/commands/view.js

@@ -1242,6 +1242,8 @@ async function collectAgentsJson(filterAgentId, resourceSections) {
         const entry = {
             version,
             isDefault: version === globalDefault,
+            isolated: isVersionIsolated(agentId, version),
+            isIsolatedDefault: getIsolatedDefault(agentId) === version,
             signedIn: info.signedIn,
             email: info.email,
             accountId: info.accountId,

package/dist/commands/webhook.js

@@ -1,6 +1,6 @@
 import * as path from 'path';
 import chalk from 'chalk';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { createFileDeliveryStore, startWebhookServer } from '../lib/triggers/webhook.js';
 import { getRuntimeStateDir } from '../lib/state.js';
 const DEFAULT_HOST = '127.0.0.1';
@@ -12,9 +12,13 @@ function positiveInt(value, fallback) {
 function readWebhookSecrets(bundleName) {
     const { env } = readAndResolveBundleEnv(bundleName, {
         caller: 'webhook serve',
-        // `webhook serve` is a long-running background server; when started detached
-        // (no TTY) it must resolve broker-only rather than pop an unanswerable prompt.
-        agentOnly: isHeadlessSecretsContext(),
+        // `webhook serve` is a long-running background server started to receive
+        // signed webhooks, not 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 and fails the start LOUD rather
+        // than popping an unanswerable prompt.
+        agentOnly: true,
     });
     const secrets = {};
     if (env.GITHUB_WEBHOOK_SECRET)

package/dist/lib/browser/chrome.d.ts

@@ -38,6 +38,18 @@ export interface LaunchResult {
     port: number;
     wsUrl: string;
 }
+/**
+ * Resolve a browser-profile secrets bundle into an env map for the child, or an
+ * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
+ * throw and never a prompt. Injecting profile secrets on launch is a BACKGROUND
+ * read (the agent is spawning the browser, not a human at a Touch ID sheet), so
+ * the read is `agentOnly` (SEC-13: never pop biometry on its own): a `never`/no-ACL
+ * or broker-held bundle resolves silently; a locked `hold`/`always` bundle throws,
+ * and we swallow it so the launch proceeds without those secrets (an agent that
+ * needs them can `agents secrets unlock <bundle>`). Exported so the no-prompt
+ * behavior is testable on the real keychain path without spawning a browser.
+ */
+export declare function resolveProfileSecretsEnv(secrets?: string): Record<string, string>;
 export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string, isElectron?: boolean): Promise<LaunchResult>;
 export declare function attachToChrome(port: number): Promise<string>;
 export declare function killChrome(pid: number): void;

package/dist/lib/browser/chrome.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { getProfileRuntimeDir } from './profiles.js';
 import { discoverBrowserWsUrl, registerPipeTransport } from './cdp.js';
-import { readAndResolveBundleEnv, bundleExists, isHeadlessSecretsContext } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, bundleExists } from '../secrets/bundles.js';
 import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
 // Windows install roots. Resolve from the environment (fall back to the usual
 // defaults) so per-user installs under %LOCALAPPDATA% and 64-bit Program Files
@@ -225,6 +225,29 @@ export function listInstalledBrowsers(platform = os.platform()) {
     }
     return found;
 }
+/**
+ * Resolve a browser-profile secrets bundle into an env map for the child, or an
+ * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
+ * throw and never a prompt. Injecting profile secrets on launch is a BACKGROUND
+ * read (the agent is spawning the browser, not a human at a Touch ID sheet), so
+ * the read is `agentOnly` (SEC-13: never pop biometry on its own): a `never`/no-ACL
+ * or broker-held bundle resolves silently; a locked `hold`/`always` bundle throws,
+ * and we swallow it so the launch proceeds without those secrets (an agent that
+ * needs them can `agents secrets unlock <bundle>`). Exported so the no-prompt
+ * behavior is testable on the real keychain path without spawning a browser.
+ */
+export function resolveProfileSecretsEnv(secrets) {
+    if (!secrets || !bundleExists(secrets))
+        return {};
+    try {
+        const { env } = readAndResolveBundleEnv(secrets, { caller: 'browser profile', agentOnly: true });
+        return env;
+    }
+    catch {
+        // Bundle locked or failed to resolve — launch without secrets (no prompt).
+        return {};
+    }
+}
 export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary, 
 // `electron: true` distinguishes Notion / VS Code-style apps from
 // regular Chrome — purely informational, stored in meta.json so the
@@ -279,16 +302,9 @@ isElectron = false) {
             : []),
         ...(options.args || []),
     ];
-    let env = { ...process.env };
-    if (secrets && bundleExists(secrets)) {
-        try {
-            const { env: bundleEnv } = readAndResolveBundleEnv(secrets, { caller: 'browser profile', agentOnly: isHeadlessSecretsContext() });
-            env = { ...env, ...bundleEnv };
-        }
-        catch {
-            // Bundle failed to resolve, continue without secrets
-        }
-    }
+    // Profile secrets: agentOnly (SEC-13) — a locked bundle resolves to an empty map
+    // (launch proceeds without them), never a Touch ID prompt. See resolveProfileSecretsEnv.
+    const env = { ...process.env, ...resolveProfileSecretsEnv(secrets) };
     const child = spawn(browserPath, args, {
         detached: true,
         stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],

package/dist/lib/cloud/antigravity.js

@@ -20,7 +20,7 @@
  * back to GEMINI_API_KEY / GOOGLE_API_KEY in the environment.
  */
 import { resolveDispatchRepos, normalizeProviderStatus } from './types.js';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../secrets/bundles.js';
 const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
 const DEFAULT_MODEL = 'antigravity-preview-05-2026';
 const KEY_NAMES = ['GEMINI_API_KEY', 'GOOGLE_API_KEY'];
@@ -65,7 +65,13 @@ export class AntigravityCloudProvider {
     resolveApiKey() {
         if (this.secretsBundle) {
             try {
-                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:antigravity', agentOnly: isHeadlessSecretsContext() });
+                // Cloud dispatch resolves the key on its own (no human at a sheet), so the
+                // read is always `agentOnly` (SEC-13: never pop Touch ID on its own). A
+                // locked bundle THROWS the actionable "unlock <name>" message, which the
+                // catch below re-raises verbatim — dispatch genuinely needs the key, so it
+                // fails LOUD with the unlock hint rather than swallowing it into a wrong
+                // path. A `never`/no-ACL or broker-held bundle resolves silently.
+                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:antigravity', agentOnly: true });
                 for (const k of KEY_NAMES) {
                     if (env[k])
                         return env[k];

package/dist/lib/crabbox/cli.js

@@ -12,7 +12,7 @@
  * from a secrets bundle when one is configured (see `crabboxEnv`).
  */
 import { spawn, spawnSync } from 'child_process';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext, listBundles, bundleExists } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
 import { readMeta, writeMeta } from '../state.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
@@ -73,10 +73,14 @@ function resolveTailscaleBundleMemo() {
  * and the single-key subset read (`keys: [ts.key]`) is rejected by
  * `canCacheResolvedEnv` for broker auto-cache — so without this memo a
  * non-broker-held tailscale bundle re-read the keychain on EVERY call (and,
- * pre-guard, could pop a Touch ID sheet each time). One read per process,
- * success or failure (a failed read memoizes as undefined: the catch below
- * already degrades to a public-network lease, retrying mid-process only
- * repeats the same failure).
+ * pre-guard, could pop a Touch ID sheet each time). The read is always
+ * `agentOnly: true` (broker-only, SEC-13): tailscale is opt-in plumbing, a
+ * `--lease` run is headless by contract, and even an interactive `--lease`
+ * invocation must never pop an unwatched Touch ID sheet for this best-effort
+ * read — a locked bundle degrades silently to a public-network lease via the
+ * catch below. One read per process, success or failure (a failed read
+ * memoizes as undefined: the catch below already degrades to a public-network
+ * lease, retrying mid-process only repeats the same failure).
  */
 let tailscaleValueMemo;
 function resolveTailscaleKeyValueMemo(ts) {
@@ -86,7 +90,7 @@ function resolveTailscaleKeyValueMemo(ts) {
             const { env } = readAndResolveBundleEnv(ts.name, {
                 caller: 'agents run --lease (crabbox tailscale)',
                 keys: [ts.key],
-                agentOnly: isHeadlessSecretsContext(),
+                agentOnly: true,
             });
             value = env[ts.key];
         }
@@ -102,6 +106,7 @@ export function resetCrabboxSecretsMemosForTest() {
     tailscaleBundleMemo = undefined;
     tailscaleValueMemo = undefined;
     leaseBundleMemo = undefined;
+    leaseEnvMemo = undefined;
 }
 /**
  * The secrets bundle to feed crabbox, resolved in priority order:
@@ -150,6 +155,59 @@ function resolveLeaseBundleMemo() {
         leaseBundleMemo = { value: resolveLeaseBundle() };
     return leaseBundleMemo.value;
 }
+/**
+ * Process-lifetime memo for the RESOLVED provider-token env, resolved ONCE up
+ * front. `crabboxEnv` is called on every `crabboxWaitReady` poll iteration
+ * (crabboxWaitReady → crabboxFind → crabboxList → crabboxEnv), so without this
+ * memo the lease-token keychain read re-ran every ~5s of the ready wait — the
+ * per-poll storm this fix exists to kill. The read is now `agentOnly: true`
+ * (SEC-13: a `--lease` run is headless by contract and must never pop an
+ * unwatched Touch ID sheet). A locked `hold`/`always` bundle makes that read
+ * THROW the actionable "unlock <name>" message; we memoize the thrown error too
+ * and re-raise it on every subsequent call, so the failure surfaces loud ONCE
+ * up front (crabboxWarmup / the first crabboxList, before any poll loop) and the
+ * loop never re-issues the read. A `never`/no-ACL or broker-held bundle resolves
+ * silently. `undefined` when no lease bundle is configured (crabbox uses its own
+ * `crabbox login`). The memo (success OR failure) is cleared per test by
+ * resetCrabboxSecretsMemosForTest.
+ */
+let leaseEnvMemo;
+function resolveLeaseEnvMemo(explicitBundle) {
+    if (!leaseEnvMemo) {
+        const resolved = explicitBundle
+            ? { name: explicitBundle }
+            : resolveLeaseBundleMemo();
+        if (!resolved) {
+            leaseEnvMemo = {};
+        }
+        else {
+            try {
+                // Auto-detected bundle → inject ONLY the provider token key(s) (least
+                // privilege; an unrelated bundle can't leak its other secrets into crabbox).
+                // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
+                // whole — the user chose it. Same resolver `agents secrets exec` uses.
+                const { env } = readAndResolveBundleEnv(resolved.name, {
+                    caller: 'agents run --lease (crabbox)',
+                    keys: resolved.keys,
+                    // --lease is headless by contract and a locked bundle must fail loud with
+                    // an unlock hint, NEVER pop a Touch ID sheet — the read cannot be answered
+                    // in a background lease (SEC-13).
+                    agentOnly: true,
+                });
+                leaseEnvMemo = { env };
+            }
+            catch (e) {
+                leaseEnvMemo = {
+                    error: new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
+                        `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`),
+                };
+            }
+        }
+    }
+    if (leaseEnvMemo.error)
+        throw leaseEnvMemo.error;
+    return leaseEnvMemo.env;
+}
 /** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
 export function setLeaseSecretsBundle(name) {
     const meta = readMeta();
@@ -159,30 +217,14 @@ export function setLeaseSecretsBundle(name) {
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export function crabboxEnv(opts) {
     const out = { ...process.env };
-    const resolved = opts.secretsBundle
-        ? { name: opts.secretsBundle }
-        : resolveLeaseBundleMemo();
-    if (resolved) {
-        try {
-            // Auto-detected bundle → inject ONLY the provider token key(s) (least
-            // privilege; an unrelated bundle can't leak its other secrets into crabbox).
-            // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
-            // whole — the user chose it. Same resolver `agents secrets exec` uses.
-            const { env } = readAndResolveBundleEnv(resolved.name, {
-                caller: 'agents run --lease (crabbox)',
-                keys: resolved.keys,
-                // --lease is headless by contract and crabboxEnv is called several times
-                // per run (list/wait/spawn/stop) — resolve broker-only so a keychain bundle
-                // can't pop repeated unwatched Touch ID sheets mid-lease.
-                agentOnly: isHeadlessSecretsContext(),
-            });
-            Object.assign(out, env);
-        }
-        catch (e) {
-            throw new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
-                `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`);
-        }
-    }
+    // The lease provider-token read is resolved ONCE up front and memoized (env or
+    // thrown error) for the process — crabboxEnv runs on every crabboxWaitReady
+    // poll, so re-reading here was the per-poll storm. A locked bundle re-raises
+    // the memoized "unlock <name>" error every call, so the failure surfaces loud
+    // on the first crabboxEnv (before any poll loop) and never re-issues the read.
+    const leaseEnv = resolveLeaseEnvMemo(opts.secretsBundle);
+    if (leaseEnv)
+        Object.assign(out, leaseEnv);
     // Tailscale plumbing (F5): inject CRABBOX_TAILSCALE_AUTH_KEY from a bundle that
     // declares a tailscale auth key, when the ambient env doesn't already set one.
     // Best-effort and opt-in — a missing/unreadable tailscale bundle never fails a

package/dist/lib/event-stream.d.ts

@@ -20,6 +20,9 @@ export interface UnifiedQuery {
     agent?: string;
     /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
     sessionId?: string;
+    /** Only events carrying this bundle name in their payload (e.g. secrets events).
+     * Combined with `sessionId`, answers "which session read this secrets bundle". */
+    bundle?: string;
     caller?: string;
     command?: string;
     module?: string;