@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/secrets/audit.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical audit emitter for `agents secrets` value access and unlock grants.
+ *
+ * Every path that reads a secret VALUE or grants an unlock funnels its audit
+ * through here, so the operational event stream — `agents events`, backed by the
+ * append-only `~/.agents/events.jsonl` audit log — carries a uniform, value-free
+ * provenance record: bundle, key NAMES, the resolving agent/harness identity,
+ * operation, source, status. The ts / host / session / caller fields are filled
+ * in by `emit()` itself. The secret VALUE is never part of the payload; this
+ * helper only ever receives metadata, and `emit()`'s `sanitizePayload` is a
+ * second redaction layer.
+ *
+ * Two event types, both audit-level and non-milestone (so they surface in
+ * `agents events` and the persisted audit trail, but are NOT required in the
+ * curated `agents activity` / `agents feed` surfaces):
+ *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
+ *                         raw `get <item>`, remote resolve, sync push,
+ *                         `run --secrets`, and every other bundle read).
+ *  - `secrets.unlocked` — a bundle was GRANTED into the secrets broker / durable
+ *                         session by `agents secrets unlock`, then readable
+ *                         prompt-free for the grant TTL.
+ */
+import { emit } from '../events.js';
+/**
+ * The agent/harness identity to attribute a secret access to. Explicit callers
+ * (the bundle reader knows the scope it resolved under) win; otherwise fall back
+ * to the ambient `$AGENTS_AGENT_NAME` set on every agent launch.
+ */
+export function resolveAuditAgent(explicit) {
+    const a = explicit || process.env.AGENTS_AGENT_NAME;
+    return a && a.length > 0 ? a : undefined;
+}
+/**
+ * Emit one value-free secret audit event to the raw/operational event stream and
+ * the persisted audit log. Only ever pass metadata — the secret value must never
+ * reach this function.
+ */
+export function emitSecretAudit(p) {
+    const agent = resolveAuditAgent(p.agent);
+    emit(p.event, {
+        module: 'secrets',
+        ...(p.bundle !== undefined ? { bundle: p.bundle } : {}),
+        ...(p.item !== undefined ? { item: p.item } : {}),
+        ...(p.operation !== undefined ? { operation: p.operation } : {}),
+        ...(p.source !== undefined ? { source: p.source } : {}),
+        ...(p.status !== undefined ? { status: p.status } : {}),
+        ...(p.keys !== undefined ? { keys: p.keys } : {}),
+        ...(p.keyCount !== undefined ? { keyCount: p.keyCount } : {}),
+        ...(p.keychainKeys !== undefined ? { keychainKeys: p.keychainKeys } : {}),
+        ...(p.kindCounts !== undefined ? { kindCounts: p.kindCounts } : {}),
+        ...(agent !== undefined ? { agent } : {}),
+        ...(p.host !== undefined ? { host: p.host } : {}),
+        ...(p.ttlMs !== undefined ? { ttlMs: p.ttlMs } : {}),
+        ...(p.error !== undefined ? { error: p.error } : {}),
+    });
+}

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

@@ -43,7 +43,9 @@ export interface VarMeta {
 }
 /**
  * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
- * - `daily` (default): ask once, then hold it silently for up to ~7 days.
+ * - `hold` (default): ask once, then serve it silently for the configured hold
+ *   duration (`secrets.agent.holdMs`, 7d by default). Named for what it does —
+ *   it was called `daily`, which stated a period it never had.
  *   (Historical name — the window is now a rolling ~1 week, not one calendar day.)
  *   Eligible for the secrets-agent — the first real keychain read auto-loads it
  *   (auto-cache is on by default) so concurrent runs read it silently, or `unlock`
@@ -61,12 +63,12 @@ export interface VarMeta {
  *   it loudly rather than silently downgrading to `always`.
  *
  * The default is configurable via `secrets.policy` in agents.yaml. Stored on disk
- * under the legacy `tier` key (`session` == `daily`, `biometry` == explicit
+ * under the legacy `tier` key (`session` == `hold`, `biometry` == explicit
  * `always`, `none` == `never`, absent == inherit the default) so bundles stay
  * readable across mixed CLI versions on synced machines. The user-facing
- * vocabulary is `policy`/`always`/`daily`/`never`.
+ * vocabulary is `policy`/`always`/`hold`/`never`.
  */
-export type SecretsPolicy = 'always' | 'daily' | 'never';
+export type SecretsPolicy = 'always' | 'hold' | 'never';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
@@ -74,7 +76,7 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
     backend?: SecretsBackend;
-    /** Prompt policy. Absent ⇒ the configured default (`daily`). Serialized under
+    /** Prompt policy. Absent ⇒ the configured default (`hold`). Serialized under
      * the legacy `tier` key — see SecretsPolicy. */
     policy?: SecretsPolicy;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
@@ -142,9 +144,10 @@ export declare class BundleUndecryptableError extends Error {
 export declare function readBundleIfDecryptable(name: string): SecretsBundle | null;
 export declare function readBundle(name: string): SecretsBundle;
 /** The default prompt policy applied to bundles without an explicit per-bundle
- * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
- * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+ * policy. Configurable via `secrets.policy` in agents.yaml; `hold` (one Touch ID
+ * per hold window — `secrets.agent.holdMs`, 7d by default) unless the user
+ * explicitly opts back into prompt-every-time with `always`. Best-effort: an
+ * unreadable config falls back to the `hold` default. */
 export declare function secretsDefaultPolicy(): SecretsPolicy;
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
@@ -301,7 +304,7 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  *
  * 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 declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
     stdin?: boolean;

package/dist/lib/secrets/bundles.js

@@ -28,10 +28,12 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { getVaultSession, vaultDeleteItem, vaultExists, vaultGetItems, vaultGetItem, vaultHasItem, vaultListItems, vaultSetItems, vaultSetItem, } from './vault.js';
 import { emit } from '../events.js';
+import { emitSecretAudit } from './audit.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,
@@ -323,7 +325,7 @@ export function readBundle(name) {
         // Absent ⇒ keychain; only set when non-keychain so a keychain bundle
         // round-trips byte-for-byte.
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -342,14 +344,14 @@ export function readBundle(name) {
     return bundle;
 }
 /** Normalize the persisted prompt policy. The on-disk `tier` key uses legacy
- * tokens for cross-version compatibility: `session` ⇒ `daily`, `biometry` ⇒ an
+ * tokens for cross-version compatibility: `session` ⇒ `hold`, `biometry` ⇒ an
  * explicit `always`. An absent token ⇒ undefined, which resolves to the
- * configured default policy (`daily`). Persisting an explicit `always` as the
- * legacy `biometry` token keeps older CLIs correct — they don't know `daily`,
+ * configured default policy (`hold`). Persisting an explicit `always` as the
+ * legacy `biometry` token keeps older CLIs correct — they don't know `hold`,
  * read `biometry` as undefined, and fall back to their own always default. */
 function parsePolicy(raw) {
-    if (raw === 'daily' || raw === 'session')
-        return 'daily';
+    if (raw === 'hold' || raw === 'daily' || raw === 'session')
+        return 'hold';
     if (raw === 'always' || raw === 'biometry')
         return 'always';
     if (raw === 'never' || raw === 'none')
@@ -357,15 +359,16 @@ function parsePolicy(raw) {
     return undefined;
 }
 /** The default prompt policy applied to bundles without an explicit per-bundle
- * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
- * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+ * policy. Configurable via `secrets.policy` in agents.yaml; `hold` (one Touch ID
+ * per hold window — `secrets.agent.holdMs`, 7d by default) unless the user
+ * explicitly opts back into prompt-every-time with `always`. Best-effort: an
+ * unreadable config falls back to the `hold` default. */
 export function secretsDefaultPolicy() {
     try {
-        return readMeta().secrets?.policy === 'always' ? 'always' : 'daily';
+        return readMeta().secrets?.policy === 'always' ? 'always' : 'hold';
     }
     catch {
-        return 'daily';
+        return 'hold';
     }
 }
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
@@ -433,12 +436,12 @@ function prepareBundleWrite(bundle) {
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'keychain' ? undefined : backend,
         // Wire format: persist the policy under the legacy `tier` token so older CLI
-        // versions on other synced machines keep reading it — `daily`⇒`session`,
+        // versions on other synced machines keep reading it — `hold`⇒`session`,
         // explicit `always`⇒`biometry`, `never`⇒`none`. An absent policy omits the
-        // token entirely and resolves to the configured default (`daily`) on read.
+        // token entirely and resolves to the configured default (`hold`) on read.
         // An older CLI that doesn't know `none` reads it as undefined and falls back
         // to its own default — safe, since it also lacks the no-ACL write path.
-        tier: bundle.policy === 'daily' ? 'session'
+        tier: bundle.policy === 'hold' ? 'session'
             : bundle.policy === 'always' ? 'biometry'
                 : bundle.policy === 'never' ? 'none'
                     : undefined,
@@ -545,7 +548,7 @@ function parseBundleMeta(nameHint, json, backend) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -1043,7 +1046,7 @@ 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, 
 // Injected so the TTY branch below is testable: it is the branch that decides a
@@ -1097,7 +1100,11 @@ 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 harness = opts.agent || process.env.AGENTS_AGENT_NAME || 'cli';
+        // 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
@@ -1106,13 +1113,14 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             // the first cache-populating run.
             const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
             stampLastUsed(filtered.bundle);
-            emit('secrets.get', {
-                module: 'secrets',
+            emitSecretAudit({
+                event: 'secrets.get',
                 bundle: name,
                 operation: opts.caller,
                 status: 'success',
                 source: 'agent',
                 keyCount: Object.keys(filtered.env).length,
+                agent: harness,
             });
             return filtered;
         }
@@ -1122,20 +1130,24 @@ 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, Date.now(), harness);
-        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()), harness);
-            emit('secrets.get', {
-                module: 'secrets',
+            // `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);
+            emitSecretAudit({
+                event: 'secrets.get',
                 bundle: name,
                 operation: opts.caller,
                 status: 'success',
                 source: 'session',
                 keyCount: Object.keys(filtered.env).length,
+                agent: harness,
             });
             return filtered;
         }
@@ -1190,6 +1202,9 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         ? getKeychainTokens([...new Set([metaItem, ...secretItems])], {
             agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
             bundle: name,
+            // The session that triggered the read, so a Touch ID prompt is
+            // attributable when several agents run at once. Exported by exec.ts.
+            sessionId: process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID,
             reason: opts.caller ? `to ${opts.caller}` : reason,
             duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
             defaultPolicy: secretsDefaultPolicy(),
@@ -1225,7 +1240,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -1261,8 +1276,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const keys = [...selectedKeys].sort();
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
-        emit('secrets.get', {
-            module: 'secrets',
+        emitSecretAudit({
+            event: 'secrets.get',
             bundle: bundle.name,
             operation: opts.caller,
             status,
@@ -1270,6 +1285,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             keys,
             keychainKeys,
             kindCounts,
+            agent: opts.agent,
             error: err instanceof Error ? err.message : (err ? String(err) : undefined),
         });
     };
@@ -1320,10 +1336,10 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         if (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
-            bundlePolicy(bundle) === 'daily' &&
+            bundlePolicy(bundle) === 'hold' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
-            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || 'cli');
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS);
         }
         return { bundle, env };
     }

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

@@ -213,9 +213,10 @@ export declare function hasKeychainToken(item: string): boolean;
 export interface KeychainReadContext {
     agent?: string;
     bundle?: string;
+    sessionId?: string;
     reason?: string;
     duration?: string;
-    defaultPolicy?: 'daily' | 'always' | 'never';
+    defaultPolicy?: 'hold' | 'always' | 'never';
     forceDuration?: boolean;
 }
 export declare function keychainOperationPrompt(context?: KeychainReadContext): string;

package/dist/lib/secrets/index.js

@@ -30,6 +30,7 @@ import * as path from 'path';
 import { linuxBackend, usesFileFallback as linuxUsesFileFallback, importNativeSecretToolItems } from './linux.js';
 import { windowsBackend, usesFileFallback as windowsUsesFileFallback, importNativeCredManItems } from './windows.js';
 import { getKeychainHelperPath } from './install-helper.js';
+import { deriveShortId } from '../session/short-id.js';
 const SERVICE_PREFIX = 'agents-cli';
 export const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
 const BUNDLES_ITEM_PREFIX = `${SERVICE_PREFIX}.bundles.`;
@@ -710,9 +711,12 @@ export function hasKeychainToken(item) {
 export function keychainOperationPrompt(context = {}) {
     const agent = context.agent || 'Agents CLI';
     const bundle = context.bundle ? ` the '${context.bundle}' bundle` : ' secrets';
+    // Which session triggered the read — the short-id disambiguates an unexpected
+    // prompt when several agents run at once (interactive + headless + exec).
+    const session = context.sessionId ? ` (session ${deriveShortId(context.sessionId)})` : '';
     const duration = context.duration ? ` for ${context.duration}` : '';
     const reason = context.reason ? ` ${context.reason}` : '';
-    return `${agent} is requesting to unlock${bundle}${duration}${reason}.`;
+    return `${agent} is requesting to unlock${bundle}${session}${duration}${reason}.`;
 }
 export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
@@ -820,7 +824,9 @@ export function getKeychainTokens(items, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
-            AGENTS_KEYCHAIN_DEFAULT_POLICY: context.defaultPolicy || 'daily',
+            // The signed helper's own vocabulary is unchanged (it predates the rename
+            // and ships as a separately-versioned binary), so map to its legacy token.
+            AGENTS_KEYCHAIN_DEFAULT_POLICY: (context.defaultPolicy ?? 'hold') === 'hold' ? 'daily' : context.defaultPolicy,
             AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
         },
         stdio: ['ignore', 'pipe', 'pipe'],

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

@@ -43,12 +43,17 @@ export declare function isDangerousRemoteEnvKey(name: string): boolean;
  */
 export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
- * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
- * list. Both flags compose; either alone works. Empty when neither is set.
+ * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
+ * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
+ * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * works on the secrets remote commands too. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {
     host?: string;
     hosts?: string;
+    device?: string;
+    devices?: string;
 }): string[];
 /**
  * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
@@ -104,3 +109,71 @@ export declare function remoteSecretsStream(target: string, args: string[], opts
 export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
     osLookupName?: string;
 }): Promise<Record<string, string>>;
+/**
+ * Outcome of a post-push read-back verification (see verifyRemoteKeychainPush).
+ *   - `ok`               — the pushed keys materialized readably on the remote.
+ *   - `locked-keychain`  — the read-back gave the SPECIFIC signal of a keychain
+ *                          that didn't persist (the remote's headless "not unlocked
+ *                          in the secrets agent" guard, or a "stored item … not
+ *                          found" on read-back, or pushed keys simply absent). Only
+ *                          this verdict earns the locked-login-keychain diagnosis +
+ *                          `--remote-backend file` steer.
+ *   - `error`            — a DIFFERENT failure (flaky SSH, timeout, unparseable
+ *                          payload). The raw error is re-surfaced verbatim, never
+ *                          mislabeled as a locked keychain.
+ */
+export type RemoteKeychainWriteVerification = {
+    ok: true;
+} | {
+    ok: false;
+    kind: 'locked-keychain';
+    reason: string;
+} | {
+    ok: false;
+    kind: 'error';
+    reason: string;
+};
+/**
+ * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
+ * value items, given the read-back of that bundle from the remote's own store.
+ *
+ * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
+ * a macOS host over headless SSH lands the bundle METADATA but not readable value
+ * items — the remote login keychain is locked in the non-interactive SSH context,
+ * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
+ * unreadable, and the remote `import` still reports success (values written first,
+ * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
+ * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
+ * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
+ * the bundle back the same way a release will (`secrets export --plaintext --format
+ * json`, driven headlessly on the remote so its `agentOnly` guard FAILS FAST before
+ * any keychain read — no Touch ID prompt) and confirming every pushed key returned.
+ *
+ * Pure so both branches are unit-testable without a real locked keychain: inject the
+ * "read-back failed / key absent" condition through `readBack`.
+ */
+export declare function evaluateKeychainWriteVerification(pushedKeys: string[], readBack: {
+    ok: true;
+    keys: string[];
+} | {
+    ok: false;
+    stderr: string;
+}): RemoteKeychainWriteVerification;
+/**
+ * The actionable error message for a failed keychain-over-SSH push verification.
+ * Names the cause (locked remote login keychain) and steers to the two real fixes:
+ * re-run with the headless-readable file backend, or unlock the remote keychain.
+ * Pure + exported so the exact guidance is asserted in tests.
+ */
+export declare function keychainWriteFailureMessage(host: string, bundle: string, reason: string): string;
+/**
+ * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
+ * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
+ * remote's own `secrets export <bundle> --plaintext --format json` — the same read
+ * a headless release performs — but keeps only the KEY NAMES; the plaintext values
+ * are dropped immediately and never retained or logged. Returns a verification
+ * verdict; the caller renders `keychainWriteFailureMessage` on failure.
+ */
+export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
+    osLookupName?: string;
+}): RemoteKeychainWriteVerification;

package/dist/lib/secrets/remote.js

@@ -17,7 +17,7 @@
  */
 import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
-import { emit } from '../events.js';
+import { emitSecretAudit } from './audit.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -74,8 +74,11 @@ export async function resolveHostSshTarget(nameOrAlias) {
     return nameOrAlias;
 }
 /**
- * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
- * list. Both flags compose; either alone works. Empty when neither is set.
+ * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
+ * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
+ * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * works on the secrets remote commands too. Empty when none is set.
  */
 export function parseHostsOption(opts) {
     const out = [];
@@ -89,9 +92,14 @@ export function parseHostsOption(opts) {
     };
     if (opts.host)
         push(opts.host);
+    if (opts.device)
+        push(opts.device);
     if (opts.hosts)
         for (const h of opts.hosts.split(','))
             push(h);
+    if (opts.devices)
+        for (const h of opts.devices.split(','))
+            push(h);
     return out;
 }
 /**
@@ -203,8 +211,8 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     // event on the INITIATING host too (values were pulled into this process and
     // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.
     // Values never enter the payload — only the bundle, target host, and count.
-    emit('secrets.get', {
-        module: 'secrets',
+    emitSecretAudit({
+        event: 'secrets.get',
         bundle,
         operation: 'remote resolve',
         source: 'remote',
@@ -214,3 +222,129 @@ export async function remoteResolveEnv(target, bundle, opts = {}) {
     });
     return env;
 }
+/**
+ * The remote's headless read-back raises one of these when a keychain-backed bundle
+ * has metadata but no readable value items — the exact locked-login-keychain
+ * signature. Anything else (connection refused, timeout, host key error) is a
+ * transient/unrelated failure and must NOT be mislabeled as a locked keychain.
+ */
+function isLockedKeychainReadBackError(stderr) {
+    const s = stderr.toLowerCase();
+    return (
+    // bundles.ts agentOnly guard: "…is not unlocked in the secrets agent…"
+    s.includes('not unlocked') ||
+        s.includes('secrets agent') ||
+        // resolveBundleEnv: "Bundle '<b>' key '<k>': stored item '<item>' not found."
+        s.includes('stored item') ||
+        s.includes('not found'));
+}
+/**
+ * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
+ * value items, given the read-back of that bundle from the remote's own store.
+ *
+ * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
+ * a macOS host over headless SSH lands the bundle METADATA but not readable value
+ * items — the remote login keychain is locked in the non-interactive SSH context,
+ * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
+ * unreadable, and the remote `import` still reports success (values written first,
+ * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
+ * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
+ * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
+ * the bundle back the same way a release will (`secrets export --plaintext --format
+ * json`, driven headlessly on the remote so its `agentOnly` guard FAILS FAST before
+ * any keychain read — no Touch ID prompt) and confirming every pushed key returned.
+ *
+ * Pure so both branches are unit-testable without a real locked keychain: inject the
+ * "read-back failed / key absent" condition through `readBack`.
+ */
+export function evaluateKeychainWriteVerification(pushedKeys, readBack) {
+    if (!readBack.ok) {
+        const stderr = readBack.stderr.trim();
+        if (isLockedKeychainReadBackError(stderr)) {
+            // The remote's own headless read raised the not-unlocked / not-found signal —
+            // exactly the confusing error the user hits later. Surface it now, at push
+            // time, with the fix.
+            return {
+                ok: false,
+                kind: 'locked-keychain',
+                reason: `the remote could not read it back${stderr ? ` (${stderr})` : ''}`,
+            };
+        }
+        // A transient / unrelated failure (flaky SSH, timeout, bad payload). Re-surface
+        // verbatim — do NOT diagnose a locked keychain from a connection error.
+        return {
+            ok: false,
+            kind: 'error',
+            reason: stderr || 'read-back failed',
+        };
+    }
+    const present = new Set(readBack.keys);
+    const missing = pushedKeys.filter((k) => !present.has(k));
+    if (missing.length > 0) {
+        // Read-back succeeded but some pushed keys are absent — the value items didn't
+        // persist. Same locked-keychain cause and fix.
+        return {
+            ok: false,
+            kind: 'locked-keychain',
+            reason: `${missing.length} of ${pushedKeys.length} key(s) did not persist on the remote ` +
+                `(missing: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''})`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * The actionable error message for a failed keychain-over-SSH push verification.
+ * Names the cause (locked remote login keychain) and steers to the two real fixes:
+ * re-run with the headless-readable file backend, or unlock the remote keychain.
+ * Pure + exported so the exact guidance is asserted in tests.
+ */
+export function keychainWriteFailureMessage(host, bundle, reason) {
+    return (`${host}: pushed '${bundle}' but the keychain items did not persist — ${reason}. ` +
+        `A macOS login keychain is LOCKED under headless SSH, so a keychain-backed write ` +
+        `lands the bundle metadata but no readable secret items, and later reads fail with ` +
+        `"stored item '…' not found". Re-run with a headless-readable backend:\n` +
+        `    agents secrets export ${bundle} --host ${host} --remote-backend file\n` +
+        `(needs AGENTS_SECRETS_PASSPHRASE set locally), or unlock the remote keychain first ` +
+        `(e.g. an interactive login / \`agents secrets unlock\` on ${host}) and retry.`);
+}
+/**
+ * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
+ * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
+ * remote's own `secrets export <bundle> --plaintext --format json` — the same read
+ * a headless release performs — but keeps only the KEY NAMES; the plaintext values
+ * are dropped immediately and never retained or logged. Returns a verification
+ * verdict; the caller renders `keychainWriteFailureMessage` on failure.
+ */
+export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName));
+    const res = sshExec(target, remoteCmd, { timeoutMs: REMOTE_TIMEOUT_MS });
+    if (res.code !== 0) {
+        const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+        const stderr = `${why}${(res.stderr || res.stdout || '').trim() ? `: ${(res.stderr || res.stdout).trim()}` : ''}`;
+        return evaluateKeychainWriteVerification(pushedKeys, { ok: false, stderr });
+    }
+    // Take the outer { … } object (tolerate login-shell banner noise), read the key
+    // names, and immediately discard the values — we only need presence here.
+    const raw = res.stdout;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    const jsonText = start >= 0 && end >= start ? raw.slice(start, end + 1) : raw.trim();
+    let keys;
+    try {
+        const parsed = JSON.parse(jsonText);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return evaluateKeychainWriteVerification(pushedKeys, {
+                ok: false,
+                stderr: 'unexpected read-back payload',
+            });
+        }
+        keys = Object.keys(parsed);
+    }
+    catch {
+        return evaluateKeychainWriteVerification(pushedKeys, {
+            ok: false,
+            stderr: 'could not parse read-back JSON',
+        });
+    }
+    return evaluateKeychainWriteVerification(pushedKeys, { ok: true, keys });
+}