@phnx-labs/agents-cli 1.20.51 → 1.20.52

package/dist/lib/feed.js

@@ -0,0 +1,251 @@
+/**
+ * Feed store -- structured block records published by agents waiting on user
+ * input (AskUserQuestion). The outbound counterpart to the inbound mailbox:
+ * the mailbox delivers messages TO agents; the feed surfaces decisions agents
+ * need FROM the user.
+ *
+ * Layout: <feedDir>/<blockId>.json
+ *   Each file is one open block -- a question the agent asked. One block per
+ *   session: a new AskUserQuestion in the same session replaces the previous
+ *   block (an agent can only ask one question at a time). Removed when the
+ *   session advances past the block.
+ *
+ * A block carries enough identity (sessionId, mailboxId, host, runtime) for
+ * `agents feed` to aggregate across hosts and for `agents message` to route
+ * a reply back to the right agent.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getFeedDir, getUserAgentsDir } from './state.js';
+/**
+ * Stable block id for a session. One block per session -- a new question
+ * replaces the previous one (the agent can only ask one question at a time).
+ */
+export function blockIdForSession(sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '-');
+    return `block-${safeSessionId}`;
+}
+function blockPath(root, blockId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(blockId)) {
+        throw new Error(`Invalid feed block id: ${blockId}`);
+    }
+    return path.join(root, `${blockId}.json`);
+}
+/** Atomic write a block record to the feed store. */
+export function publishBlock(block, root) {
+    const dir = root ?? getFeedDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const target = blockPath(dir, block.blockId);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(block, null, 2), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+/** Read all block records. Returns them sorted by stable block filename. */
+export function listBlocks(root) {
+    const dir = root ?? getFeedDir();
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const blocks = [];
+    for (const name of names.filter(n => n.endsWith('.json')).sort()) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.blockId && parsed.sessionId && parsed.questions?.length) {
+                blocks.push(parsed);
+            }
+        }
+        catch {
+            // skip corrupt / partial files
+        }
+    }
+    return blocks;
+}
+/** Remove a block record. Returns true if the file was deleted. */
+export function removeBlock(blockId, root) {
+    const dir = root ?? getFeedDir();
+    try {
+        fs.unlinkSync(blockPath(dir, blockId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook installation
+// ---------------------------------------------------------------------------
+/**
+ * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
+ * Embedded so it ships with the compiled CLI and can be installed to the
+ * CLI-writable user hooks dir without a separate file in the npm tarball.
+ */
+export const FEED_PUBLISH_HOOK_SCRIPT = `#!/usr/bin/env python3
+"""PreToolUse hook: publish an open-block record when the agent calls
+AskUserQuestion, so \`agents feed\` can aggregate pending decisions.
+
+Outbound counterpart to the inbound mailbox-inject hook. Fires only on
+AskUserQuestion (matcher-gated in agents.yaml). Writes one block per session
+to ~/.agents/.history/feed/. A new question replaces the previous block.
+
+Sub-agent gate: when the PreToolUse payload carries \`agent_type\`, this is a
+Task/Agent subagent -- skip. Only the top-level agent publishes. Verified on
+Claude Code 2.1.170 (2026-07).
+
+Fail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.
+"""
+import os
+import sys
+import json
+import re
+import socket
+import tempfile
+from datetime import datetime, timezone
+
+
+def main():
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return
+
+    # Sub-agent gate.
+    if payload.get("agent_type"):
+        return
+
+    tool_input = payload.get("tool_input", {})
+    questions = tool_input.get("questions", [])
+    if not questions:
+        return
+
+    session_id = payload.get("session_id", "")
+    if not session_id:
+        return
+
+    normalized_questions = []
+    for q in questions:
+        if not isinstance(q, dict):
+            continue
+        question = {
+            "text": q.get("question", q.get("header", "")),
+            "header": q.get("header"),
+            "multiSelect": q.get("multiSelect", False),
+        }
+        raw_opts = q.get("options", [])
+        if raw_opts:
+            question["options"] = [
+                {"label": o.get("label", ""), "description": o.get("description")}
+                for o in raw_opts
+                if isinstance(o, dict)
+            ]
+        normalized_questions.append(question)
+    if not normalized_questions:
+        return
+
+    # Identity from env (set by agents-cli at spawn).
+    mailbox_id = os.path.basename(
+        os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
+    ) or session_id
+
+    hostname = os.environ.get("AGENTS_SYNC_MACHINE_ID") or socket.gethostname()
+    host = hostname.split(".")[0].strip().lower()
+    host = re.sub(r"[^a-z0-9_-]", "-", host) or "unknown"
+
+    runtime = os.environ.get("AGENTS_RUNTIME", "headless")
+
+    safe_session_id = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
+    block_id = f"block-{safe_session_id}"
+    block = {
+        "blockId": block_id,
+        "sessionId": session_id,
+        "mailboxId": mailbox_id,
+        "host": host,
+        "runtime": runtime,
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "questions": normalized_questions,
+    }
+
+    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a
+    # HOME override on every platform. Use the same anchor so hooks and the CLI
+    # always read/write one feed store (including temp-home and sandbox runs).
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    feed_dir = os.path.join(home, ".agents", ".history", "feed")
+    os.makedirs(feed_dir, exist_ok=True)
+
+    target = os.path.join(feed_dir, f"{block_id}.json")
+    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(block, f, indent=2)
+        os.rename(tmp, target)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass  # fail open
+`;
+/** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
+export const FEED_PUBLISH_HOOK_MANIFEST = {
+    name: 'feed-publish',
+    events: ['PreToolUse'],
+    matcher: 'AskUserQuestion',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+/**
+ * Install the feed-publish hook script into the user hooks dir and add its
+ * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
+ * read-only mirror, so runtime-managed hooks must never write there.
+ * Idempotent -- skips if the script is already present and up to date.
+ */
+export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
+    try {
+        const hooksDir = path.join(userAgentsDir, 'hooks');
+        const scriptPath = path.join(hooksDir, '10-feed-publish.py');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        let installed = false;
+        if (!fs.existsSync(scriptPath) || fs.readFileSync(scriptPath, 'utf-8') !== FEED_PUBLISH_HOOK_SCRIPT) {
+            const tmpScript = `${scriptPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpScript, FEED_PUBLISH_HOOK_SCRIPT, { mode: 0o755 });
+            fs.renameSync(tmpScript, scriptPath);
+            installed = true;
+        }
+        const agentsYamlPath = path.join(userAgentsDir, 'agents.yaml');
+        const yamlDoc = fs.existsSync(agentsYamlPath)
+            ? yaml.parseDocument(fs.readFileSync(agentsYamlPath, 'utf-8'))
+            : new yaml.Document({});
+        if (yamlDoc.errors.length > 0) {
+            throw new Error(`Cannot install feed hook: ${agentsYamlPath} is invalid YAML`);
+        }
+        if (!yamlDoc.getIn(['hooks', 'feed-publish'])) {
+            yamlDoc.setIn(['hooks', 'feed-publish'], {
+                agents: ['claude'],
+                events: ['PreToolUse'],
+                matcher: 'AskUserQuestion',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            });
+            const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpYaml, String(yamlDoc));
+            fs.renameSync(tmpYaml, agentsYamlPath);
+            installed = true;
+        }
+        return { installed };
+    }
+    catch (err) {
+        return { installed: false, error: err.message };
+    }
+}

package/dist/lib/hooks.js

@@ -1028,9 +1028,11 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     const configDir = path.join(versionHome, configDirName);
     const settingsPath = path.join(configDir, 'settings.json');
     let config = {};
+    let existingRaw;
     if (fs.existsSync(settingsPath)) {
         try {
-            config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            existingRaw = fs.readFileSync(settingsPath, 'utf-8');
+            config = JSON.parse(existingRaw);
         }
         catch {
             errors.push('Failed to parse settings.json');
@@ -1111,7 +1113,10 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     try {
         fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+        const nextRaw = JSON.stringify(config, null, 2);
+        if (existingRaw !== nextRaw) {
+            fs.writeFileSync(settingsPath, nextRaw, 'utf-8');
+        }
     }
     catch (err) {
         errors.push(`Failed to write settings.json: ${err.message}`);

package/dist/lib/hosts/passthrough.js

@@ -34,6 +34,7 @@ const REMOTE_PASSTHROUGH = {
     sync: { nonInteractive: ['--yes'] },
     teams: {},
     message: {},
+    feed: {},
 };
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];

package/dist/lib/rotate.js

@@ -10,6 +10,7 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
+import { emit } from './events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
@@ -388,6 +389,7 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
             }
             recordRotationPick(agent, rotation.picked.version);
         }
+        emit('rotation.resolved', { module: 'rotate', agent, version: rotation.picked.version, strategy, healthy: rotation.healthy.length, excluded: rotation.excluded.length });
         return { version: rotation.picked.version, rotation };
     }
     return { version: fallback, rotation: null };

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

@@ -50,6 +50,18 @@ export declare const META_CACHE_PREFIX = "!meta:";
  * cache on every bump and produced a recurring Touch ID storm.
  */
 export declare function shouldSelfHealForUpgrade(persistent: boolean, storeSize: number, runningVersion: string, onDiskVersion: string): boolean;
+/**
+ * Client-side twin of shouldSelfHealForUpgrade: whether ensureAgentRunning may
+ * tear down a reachable broker whose running version differs from the client's
+ * on-disk version. Only while it holds NO real unlocks — tearing down a hot
+ * broker wipes every held bundle, so the next read of each one re-prompts for
+ * Touch ID. On a machine where installed versions churn (dev builds stamp a
+ * fresh 0.0.0-dev.<sha> on every install; an npm copy and a dev copy invoke in
+ * turn), an unguarded teardown produced a rolling Touch ID storm — the exact
+ * failure #435 fixed on the server side. A hot, protocol-compatible broker
+ * keeps serving; its own sweep adopts the new code at the next quiet moment.
+ */
+export declare function shouldTeardownVersionSkewedBroker(realHeldBundles: number): boolean;
 export interface StoredBundle {
     bundle: SecretsBundle;
     env: Record<string, string>;
@@ -172,6 +184,15 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Synchronously evict one bundle from the broker. Called after a mutating
+ * keychain write (add / rotate / remove / rename / delete) so the broker never
+ * keeps serving the pre-write snapshot for up to the ~7d hold — the next read
+ * re-resolves from the keychain (one prompt) and re-caches fresh values.
+ * Best-effort: no broker, no socket, or any failure is a silent no-op.
+ * macOS only.
+ */
+export declare function agentEvictSync(name: string): void;
 /**
  * Read the cached `secrets list` metadata snapshot for the given keychain
  * name-set hash, or null on miss / no broker / off-darwin. Reuses the value

package/dist/lib/secrets/agent.js

@@ -74,6 +74,20 @@ export function shouldSelfHealForUpgrade(persistent, storeSize, runningVersion,
         return false;
     return onDiskVersion !== runningVersion;
 }
+/**
+ * Client-side twin of shouldSelfHealForUpgrade: whether ensureAgentRunning may
+ * tear down a reachable broker whose running version differs from the client's
+ * on-disk version. Only while it holds NO real unlocks — tearing down a hot
+ * broker wipes every held bundle, so the next read of each one re-prompts for
+ * Touch ID. On a machine where installed versions churn (dev builds stamp a
+ * fresh 0.0.0-dev.<sha> on every install; an npm copy and a dev copy invoke in
+ * turn), an unguarded teardown produced a rolling Touch ID storm — the exact
+ * failure #435 fixed on the server side. A hot, protocol-compatible broker
+ * keeps serving; its own sweep adopts the new code at the next quiet moment.
+ */
+export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
+    return realHeldBundles === 0;
+}
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -581,6 +595,50 @@ export function agentGetSync(name) {
         return null;
     }
 }
+/**
+ * Inline node program for the synchronous evict path. Mirrors SYNC_GET_PROGRAM:
+ * writeBundle is synchronous and called synchronously everywhere, so a stale
+ * broker entry must be evicted without awaiting a socket round-trip. Sends one
+ * {cmd:'lock', name} and exits 0 (evicted or nothing held) / 3 (agent down).
+ * argv after -e: [execPath, <socket>, <name>].
+ */
+const SYNC_LOCK_PROGRAM = `
+const net = require('net');
+const sock = process.argv[1], name = process.argv[2];
+const c = net.createConnection(sock);
+let buf = '';
+const down = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
+const timer = setTimeout(down, 2000);
+c.on('error', down);
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'lock', name }) + '\\n'));
+c.setEncoding('utf-8');
+c.on('data', (d) => {
+  buf += d;
+  const nl = buf.indexOf('\\n');
+  if (nl < 0) return;
+  clearTimeout(timer);
+  try { c.destroy(); } catch (e) {}
+  process.exit(0);
+});
+`;
+/**
+ * Synchronously evict one bundle from the broker. Called after a mutating
+ * keychain write (add / rotate / remove / rename / delete) so the broker never
+ * keeps serving the pre-write snapshot for up to the ~7d hold — the next read
+ * re-resolves from the keychain (one prompt) and re-caches fresh values.
+ * Best-effort: no broker, no socket, or any failure is a silent no-op.
+ * macOS only.
+ */
+export function agentEvictSync(name) {
+    if (!onDarwin())
+        return;
+    if (!agentSocketExists())
+        return;
+    try {
+        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name], { timeout: 3000 });
+    }
+    catch { /* best-effort */ }
+}
 // Key inside the cached entry's env that holds the JSON metadata snapshot.
 const META_SNAPSHOT_KEY = '__snapshot__';
 /**
@@ -733,11 +791,15 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     // 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
-    // accepted immediately.
+    // accepted immediately — and so is a version-skewed one that still holds
+    // real unlocks (see shouldTeardownVersionSkewedBroker: wiping a hot cache
+    // re-prompts Touch ID for every held bundle).
     const ping = await agentPing();
     if (ping.reachable) {
         if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
             return true;
+        if (!shouldTeardownVersionSkewedBroker((await agentStatus()).length))
+            return true;
         await teardownStaleBroker();
     }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and

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

@@ -89,6 +89,9 @@ export interface LegacyBundleCandidate {
     file: string;
     keys: string[];
 }
+export declare const BUNDLE_NAME_PATTERN: RegExp;
+export declare const ENV_KEY_PATTERN: RegExp;
+export declare const BUNDLE_META_PREFIX = "agents-cli.bundles.";
 export declare const RESERVED_ENV_NAMES: Set<string>;
 export declare function bundleToEnvPrefix(name: string): string;
 export declare function isReservedEnvName(key: string): boolean;
@@ -114,7 +117,29 @@ export declare function readBundle(name: string): SecretsBundle;
 export declare function secretsDefaultPolicy(): SecretsPolicy;
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
-export declare function writeBundle(bundle: SecretsBundle): void;
+/** Options for writeBundle. */
+export interface WriteBundleOptions {
+    /**
+     * Skip evicting the bundle from the secrets-agent broker after the write.
+     * Only for writers that change nothing the broker serves — today that is
+     * stampLastUsed (a usage-telemetry timestamp, fired on every broker HIT):
+     * evicting there would make the cache destroy itself on first use. Every
+     * mutating writer (add / rotate / remove / rename / policy / import) must
+     * leave this unset so a broker-held copy never serves stale values for up
+     * to the ~7d hold.
+     */
+    skipBrokerEviction?: boolean;
+}
+/**
+ * Whether a bundle write should evict the broker-held copy. Pure + exported
+ * for regression coverage. Skips when the writer opted out (stampLastUsed),
+ * when the broker integration is disabled (AGENTS_SECRETS_NO_AGENT — the same
+ * kill-switch the read fast-path honors), or when a test keychain backend is
+ * installed (an in-memory backend has no real keychain behind it, and a test
+ * writing bundle 'prod' must never evict the user's real 'prod' unlock).
+ */
+export declare function shouldEvictAfterBundleWrite(skipRequested: boolean, noAgentEnv: string | undefined, backendOverridden: boolean): boolean;
+export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
@@ -140,6 +165,13 @@ export interface ResolveBundleOptions {
      * needs live values. Also honored via AGENTS_SECRETS_NO_AGENT=1.
      */
     noAgent?: boolean;
+    /**
+     * Resolve only from an already-unlocked secrets-agent snapshot. If the
+     * broker has no snapshot, fail before touching Keychain or any other store.
+     * Background processes use this to guarantee they never surface a biometric
+     * prompt that nobody can answer.
+     */
+    agentOnly?: boolean;
     /**
      * Inject only this subset of keys from the bundle. Keys not in this list are
      * silently excluded from the returned env map. An error is thrown if any

package/dist/lib/secrets/bundles.js

@@ -25,7 +25,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
-import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -105,9 +105,9 @@ export const SECRET_TYPES = [
 ];
 /** Minimum gap between last_used updates so the keychain isn't written on every secrets injection. */
 const LAST_USED_THROTTLE_MS = 60_000;
-const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
-const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
+export const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
+export const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
 const SECRETS_ITEM_PREFIX = 'agents-cli.secrets.';
 export const RESERVED_ENV_NAMES = new Set([
     'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
@@ -277,7 +277,24 @@ export function secretsDefaultPolicy() {
 export function bundlePolicy(bundle) {
     return bundle.policy ?? secretsDefaultPolicy();
 }
-export function writeBundle(bundle) {
+/**
+ * Whether a bundle write should evict the broker-held copy. Pure + exported
+ * for regression coverage. Skips when the writer opted out (stampLastUsed),
+ * when the broker integration is disabled (AGENTS_SECRETS_NO_AGENT — the same
+ * kill-switch the read fast-path honors), or when a test keychain backend is
+ * installed (an in-memory backend has no real keychain behind it, and a test
+ * writing bundle 'prod' must never evict the user's real 'prod' unlock).
+ */
+export function shouldEvictAfterBundleWrite(skipRequested, noAgentEnv, backendOverridden) {
+    if (skipRequested)
+        return false;
+    if (noAgentEnv === '1')
+        return false;
+    if (backendOverridden)
+        return false;
+    return true;
+}
+export function writeBundle(bundle, opts = {}) {
     validateBundleName(bundle.name);
     const backend = bundle.backend ?? 'keychain';
     if (backend === 'file')
@@ -337,12 +354,20 @@ export function writeBundle(bundle) {
     // no-ACL command is missing) rather than silently landing an ACL'd item.
     itemStore(backend).set(bundleMetaItem(bundle.name), json, { noAcl: bundle.policy === 'never' });
     emit('secrets.set', { module: 'secrets', bundle: bundle.name });
+    // A broker-held snapshot predates this write; evict it so the next read
+    // re-resolves from the keychain instead of serving stale values.
+    if (shouldEvictAfterBundleWrite(Boolean(opts.skipBrokerEviction), process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
+        agentEvictSync(bundle.name);
+    }
 }
 export function deleteBundle(name) {
     validateBundleName(name);
     const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
     if (deleted) {
         emit('secrets.delete', { module: 'secrets', bundle: name });
+        if (shouldEvictAfterBundleWrite(false, process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
+            agentEvictSync(name);
+        }
     }
     return deleted;
 }
@@ -513,7 +538,9 @@ function stampLastUsed(bundle) {
     }
     try {
         bundle.last_used = new Date(nowMs).toISOString();
-        writeBundle(bundle);
+        // skipBrokerEviction: this stamp fires on every broker HIT; letting it
+        // evict would make the cache destroy itself on first use.
+        writeBundle(bundle, { skipBrokerEviction: true });
     }
     catch {
         // Swallow — telemetry must never block secret resolution.
@@ -694,7 +721,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             emit('secrets.get', {
                 module: 'secrets',
                 bundle: name,
-                caller: opts.caller,
+                operation: opts.caller,
                 status: 'success',
                 source: 'agent',
                 keyCount: Object.keys(filtered.env).length,
@@ -702,6 +729,9 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
+    if (opts.agentOnly) {
+        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent.`);
+    }
     if (backend === 'file')
         assertFileBackendUsable(name);
     const store = itemStore(backend);
@@ -784,7 +814,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         emit('secrets.get', {
             module: 'secrets',
             bundle: bundle.name,
-            caller: opts.caller,
+            operation: opts.caller,
             status,
             keyCount: keys.length,
             keys,

package/dist/lib/secrets/icloud-import.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Recovery for LEGACY SYNCHRONIZABLE (iCloud Keychain) bundles.
+ *
+ * The pre-biometry helper era defaulted bundles to iCloud Keychain sync. The
+ * device-local cutover (biometry ACL + kSecAttrSynchronizable false on every
+ * query) orphaned those items: they still sync back via iCloud Keychain, but
+ * neither `secrets list` nor `migrate-acl` can see them. This module powers
+ * `agents secrets import --from icloud` — discover the orphaned bundles,
+ * re-import them as normal device-local bundles, and optionally purge the
+ * iCloud copies.
+ *
+ * The item-name scheme is the same one the modern store uses (see bundles.ts):
+ * metadata under `agents-cli.bundles.<name>`, one value per key under
+ * `agents-cli.secrets.<bundle>.<key>`. Env keys can never contain a dot
+ * (ENV_KEY_PATTERN), so splitting a secret service at its LAST dot recovers
+ * the bundle/key boundary even for dotted bundle names like `hetzner.com`.
+ */
+import { type SecretsBackend } from './bundles.js';
+/** One orphaned iCloud bundle, as discovered from the synced item names. */
+export interface SyncedBundleCandidate {
+    /** Bundle name derived from the iCloud service names. */
+    name: string;
+    /** Env keys that have a per-key secret item in the iCloud keychain. */
+    keys: string[];
+    /** True when an `agents-cli.bundles.<name>` metadata item exists in iCloud. */
+    hasMeta: boolean;
+    /** Every iCloud service name belonging to this candidate (the purge set). */
+    services: string[];
+}
+/**
+ * Group raw synced service names into per-bundle candidates. Pure — separated
+ * from discovery so the parsing rules are unit-testable without a keychain.
+ *
+ * A bundle can surface as metadata only (`agents-cli.bundles.<name>`), as
+ * secret items only (`agents-cli.secrets.<bundle>.<KEY>` — metadata never
+ * synced), or both; all three shapes appear in real iCloud strays, so every
+ * one becomes a candidate.
+ */
+export declare function groupSyncedServices(services: string[]): SyncedBundleCandidate[];
+/** Enumerate the iCloud keychain and return every orphaned bundle candidate. */
+export declare function discoverSyncedBundles(): SyncedBundleCandidate[];
+export interface ImportSyncedOptions {
+    /** Overwrite keys that already exist in the local bundle. */
+    force?: boolean;
+    /** Store imported values as literals in the bundle metadata (no keychain items). */
+    allPlaintext?: boolean;
+    /** Backend for a newly created bundle (existing bundles keep theirs). */
+    backend?: SecretsBackend;
+    /** Delete the iCloud copies of successfully-read items after import. */
+    purge?: boolean;
+}
+export interface ImportSyncedResult {
+    name: string;
+    added: number;
+    skipped: number;
+    /** Keys whose iCloud value could not be read (left in place, never purged). */
+    missing: string[];
+    purged: number;
+}
+/**
+ * Import one discovered iCloud bundle into the local (device-local) store.
+ *
+ * Values come from the synced secret items; the synced metadata item, when
+ * present, contributes the description, literal vars, and non-keychain refs
+ * (env:/file:/exec: refs carry no stored secret, so copying the ref preserves
+ * them exactly). Existing local keys are skipped unless `force`. With `purge`,
+ * only services whose value was successfully read are deleted from iCloud —
+ * an unreadable item is never destroyed.
+ */
+export declare function importSyncedBundle(candidate: SyncedBundleCandidate, opts?: ImportSyncedOptions): ImportSyncedResult;