@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/lib/secrets/bundles.js

@@ -31,7 +31,8 @@ import { emit } from '../events.js';
 import { readMeta, getHelpersDir } from '../state.js';
 import { assertNameActiveInResourceProfile, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
 import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
-import { loadSession, deleteSession } from './session-store.js';
+import { GLOBAL_HARNESS } from './scope.js';
+import { resolveSession, deleteSession } from './session-store.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -1020,15 +1021,19 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  * True when the current process is a background / non-interactive context that
  * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
  * a prompt nobody is watching. Two signals, either sufficient:
- *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
- *     `agents run --headless`, scheduled routines, and teammates — see
- *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, runner.ts,
+ *     teams/agents.ts).
  *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
  *     stdio is redirected to a log — e.g. a release script run in the
  *     background as `( ... ) >log 2>&1 </dev/null`).
  * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
- * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -1039,9 +1044,13 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  *
  * 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 pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
+ * the per-caller broker-only pattern used across the headless secrets readers.
  */
-export function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
+// Injected so the TTY branch below is testable: it is the branch that decides a
+// plain human shell still prompts, which is this guard's entire safety argument,
+// and reading process.* directly made it unreachable from a test.
+tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
     if (platform !== 'darwin')
         return false; // no biometry prompt to suppress off-darwin
     const override = env.AGENTS_SECRETS_NO_PROMPT;
@@ -1049,10 +1058,21 @@ export function isHeadlessSecretsContext(env = process.env, platform = process.p
         return true;
     if (override === '0')
         return false;
+    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
+    // `terminal` was missing, which made an agent terminal the one launch path
+    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
+    // interactive run (exec.ts:430), that fell through to the TTY check below, and
+    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
+    // opening a terminal is not a request to authenticate, and a launch that needs
+    // a locked bundle should say so and point at `agents secrets unlock`, not grab
+    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
+    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
+    // correctly: there the agent, not the human, is the caller. A plain shell carries
+    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
     const runtime = env.AGENTS_RUNTIME;
-    if (runtime === 'headless' || runtime === 'teams')
+    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
         return true;
-    return !process.stdin.isTTY && !process.stdout.isTTY;
+    return !tty.stdin && !tty.stdout;
 }
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
@@ -1078,7 +1098,12 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     // file-backed bundle has none to dedup. The never-unlocked path is a single
     // stat (agentSocketExists) so it costs nothing when the agent isn't running.
     if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
-        const hit = agentGetSync(name);
+        // The scope this reader asks under. Falls back to the GLOBAL scope, not to a
+        // literal `'cli'` harness — the broker and the durable store both resolve
+        // own-harness → global (bundleScopeChain), so an unscoped unlock is visible
+        // here whether this process was launched by an agent or typed in a terminal.
+        const harness = opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS;
+        const hit = agentGetSync(name, harness);
         if (hit) {
             // The agent stores the FULL bundle env. Apply the same subset filter and
             // expiry gate as the slow path — without this, `--secrets-keys X` would
@@ -1102,13 +1127,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         // Touch ID. Serve from it and re-warm the broker, so a warm bundle stays warm
         // across restart — this fixes BOTH the interactive re-prompt and the headless
         // throw below (which now fires only when there is genuinely no session).
-        const session = loadSession(name);
-        if (session) {
+        const resolved = resolveSession(name, Date.now(), harness);
+        if (resolved) {
+            const session = resolved.entry;
             const filtered = filterAgentHitBySubsetAndExpiry({ bundle: session.bundle, env: session.env }, opts);
             stampLastUsed(filtered.bundle);
             // Re-warm the broker with the remaining TTL so later reads hit RAM and
-            // `agents secrets status` is honest. Best-effort; no-ops off darwin.
-            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()));
+            // `agents secrets status` is honest. Re-warm under the scope the grant was
+            // MADE in (resolved.harness), never the asking scope — re-warming a global
+            // grant as `claude` would silently narrow it for every other harness.
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness);
             emit('secrets.get', {
                 module: 'secrets',
                 bundle: name,
@@ -1120,32 +1148,30 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    // The headless guard exists only to keep a Touch ID sheet off the interactive
-    // user's screen — so it must block ONLY reads that can actually raise one.
-    // A file-backed bundle resolves via passphrase with no prompt (handled below,
-    // never held by the broker). A `never`/no-ACL keychain bundle is written
-    // WITHOUT the biometry access control at every tier (see writeBundle), so its
-    // reads are fully silent (no Touch ID, no broker) — exactly like a file
-    // bundle, and exactly the "automation-only" tier a headless daemon reads
-    // (daemon.ts:readDaemonClaudeOAuthToken). Learning the policy here is itself
-    // prompt-less: metadata items are written no-ACL at every tier, so readBundle
-    // reads them silently. An unreadable metadata read is treated as prompt-risky
-    // (throw) — the safe default.
-    if (opts.agentOnly && backend === 'keychain') {
+    // Never/no-ACL bundles remain prompt-free regardless. No agent launch — harness,
+    // teammate, routine, or the always-on daemon — may raise the sheet itself.
+    // Explicit opt-in ONLY — a deliberate NARROWING of the agent-triggered approval
+    // added in RUSH-2032 (b99796f8 removed this throw so an agent could raise the
+    // sheet itself; 4eeada68 generalized the daemon rule into `!interactiveUnlock`).
+    // That default — true whenever an agent name was present — was the spec, not a
+    // bug. It is unwanted: each keychain read runs in its own helper process, so the
+    // biometric assertion never reuses and one agent launch meant one sheet per
+    // bundle. `agentOnly` decides alone now; a human in a plain shell carries no
+    // AGENTS_RUNTIME, so isHeadlessSecretsContext() is false, agentOnly is false, the
+    // guard never fires, and they still get their prompt. No caller passes this flag;
+    // it remains the seam for a future unlock path that wants the sheet on purpose.
+    const interactiveUnlock = opts.interactiveUnlock ?? false;
+    if (opts.agentOnly && backend === 'keychain' && !interactiveUnlock) {
         let noAclBundle = false;
         try {
             noAclBundle = bundlePolicy(readBundle(name)) === 'never';
         }
-        catch {
-            noAclBundle = false;
-        }
+        catch { /* fail closed */ }
         if (!noAclBundle) {
-            throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent, and this is a ` +
-                `headless/background process that must not raise a Touch ID prompt on the ` +
-                `interactive user's screen. Run 'agents secrets unlock ${name}' in a terminal ` +
-                `first, or set AGENTS_SECRETS_NO_PROMPT=0 to force an interactive prompt.`);
+            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.`);
         }
-        // never/no-ACL ⇒ fall through to the prompt-less keychain read below.
     }
     if (backend === 'file')
         assertFileBackendUsable(name);
@@ -1164,12 +1190,20 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const reason = opts.caller
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
-    void reason;
     // secretItems are storage names as enumerated (opaque hashed names on macOS
     // with #316 hashing active, cleartext elsewhere); metaItem is cleartext and
     // hashed inside getBatch. Deduped because the hashed enumeration spans the
     // bundle's whole namespace.
-    const fetched = store.getBatch([...new Set([metaItem, ...secretItems])]);
+    const fetched = backend === 'keychain'
+        ? getKeychainTokens([...new Set([metaItem, ...secretItems])], {
+            agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
+            bundle: name,
+            reason: opts.caller ? `to ${opts.caller}` : reason,
+            duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
+            defaultPolicy: secretsDefaultPolicy(),
+            forceDuration: Boolean(opts.duration),
+        })
+        : store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
         // For a file-backed bundle the metadata item is on disk (that's how
@@ -1297,7 +1331,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
-            agentAutoLoadSync(name, bundle, env, secretsHoldMs());
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS);
         }
         return { bundle, env };
     }
@@ -1306,6 +1340,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         throw err;
     }
 }
+export function humanUnlockDuration(ms) {
+    const days = Math.round(ms / (24 * 60 * 60 * 1000));
+    if (days >= 1)
+        return `${days} day${days === 1 ? '' : 's'}`;
+    const hours = Math.round(ms / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    const minutes = Math.max(1, Math.round(ms / (60 * 1000)));
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
 // Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;

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

@@ -210,7 +210,16 @@ export declare function hasKeychainToken(item: string): boolean;
  * call in the same process). For bundles, prefer getKeychainTokens() so a
  * single biometric prompt covers every key in the batch.
  */
-export declare function getKeychainToken(item: string): string;
+export interface KeychainReadContext {
+    agent?: string;
+    bundle?: string;
+    reason?: string;
+    duration?: string;
+    defaultPolicy?: 'daily' | 'always' | 'never';
+    forceDuration?: boolean;
+}
+export declare function keychainOperationPrompt(context?: KeychainReadContext): string;
+export declare function getKeychainToken(item: string, context?: KeychainReadContext): string;
 /**
  * Batch-read multiple keychain items behind a single Touch ID prompt. The
  * macOS helper holds one LAContext for its whole process: the first protected
@@ -221,7 +230,7 @@ export declare function getKeychainToken(item: string): string;
  * On Linux or when a test backend is installed, falls back to individual
  * lookups — no biometric prompt path on those platforms.
  */
-export declare function getKeychainTokens(items: string[]): Map<string, string>;
+export declare function getKeychainTokens(items: string[], context?: KeychainReadContext): Map<string, string>;
 /** Store or update a secret value in the keychain/keyring. Device-local;
  * biometry-gated on macOS. `opts.noAcl` (the `never` prompt-policy) writes our
  * item WITHOUT the biometry access control so later reads are fully silent — it

package/dist/lib/secrets/index.js

@@ -707,14 +707,14 @@ export function hasKeychainToken(item) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-/**
- * Retrieve a secret value from the keychain/keyring. Throws if not found.
- *
- * On macOS this triggers Touch ID (or reuses an assertion held by an earlier
- * call in the same process). For bundles, prefer getKeychainTokens() so a
- * single biometric prompt covers every key in the batch.
- */
-export function getKeychainToken(item) {
+export function keychainOperationPrompt(context = {}) {
+    const agent = context.agent || 'Agents CLI';
+    const bundle = context.bundle ? ` the '${context.bundle}' bundle` : ' secrets';
+    const duration = context.duration ? ` for ${context.duration}` : '';
+    const reason = context.reason ? ` ${context.reason}` : '';
+    return `${agent} is requesting to unlock${bundle}${duration}${reason}.`;
+}
+export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
     // an opaque hash.
     const requested = item;
@@ -739,6 +739,11 @@ export function getKeychainToken(item) {
     }
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['get', item, os.userInfo().username], {
+        env: {
+            ...process.env,
+            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.status === 1)
@@ -764,7 +769,7 @@ export function getKeychainToken(item) {
  * On Linux or when a test backend is installed, falls back to individual
  * lookups — no biometric prompt path on those platforms.
  */
-export function getKeychainTokens(items) {
+export function getKeychainTokens(items, context = {}) {
     const result = new Map();
     if (items.length === 0)
         return result;
@@ -811,6 +816,13 @@ export function getKeychainTokens(items) {
     }
     const bin = getKeychainHelperPath();
     const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...storageItems], {
+        env: {
+            ...process.env,
+            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_DEFAULT_POLICY: context.defaultPolicy || 'daily',
+            AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (child.status === 4) {

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

@@ -0,0 +1,26 @@
+/**
+ * Harness scoping for an unlocked bundle — the shared vocabulary of the broker
+ * (agent.ts), the durable session store (session-store.ts), and the read path
+ * (bundles.ts).
+ *
+ * A grant is stored under a scope and read under a scope; the two must agree or
+ * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * a grant to one harness, so an unlock without it is global by definition.
+ *
+ * This module deliberately has NO imports: agent.ts and session-store.ts already
+ * import each other, and hanging the scope constants off either one would close
+ * that cycle — under ESM a cyclic `const` read can land in the temporal dead zone
+ * and throw at runtime even though tsc is happy.
+ */
+/**
+ * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * harness. Not a valid harness name, so it can never collide with one.
+ */
+export declare const GLOBAL_HARNESS = "*";
+/**
+ * Scopes a reader consults, most specific first: its own harness, then the global
+ * grant. This is the resolution order of the scoped-grant model — a narrow
+ * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * everyone — not a fallback papering over a miss.
+ */
+export declare function bundleScopeChain(harness: string | undefined): string[];

package/dist/lib/secrets/scope.js

@@ -0,0 +1,29 @@
+/**
+ * Harness scoping for an unlocked bundle — the shared vocabulary of the broker
+ * (agent.ts), the durable session store (session-store.ts), and the read path
+ * (bundles.ts).
+ *
+ * A grant is stored under a scope and read under a scope; the two must agree or
+ * the bundle is invisible. `agents secrets unlock --for <agent>` exists to NARROW
+ * a grant to one harness, so an unlock without it is global by definition.
+ *
+ * This module deliberately has NO imports: agent.ts and session-store.ts already
+ * import each other, and hanging the scope constants off either one would close
+ * that cycle — under ESM a cyclic `const` read can land in the temporal dead zone
+ * and throw at runtime even though tsc is happy.
+ */
+/**
+ * Scope of an unlock that was not narrowed with `--for`: readable by every
+ * harness. Not a valid harness name, so it can never collide with one.
+ */
+export const GLOBAL_HARNESS = '*';
+/**
+ * Scopes a reader consults, most specific first: its own harness, then the global
+ * grant. This is the resolution order of the scoped-grant model — a narrow
+ * `--for claude` unlock stays claude-only while an unscoped unlock serves
+ * everyone — not a fallback papering over a miss.
+ */
+export function bundleScopeChain(harness) {
+    const own = harness || GLOBAL_HARNESS;
+    return own === GLOBAL_HARNESS ? [GLOBAL_HARNESS] : [own, GLOBAL_HARNESS];
+}

package/dist/lib/secrets/session-store.d.ts

@@ -38,12 +38,14 @@ export interface SessionEntry {
     expiresAt: number;
     /** true only for `--durable` unlocks — survives SLEEP. */
     sleepPersist: boolean;
+    harness?: string;
 }
 /** Metadata for one held bundle, kept in the index so we can rehydrate / prune
  * without reading every blob. */
 export interface SessionIndexMeta {
     expiresAt: number;
     sleepPersist: boolean;
+    harness?: string;
 }
 export interface SessionIndex {
     bundles: Record<string, SessionIndexMeta>;
@@ -72,10 +74,22 @@ export declare function readIndex(): SessionIndex;
 export declare function writeIndex(index: SessionIndex): void;
 /** Persist one unlocked bundle: write its blob no-ACL and record it in the index. */
 export declare function saveSession(name: string, entry: SessionEntry): void;
+/**
+ * Read a session honoring the scope chain: the caller's own harness first, then
+ * the global grant (see bundleScopeChain in scope.ts). This is the durable-store
+ * twin of the broker's `get` — both must resolve identically, or a bundle would
+ * be readable from RAM but not after a restart.
+ */
+export declare function resolveSession(name: string, now?: number, harness?: string): {
+    entry: SessionEntry;
+    harness: string;
+} | null;
 /** Read one session blob by known name. Null when absent/expired/malformed. */
-export declare function loadSession(name: string, now?: number): SessionEntry | null;
+export declare function loadSession(name: string, now?: number, harness?: string): SessionEntry | null;
+/** Remove every persisted harness grant for one bundle. */
+export declare function deleteBundleSessions(name: string): void;
 /** Delete one bundle's session blob and prune it from the index. */
-export declare function deleteSession(name: string): void;
+export declare function deleteSession(name: string, harness?: string): void;
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export declare function deleteAllSessions(): void;
 /** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to

package/dist/lib/secrets/session-store.js

@@ -25,6 +25,7 @@
  * persistence is an optimization, not a correctness dependency.
  */
 import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden } from './index.js';
+import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
 /** Prefix for all durable session items (device-local, no-ACL). */
 export const SESSION_ITEM_PREFIX = 'agents-cli.session.';
 /** Fixed-name index item — the ONLY thing we ever need to find without a known
@@ -82,8 +83,8 @@ export function removeEntry(index, name) {
 function shouldPersist() {
     return process.platform === 'darwin' || isKeychainBackendOverridden();
 }
-function sessionBlobItem(name) {
-    return `${SESSION_ITEM_PREFIX}${name}`;
+function sessionBlobItem(name, harness) {
+    return `${SESSION_ITEM_PREFIX}${harness}.${name}`;
 }
 /** Read the session index by its fixed name. `{bundles:{}}` when absent/unreadable. */
 export function readIndex() {
@@ -116,24 +117,40 @@ export function saveSession(name, entry) {
     if (!shouldPersist())
         return;
     try {
-        setKeychainToken(sessionBlobItem(name), JSON.stringify(entry), { noAcl: true });
-        writeIndex(upsertEntry(readIndex(), name, { expiresAt: entry.expiresAt, sleepPersist: entry.sleepPersist }));
+        const harness = entry.harness || GLOBAL_HARNESS;
+        const key = `${harness}:${name}`;
+        setKeychainToken(sessionBlobItem(name, harness), JSON.stringify({ ...entry, harness }), { noAcl: true });
+        writeIndex(upsertEntry(readIndex(), key, { expiresAt: entry.expiresAt, sleepPersist: entry.sleepPersist, harness }));
     }
     catch {
         /* best-effort — persistence is an optimization */
     }
 }
+/**
+ * Read a session honoring the scope chain: the caller's own harness first, then
+ * the global grant (see bundleScopeChain in scope.ts). This is the durable-store
+ * twin of the broker's `get` — both must resolve identically, or a bundle would
+ * be readable from RAM but not after a restart.
+ */
+export function resolveSession(name, now = Date.now(), harness = GLOBAL_HARNESS) {
+    for (const scope of bundleScopeChain(harness)) {
+        const entry = loadSession(name, now, scope);
+        if (entry)
+            return { entry, harness: scope };
+    }
+    return null;
+}
 /** Read one session blob by known name. Null when absent/expired/malformed. */
-export function loadSession(name, now = Date.now()) {
+export function loadSession(name, now = Date.now(), harness = GLOBAL_HARNESS) {
     if (!shouldPersist())
         return null;
     try {
-        const raw = getKeychainToken(sessionBlobItem(name));
+        const raw = getKeychainToken(sessionBlobItem(name, harness));
         const entry = JSON.parse(raw);
         if (!entry || typeof entry !== 'object' || !entry.bundle || !entry.env)
             return null;
         if (now >= entry.expiresAt) {
-            deleteSession(name); // drop expired on read, mirroring the broker's get handler
+            deleteSession(name, harness); // drop expired on read
             return null;
         }
         return entry;
@@ -142,13 +159,32 @@ export function loadSession(name, now = Date.now()) {
         return null;
     }
 }
+/** Remove every persisted harness grant for one bundle. */
+export function deleteBundleSessions(name) {
+    if (!shouldPersist())
+        return;
+    const index = readIndex();
+    let next = index;
+    for (const [key, meta] of Object.entries(index.bundles)) {
+        const scopedName = key.includes(':') ? key.split(':').slice(1).join(':') : key;
+        if (scopedName !== name)
+            continue;
+        const harness = meta.harness || GLOBAL_HARNESS;
+        try {
+            deleteKeychainToken(key.includes(':') ? sessionBlobItem(name, harness) : `${SESSION_ITEM_PREFIX}${name}`);
+        }
+        catch { /* keep going */ }
+        next = removeEntry(next, key);
+    }
+    writeIndex(next);
+}
 /** Delete one bundle's session blob and prune it from the index. */
-export function deleteSession(name) {
+export function deleteSession(name, harness = GLOBAL_HARNESS) {
     if (!shouldPersist())
         return;
     try {
-        deleteKeychainToken(sessionBlobItem(name));
-        writeIndex(removeEntry(readIndex(), name));
+        deleteKeychainToken(sessionBlobItem(name, harness));
+        writeIndex(removeEntry(readIndex(), `${harness}:${name}`));
     }
     catch {
         /* best-effort */
@@ -160,8 +196,12 @@ export function deleteAllSessions() {
         return;
     try {
         for (const name of Object.keys(readIndex().bundles)) {
+            const meta = readIndex().bundles[name];
+            const bundleName = name.includes(':') ? name.split(':').slice(1).join(':') : name;
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(name.includes(':')
+                    ? sessionBlobItem(bundleName, meta.harness || GLOBAL_HARNESS)
+                    : `${SESSION_ITEM_PREFIX}${bundleName}`);
             }
             catch { /* keep going */ }
         }
@@ -180,19 +220,81 @@ export function rehydrateSessions(now = Date.now()) {
     const out = [];
     try {
         const index = readIndex();
+        // One-time source migration from the pre-harness layout. Move each legacy
+        // bundle-name index/blob to the explicit cli scope, then delete the old blob.
+        let migratedIndex = index;
+        for (const [key, meta] of Object.entries(index.bundles)) {
+            if (key.includes(':'))
+                continue;
+            try {
+                const raw = getKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                const legacy = JSON.parse(raw);
+                setKeychainToken(sessionBlobItem(key, GLOBAL_HARNESS), JSON.stringify({ ...legacy, harness: GLOBAL_HARNESS }), { noAcl: true });
+                deleteKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                migratedIndex = upsertEntry(removeEntry(migratedIndex, key), `${GLOBAL_HARNESS}:${key}`, {
+                    expiresAt: meta.expiresAt,
+                    sleepPersist: meta.sleepPersist,
+                    harness: GLOBAL_HARNESS,
+                });
+            }
+            catch { /* malformed/absent legacy entry is pruned below */ }
+        }
+        // Second source migration: `cli`-scoped grants predate the global scope. `cli`
+        // was never a harness — it was the default when no AGENTS_AGENT_NAME was set,
+        // i.e. "unlocked from a terminal for general use", which is exactly the global
+        // grant. Rewriting them means an unlock a user already paid Touch ID for keeps
+        // working after upgrade instead of silently becoming unreadable to every agent.
+        for (const [key, meta] of Object.entries(migratedIndex.bundles)) {
+            if (!key.startsWith('cli:'))
+                continue;
+            const bundleName = key.slice('cli:'.length);
+            const globalKey = `${GLOBAL_HARNESS}:${bundleName}`;
+            // A global grant for this bundle can already exist: the user re-runs
+            // `unlock` on the new code (which writes the global scope) before the
+            // broker restarts to run this migration. The existing global grant is the
+            // NEWER one, so the stale `cli` entry is discarded, never merged over it —
+            // overwriting would restore a superseded token and, if the stale entry had
+            // expired, hand its expiry to the fresh grant so the prune below deletes a
+            // valid unlock outright.
+            if (migratedIndex.bundles[globalKey]) {
+                try {
+                    deleteKeychainToken(sessionBlobItem(bundleName, 'cli'));
+                }
+                catch { /* already gone */ }
+                migratedIndex = removeEntry(migratedIndex, key);
+                continue;
+            }
+            try {
+                const raw = getKeychainToken(sessionBlobItem(bundleName, 'cli'));
+                const legacy = JSON.parse(raw);
+                setKeychainToken(sessionBlobItem(bundleName, GLOBAL_HARNESS), JSON.stringify({ ...legacy, harness: GLOBAL_HARNESS }), { noAcl: true });
+                deleteKeychainToken(sessionBlobItem(bundleName, 'cli'));
+                migratedIndex = upsertEntry(removeEntry(migratedIndex, key), globalKey, {
+                    expiresAt: meta.expiresAt,
+                    sleepPersist: meta.sleepPersist,
+                    harness: GLOBAL_HARNESS,
+                });
+            }
+            catch { /* malformed/absent entry is pruned below */ }
+        }
+        writeIndex(migratedIndex);
+        index.bundles = migratedIndex.bundles;
         const { survivors, expiredNames } = pruneExpired(index, now);
         for (const name of expiredNames) {
+            const meta = index.bundles[name];
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(sessionBlobItem(name.split(':').slice(1).join(':'), meta.harness || GLOBAL_HARNESS));
             }
             catch { /* keep going */ }
         }
         if (expiredNames.length)
             writeIndex(survivors);
         for (const name of selectRehydratable(survivors, now)) {
-            const entry = loadSession(name, now);
+            const meta = survivors.bundles[name];
+            const bundleName = name.split(':').slice(1).join(':');
+            const entry = loadSession(bundleName, now, meta.harness || GLOBAL_HARNESS);
             if (entry)
-                out.push({ name, entry });
+                out.push({ name: bundleName, entry });
         }
     }
     catch {
@@ -208,8 +310,9 @@ export function pruneSessionsOnSleep() {
     try {
         const { survivors, deletedNames } = pruneOnSleep(readIndex());
         for (const name of deletedNames) {
+            const meta = readIndex().bundles[name];
             try {
-                deleteKeychainToken(sessionBlobItem(name));
+                deleteKeychainToken(sessionBlobItem(name.split(':').slice(1).join(':'), meta.harness || GLOBAL_HARNESS));
             }
             catch { /* keep going */ }
         }

package/dist/lib/secrets/unlock-hints.d.ts

@@ -0,0 +1,27 @@
+/** The subset of a `secrets.get` event this heuristic reads. */
+export interface SecretGetRecord {
+    /** Bundle name the read targeted. */
+    bundle?: string;
+    /** Where the value came from: `agent` (broker hit) / `session` (durable
+     *  unlock) are SILENT; anything else hit the keychain and thus prompted. */
+    source?: string;
+}
+export interface PromptedBundle {
+    name: string;
+    /** Number of prompting (keychain) reads in the window. */
+    count: number;
+}
+/**
+ * From recent `secrets.get` records, find bundles read often enough via the
+ * keychain (i.e. NOT served silently by the broker or a durable session) to be
+ * worth unlocking once. A bundle currently `held` is already silent, so it is
+ * excluded; the caller further drops `never`/no-ACL bundles (which never prompt,
+ * so unlocking them is a no-op).
+ *
+ * @param records recent `secrets.get` events (any order)
+ * @param held    bundle names the broker currently holds (silent reads)
+ * @param opts.minReads minimum prompting reads to surface a bundle (default 3)
+ */
+export declare function frequentlyPromptedBundles(records: SecretGetRecord[], held: Set<string>, opts?: {
+    minReads?: number;
+}): PromptedBundle[];