@phnx-labs/agents-cli 1.20.50 → 1.20.52

package/dist/lib/hooks/cache.js

@@ -105,13 +105,19 @@ export function getHookShimPath(name) {
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
  * when the content differs from what's on disk. Returns the absolute shim path.
+ *
+ * A shim is generated when the hook opts into caching (`cache`) and/or declares
+ * `matches:` predicates. When `matches` is present the shim gates execution on
+ * those predicates before running the underlying script (see `renderShim`);
+ * when `cache` is absent the shim is a thin pass-through wrapper that only
+ * applies the gate and forwards stdin/stdout unchanged.
  */
 export function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
     const logsDir = args.paths?.logsDir ?? getLogsDir();
     const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
-    const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
+    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
     if (fs.existsSync(shimPath)) {
@@ -132,24 +138,204 @@ export function generateHookShim(args) {
     }
     return shimPath;
 }
+/**
+ * The matches: gate, as a self-contained Python program run once per fire.
+ *
+ * Reads the hook's `matches:` block from $MATCHES_JSON and the event JSON from
+ * stdin, then prints `FIRE` or `SKIP`. A faithful port of `shouldFire()` in
+ * src/lib/hooks/match.ts — all declared predicates AND together, an empty block
+ * always fires, and the same ReDoS guard (`isSafeHookRegex`) rejects unsafe
+ * regexes to `SKIP`. Kept in double-quotes/apostrophe-free so it survives being
+ * embedded in a single-quoted `python -c '...'` argument in the shim. Behavioural
+ * parity with shouldFire() is pinned by a conformance test (match-parity.test.ts).
+ *
+ * On any exception it does NOT print SKIP — the shim treats a missing/garbled
+ * verdict as FIRE (fail-open), so a broken gate never silently disables a hook.
+ */
+const GATE_PY = `import json, os, re, subprocess, sys
+
+def arr(v):
+    if v is None:
+        return []
+    return v if isinstance(v, list) else [v]
+
+def max_group_depth(src):
+    depth = 0
+    mx = 0
+    escaped = False
+    in_class = False
+    for ch in src:
+        if escaped:
+            escaped = False
+            continue
+        if ch == chr(92):
+            escaped = True
+            continue
+        if ch == "[":
+            in_class = True
+            continue
+        if ch == "]":
+            in_class = False
+            continue
+        if in_class:
+            continue
+        if ch == "(":
+            depth += 1
+            if depth > mx:
+                mx = depth
+        elif ch == ")" and depth > 0:
+            depth -= 1
+    return mx
+
+_NESTED = re.compile(r"\\((?:\\?:)?[^)]*[*+][?+*{,\\d}]*[^)]*\\)\\s*(?:[+*]|\\{\\d*,?\\d*\\})")
+
+def is_safe(src):
+    if len(src) > 200:
+        return False
+    if max_group_depth(src) > 3:
+        return False
+    if _NESTED.search(src):
+        return False
+    return True
+
+def compile_rx(src):
+    if not is_safe(src):
+        return None
+    try:
+        return re.compile(src)
+    except re.error:
+        return None
+
+def find_root(start):
+    d = os.path.abspath(start)
+    while True:
+        if os.path.exists(os.path.join(d, ".git")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+def git_dirty(cwd):
+    try:
+        out = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+        )
+        return len(out.stdout.decode().strip()) > 0
+    except Exception:
+        return False
+
+def should_fire():
+    m = json.loads(os.environ.get("MATCHES_JSON") or "{}")
+    if not m:
+        return True
+    try:
+        inp = json.load(sys.stdin)
+    except Exception:
+        inp = {}
+    cwd = inp.get("cwd") or os.getcwd()
+
+    v = m.get("prompt_contains")
+    if v is not None:
+        if v not in (inp.get("prompt") or ""):
+            return False
+
+    v = m.get("prompt_matches")
+    if v is not None:
+        rx = compile_rx(v)
+        if rx is None or not rx.search(inp.get("prompt") or ""):
+            return False
+
+    v = m.get("tool_name")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            tn = inp.get("tool_name")
+            if not tn or tn not in allowed:
+                return False
+
+    v = m.get("tool_args_match")
+    if v is not None:
+        ta = inp.get("tool_args")
+        ser = ta if isinstance(ta, str) else json.dumps(ta if ta is not None else "", separators=(",", ":"))
+        rx = compile_rx(v)
+        if rx is None or not rx.search(ser):
+            return False
+
+    v = m.get("cwd_includes")
+    if v is not None:
+        needles = arr(v)
+        if needles and not any(n in cwd for n in needles):
+            return False
+
+    v = m.get("project_has")
+    if v is not None:
+        root = find_root(cwd)
+        if not root or not os.path.exists(os.path.join(root, v)):
+            return False
+
+    v = m.get("git_dirty")
+    if v is not None:
+        if bool(v) != git_dirty(cwd):
+            return False
+
+    return True
+
+print("FIRE" if should_fire() else "SKIP")
+`;
+/**
+ * Gate-only pass-through tail: no caching, just run the underlying script with
+ * stdin forwarded and stdout/exit code propagated, plus one timing log line.
+ * Used when a hook declares \`matches:\` but no \`cache:\`.
+ */
+const PASSTHROUGH_TAIL = `now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
+START_NS=$(now_ns)
+EXIT=0
+if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE"; then
+  EXIT=0
+else
+  EXIT=$?
+fi
+END_NS=$(now_ns)
+MS=$(( (END_NS - START_NS) / 1000000 ))
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
+  "$TS" "$HOOK_NAME" "$MS" "none" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+
+exit "$EXIT"`;
 /**
  * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
  * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
  * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
  * stub — which exits non-zero without running — doesn't silently break caching.
+ *
+ * When `matches` is set, an early gate block evaluates the `matches:` predicates
+ * against the event JSON on stdin and exits 0 without running the script when
+ * they don't hold — this is the runtime enforcement of the documented `matches:`
+ * gating (mirrors `shouldFire()` in match.ts). When `cache` is null the shim is
+ * a gate-only pass-through: it forwards stdin to the script and its stdout back,
+ * with no cache read/write.
  */
-function renderShim(name, scriptPath, cache, paths) {
-    const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
-    const key = cache.key ?? 'global';
-    const prefetch = cache.prefetch ?? 'none';
+function renderShim(name, scriptPath, cache, matches, paths) {
+    const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
+    const key = cache?.key ?? 'global';
+    const prefetch = cache?.prefetch ?? 'none';
     const { cacheDir, logsDir } = paths;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    const matchesJson = hasMatches ? JSON.stringify(matches) : '';
     // sh-escape: wrap in single quotes, escape any embedded single quotes.
     const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    const cacheHeader = cache
+        ? `# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}`
+        : `# Cache: none (gate-only pass-through)`;
+    const matchesHeader = hasMatches ? `\n# Matches: ${matchesJson}` : '';
     return `#!/usr/bin/env bash
 # GENERATED by agents-cli. Do not edit — re-run \`agents hooks sync\` to refresh.
 # Hook: ${name}
 # Source: ${scriptPath}
-# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}
+${cacheHeader}${matchesHeader}
 set -u
 
 HOOK_NAME=${q(name)}
@@ -159,6 +345,7 @@ LOGS_DIR=${q(logsDir)}
 TTL=${ttl}
 PREFETCH=${q(prefetch)}
 KEY_MODE=${q(key)}
+MATCHES_JSON=${q(matchesJson)}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR"
 
@@ -178,7 +365,33 @@ done
 # Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
-# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
+# --- matches: gate (issue #744 / RUSH-1506) -------------------------------
+# Enforce the hook's declared \`matches:\` predicates at fire time. Mirrors
+# shouldFire() in src/lib/hooks/match.ts: all declared predicates AND together;
+# an empty/absent block always fires. When the predicates don't hold we exit 0
+# WITHOUT running the script (a skipped hook is not an error). Fail-open: any
+# gate-eval error runs the script, so a broken predicate can never silently
+# disable a safety hook (e.g. git-guard).
+if [ -n "$MATCHES_JSON" ]; then
+  _GATE="$(printf '%s' "$STDIN_PAYLOAD" | MATCHES_JSON="$MATCHES_JSON" "$PY" -c ${q(GATE_PY)} 2>/dev/null || printf FIRE)"
+  [ -z "$_GATE" ] && _GATE=FIRE
+  if [ "$_GATE" = SKIP ]; then
+    _TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    _LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+    printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":0,"cache":"skip","exit":0}\\n' \\
+      "$_TS" "$HOOK_NAME" >>"$_LOG_FILE" 2>/dev/null || true
+    exit 0
+  fi
+fi
+${cache ? CACHE_TAIL : PASSTHROUGH_TAIL}
+`;
+}
+/**
+ * Cache tail: the full cache lookup / stale-while-revalidate / timing machinery.
+ * Emitted only when the hook opts into \`cache:\`. (When only \`matches:\` is set,
+ * PASSTHROUGH_TAIL runs instead — no cache read/write.)
+ */
+const CACHE_TAIL = `# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
 # \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
 sha1_12() { "$PY" -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
 
@@ -267,7 +480,6 @@ printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%
 
 exit "$EXIT"
 `;
-}
 /**
  * Remove a hook's shim. Called by the registrar's garbage collection when a
  * hook is renamed/deleted or has its `cache:` field removed.

package/dist/lib/hooks.js

@@ -153,10 +153,12 @@ import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
  *
- * Returns either the raw script path (no `cache:` set, legacy behavior) or
- * the path to a generated caching/timing shim. The shim is written as a
- * side effect when `cache:` is configured. The agent-native settings file
- * gets the same shape either way — just a different command path.
+ * Returns either the raw script path (neither `cache:` nor `matches:` set,
+ * legacy behavior) or the path to a generated wrapper shim. The shim is written
+ * as a side effect when `cache:` and/or `matches:` is configured — it enforces
+ * the `matches:` gate at fire time and layers the caching/timing machinery when
+ * `cache:` is set. The agent-native settings file gets the same shape either
+ * way — just a different command path.
  */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
@@ -165,13 +167,20 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     if (!isValidHookShimName(name))
         return null;
     const cache = parseCacheConfig(hookDef.cache);
-    if (!cache) {
-        // No caching opted in — make sure a previously generated shim from an
-        // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
+    const matches = hookDef.matches;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    if (!cache && !hasMatches) {
+        // No caching and no matches: gate opted in — make sure a previously
+        // generated shim from an earlier `cache:`/`matches:` config is gone so the
+        // JSONL doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    return toPortableCommand(generateHookShim({ name, scriptPath, cache }));
+    // A shim is generated when the hook opts into caching and/or declares
+    // `matches:` predicates. The shim enforces the `matches:` gate at fire time
+    // (skipping the script when predicates don't hold) and, when `cache:` is set,
+    // layers the cache/timing machinery on top.
+    return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file
@@ -1019,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');
@@ -1102,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/platform/exec.d.ts

@@ -14,7 +14,10 @@ export declare function needsWindowsShell(binary: string, platform?: NodeJS.Plat
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per
  * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX.
+ * shell would actually run, matching `which` semantics on POSIX. stderr is
+ * dropped: a miss is an expected outcome here, and `where.exe` announces every
+ * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
+ * into the caller's terminal once per probe.
  */
 export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;
 /**

package/dist/lib/platform/exec.js

@@ -27,11 +27,17 @@ export function needsWindowsShell(binary, platform = process.platform) {
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per
  * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX.
+ * shell would actually run, matching `which` semantics on POSIX. stderr is
+ * dropped: a miss is an expected outcome here, and `where.exe` announces every
+ * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
+ * into the caller's terminal once per probe.
  */
 export function findExecutable(name, platform = process.platform) {
     try {
-        const out = execFileSync(whichCommand(platform), [name], { encoding: 'utf-8' });
+        const out = execFileSync(whichCommand(platform), [name], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
         const first = out.trim().split(/\r?\n/)[0]?.trim();
         return first || null;
     }

package/dist/lib/resources.d.ts

@@ -74,11 +74,3 @@ export interface GetAgentResourcesOptions {
  * This is the source of truth - not the tracking data in agents.yaml.
  */
 export declare function getAgentResources(agentId: AgentId, options?: GetAgentResourcesOptions): AgentResources;
-/**
- * Get resources for all agents.
- */
-export declare function getAllAgentResources(agentIds: AgentId[], options?: GetAgentResourcesOptions & {
-    cliStates?: Record<AgentId, {
-        installed: boolean;
-    }>;
-}): AgentResources[];

package/dist/lib/resources.js

@@ -180,13 +180,3 @@ export function getAgentResources(agentId, options = {}) {
         workflows,
     };
 }
-/**
- * Get resources for all agents.
- */
-export function getAllAgentResources(agentIds, options = {}) {
-    const { cliStates, ...restOptions } = options;
-    return agentIds.map((agentId) => {
-        const cliInstalled = cliStates?.[agentId]?.installed ?? true;
-        return getAgentResources(agentId, { ...restOptions, cliInstalled });
-    });
-}

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/runner.js

@@ -74,8 +74,16 @@ export function buildJobCommand(config, resolvedPrompt) {
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'codex') {
-        if (mode === 'edit') {
-            cmd.push('--dangerously-bypass-approvals-and-sandbox');
+        if (mode === 'plan') {
+            // The template defaults to workspace-write; plan means read-only.
+            const sbIndex = cmd.indexOf('--sandbox');
+            if (sbIndex !== -1)
+                cmd[sbIndex + 1] = 'read-only';
+        }
+        else if (mode === 'edit' || mode === 'auto') {
+            // Keep the workspace-write sandbox — no approval bypass; only skip drops
+            // the guardrails. Re-enable network, which workspace-write turns off.
+            cmd.push('-c', 'sandbox_workspace_write.network_access=true');
         }
         else if (mode === 'skip') {
             // Remove sandbox restriction, just --dangerously-bypass-approvals-and-sandbox

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