@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/secrets/agent.js

@@ -40,6 +40,7 @@ import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
 import { selectLeasedEnv } from './lease.js';
 import { emitSecretAudit } from './audit.js';
+import { isDaemonServiceEnabled } from '../daemon-services.js';
 // Re-exported so callers already reaching for agent.js keep one obvious home for
 // the scope vocabulary; the definitions live in the leaf module scope.ts because
 // agent.ts and session-store.ts import each other and a cyclic `const` read can
@@ -50,6 +51,14 @@ export { GLOBAL_HARNESS, bundleScopeChain };
 const PROTOCOL_VERSION = 3;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
+/**
+ * Whether the secrets broker service is enabled in the daemon service config.
+ * Off-darwin this is irrelevant (the broker is never used), but the helper is
+ * kept synchronous and safe everywhere so callers can fail loud without a prompt.
+ */
+export function isSecretsBrokerEnabled() {
+    return isDaemonServiceEnabled('secrets-broker');
+}
 /**
  * Reserved store-key prefix for the `secrets list` metadata snapshot cache.
  * The broker holds the resolved bundle-metadata array (names/policy/timestamps,
@@ -361,7 +370,12 @@ export function realBundleCount(store) {
 export function scopedBundleKey(name, harness) {
     return `${harness}:${name}`;
 }
-export function handleAgentRequest(store, req, now = Date.now()) {
+export function handleAgentRequest(store, req, now = Date.now(), 
+// Eviction tombstones: `lock` records when each bundle was wiped so a load
+// whose snapshot predates the eviction (a detached auto-load that raced a
+// mutating write) is rejected instead of re-populating the store with a
+// pre-mutation copy. Broker-lifetime state, owned by the caller like `store`.
+evictedAt = new Map()) {
     switch (req.cmd) {
         case 'ping':
             // Report the version of the code this broker is RUNNING (getCliVersion
@@ -390,6 +404,13 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             return { ok: true, cmd: 'get', hit: false };
         }
         case 'load': {
+            const evictedTs = evictedAt.get(req.name);
+            if (evictedTs !== undefined && req.snapshotAt !== undefined && req.snapshotAt <= evictedTs) {
+                // The loader captured its bundle/env before a mutating write evicted
+                // this name; accepting it would serve (and later re-persist) stale
+                // state. A load with no snapshotAt (older client) is accepted as before.
+                return { ok: false, error: `stale load for '${req.name}': snapshot predates an eviction` };
+            }
             const harness = req.harness || GLOBAL_HARNESS;
             let env = req.env;
             if (req.lease) {
@@ -409,9 +430,12 @@ export function handleAgentRequest(store, req, now = Date.now()) {
                 for (const [key, entry] of store)
                     if (entry.bundle.name === req.name && store.delete(key))
                         wiped++;
+                evictedAt.set(req.name, now);
                 return { ok: true, cmd: 'lock', wiped };
             }
             const wiped = store.size;
+            for (const entry of store.values())
+                evictedAt.set(entry.bundle.name, now);
             store.clear();
             return { ok: true, cmd: 'lock', wiped };
         }
@@ -721,8 +745,9 @@ export async function runSecretsAgent(opts = {}) {
             emptySince = now;
         }
     };
+    const evictedAt = new Map();
     const handle = (req) => {
-        const resp = handleAgentRequest(store, req);
+        const resp = handleAgentRequest(store, req, Date.now(), evictedAt);
         if (realBundleCount(store) > 0)
             emptySince = Date.now();
         return resp;
@@ -854,7 +879,8 @@ export async function startHostedBroker() {
         return null;
     const store = rehydrateStore();
     const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
-    const handle = (req) => handleAgentRequest(store, req);
+    const evictedAt = new Map();
+    const handle = (req) => handleAgentRequest(store, req, Date.now(), evictedAt);
     const onConn = makeConnectionHandler(handle, readAgentToken);
     const server = await bindBrokerSocket(sock, onConn);
     if (!server)
@@ -1039,6 +1065,8 @@ function syncClient(sub, timeout) {
  * (soft — caller falls through to the real keychain). macOS only.
  */
 export function agentGetSync(name, harness = GLOBAL_HARNESS) {
+    if (!isSecretsBrokerEnabled())
+        return null;
     if (!agentSocketExists())
         return null;
     const r = syncClient([SYNC_GET_CMD, name, harness], SYNC_GET_TIMEOUT_MS);
@@ -1270,10 +1298,15 @@ export function clampHoldMs(v) {
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease, 
+// When the caller read the bundle from the keychain — lets the broker
+// reject this load if an eviction lands in between (tombstones, above).
+snapshotAt) {
     if (!onDarwin())
         return;
-    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness, lease });
+    if (!isSecretsBrokerEnabled())
+        return;
+    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness, lease, snapshotAt });
     // Broker actually LISTENING → deterministic synchronous warm (bounded; the read
     // already paid a Touch ID, so <1s here is invisible). We gate on a real liveness
     // ping, NOT mere socket-file existence: a broker that died leaving its socket
@@ -1340,13 +1373,13 @@ export async function runAgentLoadFromStdin() {
         process.exitCode = 1; // broker couldn't be brought up — did NOT load
         return;
     }
-    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? GLOBAL_HARNESS, payload.lease);
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? GLOBAL_HARNESS, payload.lease, payload.snapshotAt);
     if (!loaded)
         process.exitCode = 1; // transport failed — did NOT load
 }
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export async function agentLoad(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
-    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness, lease });
+export async function agentLoad(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease, snapshotAt) {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness, lease, snapshotAt });
     return r?.ok === true && r.cmd === 'load';
 }
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
@@ -1390,6 +1423,8 @@ export async function agentPing() {
 export async function ensureAgentRunning(timeoutMs = 5000) {
     if (!onDarwin())
         return false;
+    if (!isSecretsBrokerEnabled())
+        return false;
     // Self-heal: if a broker is reachable but running pre-upgrade code (its
     // reported version != the version on disk now), tear it down so the paths
     // below bring up a fresh one on current code. A current, reachable broker is

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

@@ -211,6 +211,7 @@ export interface BundleEntryInfo {
     detail: string;
 }
 export declare function describeBundle(bundle: SecretsBundle): BundleEntryInfo[];
+export declare function stampLastUsed(bundle: SecretsBundle): void;
 /** Options for resolveBundleEnv. */
 export interface ResolveBundleOptions {
     /**

package/dist/lib/secrets/bundles.js

@@ -31,7 +31,7 @@ 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 { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs, isSecretsBrokerEnabled } from './agent.js';
 import { GLOBAL_HARNESS } from './scope.js';
 import { resolveSession, deleteSession } from './session-store.js';
 import { createHash } from 'node:crypto';
@@ -907,11 +907,20 @@ export function describeBundle(bundle) {
     }
     return out;
 }
-// Bump `bundle.last_used` and persist the bundle, but no more than once per
-// throttle window so we don't pay a keychain write on every agent run. Failures
-// are swallowed — usage tracking is never allowed to break secret resolution.
+// Bump `last_used` and persist it, but no more than once per throttle window
+// so we don't pay a keychain write on every agent run. Failures are swallowed —
+// usage tracking is never allowed to break secret resolution.
 // Set AGENTS_NO_USAGE_TRACK=1 to disable the stamp entirely (used by tests).
-function stampLastUsed(bundle) {
+//
+// The passed bundle is often the BROKER'S snapshot (this fires on every broker
+// hit), which can be stale — a detached auto-load captured before a mutating
+// write can land after its eviction. Persisting that snapshot wholesale used to
+// write its whole `vars` map back over the authoritative store, resurrecting
+// removed keys (or, for a since-deleted bundle, the bundle itself). The stamp
+// is telemetry: it re-reads the store's own current copy (bundle metadata is a
+// silent no-ACL read) and writes ONLY the timestamp onto that.
+// Exported for regression coverage, like shouldEvictAfterBundleWrite.
+export function stampLastUsed(bundle) {
     if (process.env.AGENTS_NO_USAGE_TRACK)
         return;
     const nowMs = Date.now();
@@ -921,10 +930,14 @@ function stampLastUsed(bundle) {
             return;
     }
     try {
-        bundle.last_used = new Date(nowMs).toISOString();
+        const fresh = readBundle(bundle.name); // throws if the bundle is gone — swallowed below
+        const stamp = new Date(nowMs).toISOString();
+        fresh.last_used = stamp;
+        // Keep the caller's (possibly broker-held) copy throttling correctly.
+        bundle.last_used = stamp;
         // skipBrokerEviction: this stamp fires on every broker HIT; letting it
         // evict would make the cache destroy itself on first use.
-        writeBundle(bundle, { skipBrokerEviction: true });
+        writeBundle(fresh, { skipBrokerEviction: true });
     }
     catch {
         // Swallow — telemetry must never block secret resolution.
@@ -1272,6 +1285,10 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             // `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.
+            // No snapshotAt: the session's bundle was read at unlock time, not now —
+            // claiming freshness here would defeat the broker's eviction tombstones.
+            // An undated load is accepted (legacy behavior); the durable-session
+            // staleness window itself is a known, separate concern.
             agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness, session.lease);
             emitSecretAudit({
                 event: 'secrets.get',
@@ -1303,40 +1320,49 @@ export function readAndResolveBundleEnv(name, opts = {}) {
                 `never raises a Touch ID sheet on its own.`);
         }
     }
+    // If the secrets broker is explicitly disabled and this bundle would otherwise
+    // fall through to a keychain read (Touch ID prompt), fail loud now. Never-policy
+    // bundles are verified below and remain silent; vault/file backends are unaffected.
+    if (backend === 'keychain' && !isSecretsBrokerEnabled() && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
+        throw new Error(`Secrets broker is disabled — re-enable with 'agents daemon services enable secrets-broker'. ` +
+            `If you meant to read directly from the keychain, set AGENTS_SECRETS_NO_AGENT=1.`);
+    }
     if (backend === 'vault')
         assertVaultBackendUsable(name);
     const store = itemStore(backend);
     const metaItem = bundleMetaItem(name);
     const bundleSecretPrefix = `${SECRETS_ITEM_PREFIX}${name}.`;
-    let secretItems;
-    try {
-        secretItems = store.list(bundleSecretPrefix);
-    }
-    catch {
-        secretItems = [];
+    let enumeratedSecretItems = [];
+    // Agent launches must never enumerate the macOS Keychain: a per-bundle
+    // prefix becomes a broad `agents-cli.` scan after service-name hashing and
+    // macOS evaluates unrelated biometry ACLs during that scan (RUSH-2440).
+    // Interactive reads retain the existing enumeration side of the union so
+    // legacy/aliased items keep their established behavior.
+    if (backend !== 'keychain' || !opts.agentOnly) {
+        try {
+            enumeratedSecretItems = store.list(bundleSecretPrefix);
+        }
+        catch {
+            enumeratedSecretItems = [];
+        }
     }
     const reason = opts.caller
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
-    // 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 = backend === 'keychain'
-        ? 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(),
-            forceDuration: Boolean(opts.duration),
-            silentNoAcl: verifiedNoAclBundle,
-        })
-        : store.getBatch([...new Set([metaItem, ...secretItems])]);
-    const json = fetched.get(metaItem);
+    // Captured BEFORE the first keychain read: if a mutating write evicts this
+    // bundle while the read is in flight, the broker's tombstone must beat this
+    // snapshot, so the conservative (earliest) timestamp is the correct one.
+    const snapshotAt = Date.now();
+    // Fetch metadata first (it's always no-ACL), then derive secret item names
+    // from its declared keys instead of enumerating. This eliminates the broad
+    // Keychain scan that triggered Touch ID on every run (RUSH-2440). The
+    // metadata is authoritative for declared keys; undeclared keys (union with
+    // legacy/orphaned items) are not supported in agent-only mode and would
+    // fail the agentOnly gate anyway.
+    const metaFetched = backend === 'keychain'
+        ? getKeychainTokens([metaItem], { silentNoAcl: true })
+        : store.getBatch([...new Set([metaItem, ...enumeratedSecretItems])]);
+    const json = metaFetched.get(metaItem);
     if (json === undefined) {
         if (vaultExists() && !getVaultSession().loggedIn) {
             throw new Error(`Synced secrets are locked. Run: agents login`);
@@ -1353,6 +1379,39 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     if (!parsed || typeof parsed !== 'object') {
         throw new Error(`Bundle '${name}' is malformed.`);
     }
+    // Compute exact storage names from declared keychain references. The env key
+    // and stored item name may differ (`TOKEN=keychain:actual-token`), so deriving
+    // item names from Object.keys(vars) would silently read the wrong secret.
+    const declaredSecretItems = [];
+    if (parsed.vars && typeof parsed.vars === 'object') {
+        for (const raw of Object.values(parsed.vars)) {
+            const value = parseBundleValue(raw);
+            if ('ref' in value && value.ref.provider === 'keychain') {
+                declaredSecretItems.push(secretsKeychainItem(name, value.ref.value));
+            }
+        }
+    }
+    const secretItems = [...new Set([...enumeratedSecretItems, ...declaredSecretItems])];
+    // Now fetch both metadata and secret values in one batch.
+    // The interactive path keeps the enumeration + declared-item union; the
+    // agent-only path contains declared items only and therefore never scans.
+    const fetched = backend === 'keychain'
+        ? 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(),
+            forceDuration: Boolean(opts.duration),
+            silentNoAcl: verifiedNoAclBundle,
+        })
+        // File/vault enumeration is complete and prompt-free. Reuse its initial
+        // batch so metadata-first Keychain safety does not double-decrypt every
+        // file-backed credential read.
+        : metaFetched;
     const bundle = {
         name,
         description: parsed.description,
@@ -1393,53 +1452,6 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     }
     const keys = [...selectedKeys].sort();
     keychainKeys.sort();
-    // RUSH-2252: complete the read set from the bundle's DECLARED keys, not only
-    // from the enumeration above. `store.list()` derives the batch by enumerating
-    // the bundle's namespace, and that enumeration is lossy by construction — the
-    // macOS helper's `list` omits every biometry-ACL'd item
-    // (`kSecUseAuthenticationUISkip`) and skips the whole data-protection pass when
-    // the keychain is locked, so a `hold`-policy bundle's value items never appear
-    // and a present secret reads as "not found" (RUSH-2248). A declared key whose
-    // item did not enumerate is therefore absent from `fetched`; read those exact
-    // items directly — a point read DOES evaluate the ACL, so it triggers Touch ID
-    // and returns the value the enumeration could not see. The enumeration still
-    // earns its place (it catches hashed/aliased storage names and stale leftovers
-    // not named in the metadata), so this is a UNION, not a replacement.
-    //
-    // One Touch ID sheet is preserved: the items missing from `fetched` are exactly
-    // the ACL'd ones the enumeration dropped, so the first batch (metadata plus any
-    // no-ACL / `never` items) raised no sheet, and this second batch raises the
-    // single sheet that covers all of them. When the enumeration is healthy every
-    // declared item is already in `fetched`, `missingDeclared` is empty, and this
-    // is skipped entirely — zero behavior change and no extra spawn on the hot path.
-    if (backend === 'keychain') {
-        const missingDeclared = [];
-        for (const key of keychainKeys) {
-            const p = parsedByKey.get(key);
-            if (!('ref' in p) || p.ref.provider !== 'keychain')
-                continue;
-            const item = secretsKeychainItem(bundle.name, p.ref.value);
-            if (fetched.get(item) === undefined && fetched.get(keychainServiceAlias(item)) === undefined) {
-                missingDeclared.push(item);
-            }
-        }
-        if (missingDeclared.length > 0) {
-            const declaredFetched = getKeychainTokens([...new Set(missingDeclared)], {
-                agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
-                bundle: name,
-                sessionId: process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID,
-                reason: opts.caller ? `to ${opts.caller}` : reason,
-                duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
-                // The policy is known now (metadata parsed), so the prompt names the real
-                // duration instead of the pre-read default the first batch had to guess.
-                defaultPolicy: bundlePolicy(bundle),
-                forceDuration: Boolean(opts.duration),
-                silentNoAcl: verifiedNoAclBundle,
-            });
-            for (const [k, v] of declaredFetched)
-                fetched.set(k, v);
-        }
-    }
     const emitReadAudit = (status, err) => {
         emitSecretAudit({
             event: 'secrets.get',
@@ -1474,7 +1486,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             bundlePolicy(bundle) === 'hold' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
-            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS);
+            agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS, undefined, snapshotAt);
         }
         return { bundle, env };
     }

package/dist/lib/secrets/index.js

@@ -298,7 +298,34 @@ export function readHmacKeyRecord() {
     catch {
         return null;
     }
-    return parseHmacKeyRecord(raw);
+    const record = parseHmacKeyRecord(raw);
+    // Converge a stale-ACL'd hmackey to silent, on the HOT read path (RUSH-2441 /
+    // restore of v1.22.7 / 391017461). An old helper re-stamped this
+    // contractually-no-ACL item with a biometry ACL, so the read just above pops
+    // the generic "Agents CLI needs to authenticate" sheet on EVERY hashed
+    // lookup — the `agents devices list` stats probe the SessionStart hook runs,
+    // and every other background hashed read. `maybeAutoRekey`'s one-shot heal
+    // only fires on a cleartext-bundle resolve and is bypassed for the
+    // hmackey/hashed-name path (`prepareServiceName` returns early for
+    // HMAC_KEY_ITEM before maybeAutoRekey), so it never converged exactly these
+    // reads and the machine prompted forever. Re-store the record no-ACL once
+    // per machine here (the read that produced it has already happened — and
+    // already prompted if the item was ACL'd); every subsequent read, in this
+    // process and all future ones, is silent.
+    //
+    // v1.22.10 (bf79dc885 / #1995) moved the heal back into maybeAutoRekey and
+    // left the changelog claim in 1.22.7 false until this restore.
+    if (record && !record.healedNoAcl) {
+        try {
+            healHmacKeyNoAclOnce(record);
+            record.healedNoAcl = true;
+        }
+        catch {
+            // A failed no-ACL re-store leaves the item still ACL'd (a still-prompting
+            // read) rather than a silent wrong state; the next process retries.
+        }
+    }
+    return record;
 }
 function writeHmacKeyRecord(rec) {
     // JSON.stringify drops undefined fields (used to clear pendingDeletes).
@@ -471,14 +498,10 @@ export function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
-        if (st.record && !st.record.healedNoAcl) {
-            try {
-                healHmacKeyNoAclOnce(st.record);
-            }
-            catch {
-                /* the next explicit unlock retries */
-            }
-        }
+        // The stale-ACL'd-hmackey heal runs on the hot read path
+        // (readHmacKeyRecord), which resolveHashState() above just went through —
+        // so st.record is already healed here regardless of how this machine
+        // reached "hashing active". Nothing to do but finish any pending deletes.
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);

package/dist/lib/secrets/install-helper.d.ts

@@ -33,14 +33,14 @@ export declare function ensureKeychainHelperInstalled(opts?: {
  * Return the absolute path to the helper executable. If the installed bundle
  * is missing, or is stale relative to the bundled source helper, performs a
  * lazy (re)install first. The staleness check is what lets an upgraded CLI
- * replace a helper a previous version installed — `agents helper install`
- * never runs on `npm i -g`, so this call site is the only one every machine
- * is guaranteed to pass through.
+ * replace a helper a previous version installed — the install never runs on
+ * `npm i -g`, so this call site is the only one every machine is guaranteed to
+ * pass through.
  *
  * Throws on non-darwin.
  */
 export declare function getKeychainHelperPath(): string;
-/** Diagnostic snapshot used by `agents helper status`. */
+/** Diagnostic snapshot of the installed Keychain helper. */
 export interface KeychainHelperStatus {
     source: string | null;
     destination: string;

package/dist/lib/secrets/install-helper.js

@@ -140,7 +140,7 @@ export function ensureKeychainHelperInstalled(opts = {}) {
         const verify = codesignVerify(dest);
         if (!verify.ok) {
             throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
-                'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
+                'The bundle may be corrupted. Reinstall agents-cli to restore it; the helper reinstalls automatically on the next secrets use.');
         }
         heartbeat(); // codesign done; spctl does a network Gatekeeper lookup — refresh again
         const assess = spctlAssess(dest);
@@ -156,9 +156,9 @@ export function ensureKeychainHelperInstalled(opts = {}) {
  * Return the absolute path to the helper executable. If the installed bundle
  * is missing, or is stale relative to the bundled source helper, performs a
  * lazy (re)install first. The staleness check is what lets an upgraded CLI
- * replace a helper a previous version installed — `agents helper install`
- * never runs on `npm i -g`, so this call site is the only one every machine
- * is guaranteed to pass through.
+ * replace a helper a previous version installed — the install never runs on
+ * `npm i -g`, so this call site is the only one every machine is guaranteed to
+ * pass through.
  *
  * Throws on non-darwin.
  */

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

@@ -33,6 +33,12 @@ export interface PushBundleOptions {
     passphrase?: string;
     /** Label for the audit trail — `export --host` vs `fleet apply`. */
     operation: string;
+    /** Preserve an automation account's permanent prompt-free policy remotely. */
+    policyNever?: boolean;
+    /** Permit a human-invoked push to read locally without requiring the agent broker. */
+    agentOnly?: boolean;
+    /** Non-secret literals whose bundle value kind must survive the dotenv transport. */
+    literalValues?: Record<string, string>;
 }
 export interface PushBundleResult {
     ok: boolean;
@@ -42,14 +48,34 @@ export interface PushBundleResult {
     /** One line for the caller to render. Never contains a secret value. */
     message: string;
 }
+export interface LiteralRestorePlan {
+    key: string;
+    removeArgs: string[];
+    addArgs: string[];
+}
+/** Preserve the literal-vs-secret schema that dotenv transport cannot encode. */
+export declare function planLiteralRestoration(bundle: string, literalValues?: Record<string, string>): LiteralRestorePlan[];
 /**
  * Read and resolve a bundle once, for pushing to one or more hosts.
  *
- * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
- * passed: storage-shaped values, and the headless guard that fails fast rather
- * than popping Touch ID inside an automated run.
+ * `keyMode: 'storage'` is fixed — a push always sends storage-shaped values.
+ *
+ * `agentOnly` is the caller's to decide, and it is NOT a security level: it
+ * selects the broker-only read (fail fast with the `agents secrets unlock` hint)
+ * over the interactive read (macOS may raise a Touch ID sheet). The headless
+ * guard exists because an AGENT LAUNCH must never enumerate the keychain — a
+ * per-bundle prefix becomes a broad `agents-cli.` scan after service-name
+ * hashing, and macOS evaluates unrelated biometry ACLs during it, one sheet per
+ * installed version (bundles.ts, RUSH-2440). A human at a TTY is not that case:
+ * they can answer one prompt, and the interactive sibling reads (`view --reveal`,
+ * `exec`) already let them. NOT `get` — it is unconditionally `agentOnly` on
+ * purpose, because prompting would hang a `$(agents secrets get …)` capture
+ * mid-pipeline (SEC-13b). It defaults to `true` so an automated caller that says
+ * nothing stays broker-only.
  */
-export declare function resolveBundleForPush(bundle: string, caller: string): ResolvedBundleForPush;
+export declare function resolveBundleForPush(bundle: string, caller: string, opts?: {
+    agentOnly?: boolean;
+}): ResolvedBundleForPush;
 /**
  * WHICH transport a (backend, target-OS) pair selects, and the exact bytes it
  * will send. One of four outcomes, and picking the wrong one is silent: a
@@ -68,17 +94,25 @@ export type PushTransport =
     kind: 'refuse';
     message: string;
 }
-/** A command sent over the raw ssh engine, with the .env on stdin. */
+/**
+ * A command sent over the raw ssh engine, with the .env on stdin. `multiplex`
+ * is always `false`: a push ships credential bytes, so its connection must not
+ * reuse — or leave behind — a persistent authenticated control master to the
+ * destination the way the default fan-out connections do (RUSH-2527). This
+ * mirrors the `--copy-creds` dispatch posture (`multiplex: !opts.copyCreds`).
+ */
  | {
     kind: 'ssh';
     remoteCmd: string;
     input: string;
+    multiplex: false;
 }
-/** The OS-aware `agents secrets` wrapper, the READ inverse's own path. */
+/** The OS-aware `agents secrets` wrapper, the READ inverse's own path. Never multiplexed — see the `ssh` kind. */
  | {
     kind: 'remote-secrets';
     args: string[];
     input: string;
+    multiplex: false;
 };
 /** Choose the transport for one push. Pure: registry read in, plan out. */
 export declare function planPushTransport(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushTransport;