@phnx-labs/agents-cli 1.20.76 → 1.20.77

package/dist/lib/secrets/bundles.js

@@ -1020,15 +1020,19 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  * True when the current process is a background / non-interactive context that
  * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
  * a prompt nobody is watching. Two signals, either sufficient:
- *   - `AGENTS_RUNTIME` is `headless` or `teams` (set on the child env by
- *     `agents run --headless`, scheduled routines, and teammates — see
- *     exec.ts:resolveInteractive, runner.ts, teams/agents.ts).
+ *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
+ *     launch, interactive included, and inherited by everything spawned beneath
+ *     one (set on the child env by `agents run --headless`, scheduled routines,
+ *     teammates, and interactive runs — see exec.ts:430, runner.ts,
+ *     teams/agents.ts).
  *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
  *     stdio is redirected to a log — e.g. a release script run in the
  *     background as `( ... ) >log 2>&1 </dev/null`).
  * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An interactive `eval "$(agents secrets export X)"`
- * keeps its terminal stdin, so it is NOT classified headless and still prompts.
+ * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
+ * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
+ * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
+ * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -1041,7 +1045,11 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
  * the per-caller pattern already used by the daemon (daemon.ts:readDaemonClaudeOAuthToken).
  */
-export function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
+// Injected so the TTY branch below is testable: it is the branch that decides a
+// plain human shell still prompts, which is this guard's entire safety argument,
+// and reading process.* directly made it unreachable from a test.
+tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
     if (platform !== 'darwin')
         return false; // no biometry prompt to suppress off-darwin
     const override = env.AGENTS_SECRETS_NO_PROMPT;
@@ -1049,10 +1057,21 @@ export function isHeadlessSecretsContext(env = process.env, platform = process.p
         return true;
     if (override === '0')
         return false;
+    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
+    // `terminal` was missing, which made an agent terminal the one launch path
+    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
+    // interactive run (exec.ts:430), that fell through to the TTY check below, and
+    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
+    // opening a terminal is not a request to authenticate, and a launch that needs
+    // a locked bundle should say so and point at `agents secrets unlock`, not grab
+    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
+    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
+    // correctly: there the agent, not the human, is the caller. A plain shell carries
+    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
     const runtime = env.AGENTS_RUNTIME;
-    if (runtime === 'headless' || runtime === 'teams')
+    if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
         return true;
-    return !process.stdin.isTTY && !process.stdout.isTTY;
+    return !tty.stdin && !tty.stdout;
 }
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
@@ -1078,7 +1097,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     // file-backed bundle has none to dedup. The never-unlocked path is a single
     // stat (agentSocketExists) so it costs nothing when the agent isn't running.
     if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
-        const hit = agentGetSync(name);
+        const harness = opts.agent || process.env.AGENTS_AGENT_NAME || 'cli';
+        const hit = agentGetSync(name, harness);
         if (hit) {
             // The agent stores the FULL bundle env. Apply the same subset filter and
             // expiry gate as the slow path — without this, `--secrets-keys X` would
@@ -1102,13 +1122,13 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         // Touch ID. Serve from it and re-warm the broker, so a warm bundle stays warm
         // across restart — this fixes BOTH the interactive re-prompt and the headless
         // throw below (which now fires only when there is genuinely no session).
-        const session = loadSession(name);
+        const session = loadSession(name, Date.now(), harness);
         if (session) {
             const filtered = filterAgentHitBySubsetAndExpiry({ bundle: session.bundle, env: session.env }, opts);
             stampLastUsed(filtered.bundle);
             // Re-warm the broker with the remaining TTL so later reads hit RAM and
             // `agents secrets status` is honest. Best-effort; no-ops off darwin.
-            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()));
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), harness);
             emit('secrets.get', {
                 module: 'secrets',
                 bundle: name,
@@ -1120,32 +1140,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 +1182,20 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const reason = opts.caller
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
-    void reason;
     // secretItems are storage names as enumerated (opaque hashed names on macOS
     // with #316 hashing active, cleartext elsewhere); metaItem is cleartext and
     // hashed inside getBatch. Deduped because the hashed enumeration spans the
     // bundle's whole namespace.
-    const fetched = store.getBatch([...new Set([metaItem, ...secretItems])]);
+    const fetched = backend === 'keychain'
+        ? getKeychainTokens([...new Set([metaItem, ...secretItems])], {
+            agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
+            bundle: name,
+            reason: opts.caller ? `to ${opts.caller}` : reason,
+            duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
+            defaultPolicy: secretsDefaultPolicy(),
+            forceDuration: Boolean(opts.duration),
+        })
+        : store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
         // For a file-backed bundle the metadata item is on disk (that's how
@@ -1297,7 +1323,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
-            agentAutoLoadSync(name, bundle, env, secretsHoldMs());
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || 'cli');
         }
         return { bundle, env };
     }
@@ -1306,6 +1332,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         throw err;
     }
 }
+export function humanUnlockDuration(ms) {
+    const days = Math.round(ms / (24 * 60 * 60 * 1000));
+    if (days >= 1)
+        return `${days} day${days === 1 ? '' : 's'}`;
+    const hours = Math.round(ms / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `${hours} hour${hours === 1 ? '' : 's'}`;
+    const minutes = Math.max(1, Math.round(ms / (60 * 1000)));
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
 // Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;

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

@@ -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/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>;
@@ -73,9 +75,11 @@ 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 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

@@ -82,8 +82,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 +116,26 @@ 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 || 'cli';
+        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 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 = 'cli') {
     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 +144,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 || 'cli';
+        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 = 'cli') {
     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 +181,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 || 'cli')
+                    : `${SESSION_ITEM_PREFIX}${bundleName}`);
             }
             catch { /* keep going */ }
         }
@@ -180,19 +205,43 @@ 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, 'cli'), JSON.stringify({ ...legacy, harness: 'cli' }), { noAcl: true });
+                deleteKeychainToken(`${SESSION_ITEM_PREFIX}${key}`);
+                migratedIndex = upsertEntry(removeEntry(migratedIndex, key), `cli:${key}`, {
+                    expiresAt: meta.expiresAt,
+                    sleepPersist: meta.sleepPersist,
+                    harness: 'cli',
+                });
+            }
+            catch { /* malformed/absent legacy 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 || 'cli'));
             }
             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 || 'cli');
             if (entry)
-                out.push({ name, entry });
+                out.push({ name: bundleName, entry });
         }
     }
     catch {
@@ -208,8 +257,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 || 'cli'));
             }
             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[];

package/dist/lib/secrets/unlock-hints.js

@@ -0,0 +1,36 @@
+// Usage-based unlock hints: surface bundles you keep getting a Touch ID prompt
+// for, so `agents secrets status` can suggest unlocking them once instead of
+// prompting on every read. Built on the existing `secrets.get` audit events
+// (events.jsonl) — no new tracking. Pure + exported so the threshold/filter
+// logic is unit-testable without the events sink or the keychain.
+/**
+ * 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 function frequentlyPromptedBundles(records, held, opts = {}) {
+    const minReads = opts.minReads ?? 3;
+    const counts = new Map();
+    for (const r of records) {
+        if (!r.bundle)
+            continue;
+        // A broker hit or a durable-session read raised no Touch ID sheet — only a
+        // read that fell through to the keychain did. Count those; they are the ones
+        // an unlock would silence.
+        if (r.source === 'agent' || r.source === 'session')
+            continue;
+        if (held.has(r.bundle))
+            continue;
+        counts.set(r.bundle, (counts.get(r.bundle) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, n]) => n >= minReads)
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}

package/dist/lib/session/active.d.ts

@@ -4,6 +4,7 @@ import { type HookSessionIndex } from './hook-sessions.js';
 import { type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import type { SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
+import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
@@ -353,6 +354,15 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * Match an SSH client IP to a registered device (pure — testable with a plain
+ * registry object). Returns the device name + ssh login user when the IP is a
+ * known device address.
+ */
+export declare function matchOriginDevice(clientIp: string, reg: DeviceRegistry): {
+    device: string;
+    user?: string;
+} | undefined;
 /**
  * Collapse rows that resolve to the *same* session — a session with many
  * subagent/fork PIDs (all matched to one transcript file) would otherwise print

package/dist/lib/session/active.js

@@ -34,6 +34,7 @@ import { readSessionTailWithRaw } from './tail.js';
 import { computeTokPerSec } from './throughput.js';
 import { inferSessionState } from './state.js';
 import { detectProvenance } from './provenance.js';
+import { loadDevices } from '../devices/registry.js';
 import { presenceFromStore } from './detached.js';
 import { mapBounded } from '../concurrency.js';
 const execFileAsync = promisify(execFile);
@@ -1081,8 +1082,11 @@ export async function listTmuxAgentSessions() {
         const pidAlive = pid ? isPidAlive(pid, liveEntry?.startedAtMs) : true;
         const { state, tokPerSec } = computeLiveSignals(id.agent, sessionFile, cwd, pidAlive);
         const { birthtimeMs, mtimeMs } = sessionFileTimes(sessionFile);
-        // Provenance is known exactly here (the pane IS a tmux pane) — set it so
-        // enrichProvenance skips it and the locator/reply rails resolve off the pane.
+        // The mux/reply rails are known exactly here (the pane IS a tmux pane), so we
+        // stamp them off the pane. `transport:'local'` is only a placeholder: the pane
+        // can't reveal how the shell above it was reached. enrichProvenance later reads
+        // the pane process's env and upgrades this to 'ssh' (with the real origin) when
+        // SSH_CONNECTION is present, while preserving this mux/reply.
         const provenance = {
             host: os.hostname(),
             transport: 'local',
@@ -1135,6 +1139,7 @@ export async function getActiveSessions(opts = {}) {
     const unattributed = opts.skipHeadless ? [] : await listUnattributedActive(knownPids);
     const merged = dedupeBySession([...tmuxAgents, ...teams, ...terminals, ...cloud, ...unattributed]);
     await enrichProvenance(merged);
+    await resolveOrigins(merged);
     foldPresence(merged);
     return merged;
 }
@@ -1161,14 +1166,72 @@ function foldPresence(rows) {
  * each session once, not once per fork pid. Probes run in parallel — each is a
  * single /proc read (Linux) or `ps` call (macOS); failures leave `provenance`
  * undefined rather than blocking the listing.
+ *
+ * A row that already carries provenance (the tmux path, which knows its exact
+ * mux/reply from the pane) is not skipped — it is probe-and-MERGED. The tmux
+ * path can only stamp a `transport:'local'` placeholder because the pane alone
+ * doesn't reveal how the shell above it was reached; the process env does. So we
+ * still read the env and fill in the real SSH origin/term, while preserving the
+ * authoritative mux/reply the pane already gave us. Skipping this (the old
+ * behavior) is exactly why ssh-launched tmux sessions rendered as local.
  */
 async function enrichProvenance(sessions) {
     await Promise.all(sessions.map(async (s) => {
-        if (s.provenance || !s.pid)
+        if (!s.pid)
+            return;
+        const probed = await detectProvenance(s.pid);
+        if (!probed)
+            return;
+        if (!s.provenance) {
+            s.provenance = probed;
             return;
-        s.provenance = await detectProvenance(s.pid);
+        }
+        // Row already carries exact mux/reply (the tmux path). Fill only what a
+        // pre-set provenance can't know from the pane alone: the real launch origin.
+        if (probed.transport === 'ssh' && !s.provenance.ssh) {
+            s.provenance.transport = 'ssh';
+            s.provenance.ssh = probed.ssh;
+        }
+        if (probed.term && !s.provenance.term)
+            s.provenance.term = probed.term;
     }));
 }
+/**
+ * Match an SSH client IP to a registered device (pure — testable with a plain
+ * registry object). Returns the device name + ssh login user when the IP is a
+ * known device address.
+ */
+export function matchOriginDevice(clientIp, reg) {
+    for (const d of Object.values(reg)) {
+        if (d.address?.ip && d.address.ip === clientIp) {
+            return { device: d.name, ...(d.user ? { user: d.user } : {}) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the initiating device for every ssh-transport session by matching its
+ * `ssh.clientIp` against the device registry. Read-only and best-effort: a
+ * registry that can't be loaded, or an IP that matches no device, leaves
+ * `origin` undefined (the raw client IP is still on `ssh`). Mutates in place.
+ */
+async function resolveOrigins(sessions) {
+    const needing = sessions.filter((s) => s.provenance?.ssh && !s.provenance.origin);
+    if (needing.length === 0)
+        return;
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        return;
+    }
+    for (const s of needing) {
+        const match = matchOriginDevice(s.provenance.ssh.clientIp, reg);
+        if (match)
+            s.provenance.origin = match;
+    }
+}
 /**
  * Identity for a row the scan could not tie to a session: a daemon's worker
  * processes (an OpenClaw gateway spawning `codex`, a supervisor pool) have no