@phnx-labs/agents-cli 1.20.74 → 1.20.77

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

@@ -40,6 +40,7 @@ export declare const DEFAULT_TTL_MS: number;
  * spawnSync argv (unlike a NUL byte); `status` hides these entries.
  */
 export declare const META_CACHE_PREFIX = "!meta:";
+export { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /**
  * Decide whether a persistent broker should self-heal onto freshly-installed
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
@@ -68,12 +69,14 @@ export interface StoredBundle {
     env: Record<string, string>;
     /** epoch ms; the entry is gone once Date.now() passes this. */
     expiresAt: number;
+    harness: string;
 }
 /** One unlocked bundle as reported by `status`. */
 export interface AgentStatusEntry {
     name: string;
     expiresAt: number;
     keyCount: number;
+    harness: string;
 }
 /**
  * Read the current broker capability token, or null if none is present. Clients
@@ -105,10 +108,12 @@ export type Request = {
 } | {
     cmd: 'get';
     name: string;
+    harness?: string;
     token?: string;
 } | {
     cmd: 'load';
     name: string;
+    harness?: string;
     bundle: SecretsBundle;
     env: Record<string, string>;
     ttlMs: number;
@@ -165,6 +170,7 @@ export type Response = {
  * exiting. Pure + exported for unit testing.
  */
 export declare function realBundleCount(store: Map<string, StoredBundle>): number;
+export declare function scopedBundleKey(name: string, harness: string): string;
 export declare function handleAgentRequest(store: Map<string, StoredBundle>, req: Request, now?: number): Response;
 /**
  * Decide whether a `watch-lock` helper line should wipe the in-memory store.
@@ -232,15 +238,61 @@ export declare function startHostedBroker(): Promise<{
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
+/**
+ * Spawn one of the `__secrets-*` sync clients and return its result.
+ *
+ * These three call sites used to hand-roll `spawnSync(process.execPath, ['-e',
+ * <inline node program>, …])`. That is correct only for a JS install, where
+ * `process.execPath` is `node`. Since 1.20.53 the shipped macOS `agents` is a
+ * **bun-compiled Mach-O**, where `process.execPath` is the CLI binary itself —
+ * so the spawn became `agents -e <program> …`, which commander rejects with
+ * `error: unknown option '-e'` and a non-zero exit. Every sync client then took
+ * its own failure path (`agentGetSync` → null, `agentReachableSync` → false,
+ * `agentEvictSync` → no-op), which reads as "broker down" and falls through to
+ * a real keychain read. Net effect on the standalone binary: the broker cache
+ * was never hit, so the `daily` policy's one-prompt-per-7d never applied and
+ * every bundle read re-popped Touch ID.
+ *
+ * Same defect class as the broker-launch bug fixed in 1.20.56 (see cliSpawn's
+ * doc comment); these three sites were simply never converted. Routing them
+ * through `getCliLaunch` fixes both install shapes at once and keeps a single
+ * code path.
+ *
+ * The subcommands are top-level `__secrets-*` tokens intercepted in index.ts
+ * BEFORE commander and before the CLI's startup work, exactly like
+ * `__daemon-run` and `__vault-age-helper`. That is load-bearing, not cosmetic:
+ * a normal command path runs `checkForUpdates()` and `spawnDetachedSync()` on
+ * every invocation (index.ts), so registering these as ordinary hidden
+ * subcommands would fire an update check and spawn a detached background sync
+ * on every cache hit — turning the hot read path into a process fork storm.
+ */
+export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
+    command: string;
+    args: string[];
+};
 /**
  * Synchronous read for the hot path. Returns the cached resolved bundle, or
  * null if the agent isn't running / doesn't hold this bundle / anything fails
  * (soft — caller falls through to the real keychain). macOS only.
  */
-export declare function agentGetSync(name: string): {
+export declare function agentGetSync(name: string, harness?: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Last non-empty line of a child's stdout — the payload line.
+ *
+ * The inline `node -e` client this replaced was a bare node process that could
+ * only ever emit its own JSON. The replacement boots the real CLI, so anything
+ * the CLI prints on the way up shares that stream. Today the known chatter (the
+ * `~/.agents/ is N commits behind` notice) correctly goes to stderr, but a
+ * single future stdout write anywhere in startup would make `JSON.parse` throw
+ * and turn every cache hit back into a silent miss — i.e. quietly reintroduce
+ * the Touch-ID-on-every-read bug this fix closes, with no failing test to catch
+ * it. Anchoring on the last line makes the payload the terminator of the
+ * stream rather than the whole of it, so preceding chatter is inert.
+ */
+export declare function lastLine(stdout: string): string;
 /**
  * Synchronous liveness check: is a broker actually LISTENING and answering (not
  * just a lingering socket file)? Used to decide whether the auto-cache may take
@@ -259,6 +311,25 @@ export declare function agentReachableSync(): boolean;
  * macOS only.
  */
 export declare function agentEvictSync(name: string): void;
+/** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
+ * cache hit. Exit 0 = hit, 3 = miss or broker down. */
+export declare function runAgentGetSync(name: string, harness?: string): Promise<number>;
+/** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
+ * our protocol, 3 = nothing there. Deliberately does NOT gate on
+ * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
+ * synchronous warm path, and a version-skewed broker still answers reads. That
+ * matches the inline program this replaced. */
+export declare function runAgentPingSync(): Promise<number>;
+/** Body of `__secrets-lock <name>`. Best-effort evict; exit 0 even when no
+ * broker answers, so a missing broker never fails the mutating write that
+ * triggered it (agentEvictSync discards this either way).
+ *
+ * An empty name is refused rather than forwarded: the broker treats a nameless
+ * lock as lock-ALL (handleAgentRequest), so a bare `__secrets-lock` would wipe
+ * every held bundle and re-prompt Touch ID for each. That was unreachable while
+ * this was an inline `node -e` string; as a top-level argv token it is one typo
+ * away, and agentEvictSync only ever locks by name. */
+export declare function runAgentLockSync(name: string): Promise<number>;
 /**
  * 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
@@ -321,7 +392,7 @@ export declare function clampHoldMs(v: unknown): number;
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
+export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): void;
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
@@ -336,7 +407,7 @@ export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, e
  */
 export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): Promise<boolean>;
+export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): Promise<boolean>;
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
  * wiped, or 0 when no broker is running. */
 export declare function agentLock(name?: string): Promise<number>;
@@ -364,4 +435,3 @@ export declare function agentPing(): Promise<{
  * gets starved under heavy load, so it's last.
  */
 export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;
-export {};

package/dist/lib/secrets/agent.js

@@ -35,9 +35,10 @@ import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
+import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
-const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION = 2;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 /**
@@ -58,6 +59,34 @@ export const META_CACHE_PREFIX = '!meta:';
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
 /** How often the broker sweeps expired entries. */
 const SWEEP_INTERVAL_MS = 30 * 1000;
+/**
+ * Timeouts for the three synchronous broker clients, split across the process
+ * boundary they now straddle.
+ *
+ * `SOCKET_*` bound the socket round-trip inside the spawned `__secrets-*`
+ * child, and carry over unchanged from the inline `node -e` programs these
+ * replaced. `SYNC_*` bound the parent's `spawnSync` and must additionally cover
+ * the child's boot, so each is its socket budget plus ~2s of headroom. A parent
+ * timeout that fired before the child's own timer would report "broker down"
+ * for a broker that is merely slow, which costs a Touch ID prompt — so the
+ * parent budget is deliberately the looser of the two.
+ *
+ * Boot cost, measured on the bun-compiled binary on an M-series Mac (median of
+ * 15, against a live broker): ~96ms via the index.ts intercept, ~165ms if the
+ * intercept is moved below the startup statements, ~44ms for the `node -e` this
+ * replaces. The intercept is what keeps the regression modest; see index.ts.
+ */
+const SOCKET_GET_TIMEOUT_MS = 2000;
+const SOCKET_PING_TIMEOUT_MS = 700;
+const SOCKET_LOCK_TIMEOUT_MS = 2000;
+const SYNC_GET_TIMEOUT_MS = 4000;
+const SYNC_PING_TIMEOUT_MS = 2500;
+const SYNC_LOCK_TIMEOUT_MS = 4000;
+// The argv tokens live in a leaf module so index.ts can bind the SAME values
+// without importing this one. Re-exported here for callers already reaching for
+// agent.js. See sync-commands.ts for why a shared binding rather than matching
+// literals: the drift it prevents is silent and costs a Touch ID prompt per read.
+export { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /**
  * Decide whether a persistent broker should self-heal onto freshly-installed
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
@@ -104,7 +133,8 @@ function onDarwin() {
 function rehydrateStore(now = Date.now()) {
     const store = new Map();
     for (const { name, entry } of rehydrateSessions(now)) {
-        store.set(name, { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt });
+        const harness = entry.harness || 'cli';
+        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
     }
     return store;
 }
@@ -262,11 +292,14 @@ export async function uninstallSecretsAgentService() {
  */
 export function realBundleCount(store) {
     let n = 0;
-    for (const name of store.keys())
-        if (!name.startsWith(META_CACHE_PREFIX))
+    for (const e of store.values())
+        if (!e.bundle.name.startsWith(META_CACHE_PREFIX))
             n++;
     return n;
 }
+export function scopedBundleKey(name, harness) {
+    return `${harness}:${name}`;
+}
 export function handleAgentRequest(store, req, now = Date.now()) {
     switch (req.cmd) {
         case 'ping':
@@ -276,20 +309,26 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             // the broker is running pre-upgrade code and should be restarted.
             return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION, cliVersion: getCliVersion() };
         case 'get': {
-            const e = store.get(req.name);
+            const key = scopedBundleKey(req.name, req.harness || 'cli');
+            const e = store.get(key);
             if (!e || now >= e.expiresAt) {
                 if (e)
-                    store.delete(req.name); // drop expired on read
+                    store.delete(key); // drop expired on read
                 return { ok: true, cmd: 'get', hit: false };
             }
             return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
         }
         case 'load':
-            store.set(req.name, { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs });
+            const harness = req.harness || 'cli';
+            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs, harness });
             return { ok: true, cmd: 'load' };
         case 'lock': {
             if (req.name) {
-                return { ok: true, cmd: 'lock', wiped: store.delete(req.name) ? 1 : 0 };
+                let wiped = 0;
+                for (const [key, entry] of store)
+                    if (entry.bundle.name === req.name && store.delete(key))
+                        wiped++;
+                return { ok: true, cmd: 'lock', wiped };
             }
             const wiped = store.size;
             store.clear();
@@ -300,9 +339,9 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             for (const [name, e] of store) {
                 if (now >= e.expiresAt)
                     continue;
-                if (name.startsWith(META_CACHE_PREFIX))
-                    continue; // internal list cache, not a user bundle
-                entries.push({ name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length });
+                if (e.bundle.name.startsWith(META_CACHE_PREFIX))
+                    continue; // internal list cache
+                entries.push({ name: e.bundle.name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length, harness: e.harness });
             }
             return { ok: true, cmd: 'status', entries };
         }
@@ -744,51 +783,65 @@ export function agentSocketExists() {
     return onDarwin() && fs.existsSync(socketPath());
 }
 /**
- * Inline node program for the synchronous read fast-path. `readAndResolveBundleEnv`
- * is synchronous and called synchronously everywhere, so we can't await a socket
- * round-trip — but spawning the full CLI to do it would load every command. This
- * minimal `node -e` client connects, asks for one bundle, prints the resolved
- * {bundle, env} as JSON, and exits 0 (hit) / 3 (miss or agent down). argv after
- * -e: [execPath, <socket>, <name>].
+ * Spawn one of the `__secrets-*` sync clients and return its result.
+ *
+ * These three call sites used to hand-roll `spawnSync(process.execPath, ['-e',
+ * <inline node program>, …])`. That is correct only for a JS install, where
+ * `process.execPath` is `node`. Since 1.20.53 the shipped macOS `agents` is a
+ * **bun-compiled Mach-O**, where `process.execPath` is the CLI binary itself —
+ * so the spawn became `agents -e <program> …`, which commander rejects with
+ * `error: unknown option '-e'` and a non-zero exit. Every sync client then took
+ * its own failure path (`agentGetSync` → null, `agentReachableSync` → false,
+ * `agentEvictSync` → no-op), which reads as "broker down" and falls through to
+ * a real keychain read. Net effect on the standalone binary: the broker cache
+ * was never hit, so the `daily` policy's one-prompt-per-7d never applied and
+ * every bundle read re-popped Touch ID.
+ *
+ * Same defect class as the broker-launch bug fixed in 1.20.56 (see cliSpawn's
+ * doc comment); these three sites were simply never converted. Routing them
+ * through `getCliLaunch` fixes both install shapes at once and keeps a single
+ * code path.
+ *
+ * The subcommands are top-level `__secrets-*` tokens intercepted in index.ts
+ * BEFORE commander and before the CLI's startup work, exactly like
+ * `__daemon-run` and `__vault-age-helper`. That is load-bearing, not cosmetic:
+ * a normal command path runs `checkForUpdates()` and `spawnDetachedSync()` on
+ * every invocation (index.ts), so registering these as ordinary hidden
+ * subcommands would fire an update check and spawn a detached background sync
+ * on every cache hit — turning the hot read path into a process fork storm.
  */
-const SYNC_GET_PROGRAM = `
-const net = require('net'), fs = require('fs');
-const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
-let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
-const c = net.createConnection(sock);
-let buf = '';
-const miss = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
-const timer = setTimeout(miss, 2000);
-c.on('error', miss);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name, token }) + '\\n'));
-c.setEncoding('utf-8');
-c.on('data', (d) => {
-  buf += d;
-  const nl = buf.indexOf('\\n');
-  if (nl < 0) return;
-  clearTimeout(timer);
-  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return miss(); }
-  try { c.destroy(); } catch (e) {}
-  if (r && r.ok && r.hit) { process.stdout.write(JSON.stringify({ bundle: r.bundle, env: r.env })); process.exit(0); }
-  process.exit(3);
-});
-`;
+export function syncClientLaunch(sub, agentsBin) {
+    return agentsBin ? getCliLaunch(sub, agentsBin) : getCliLaunch(sub);
+}
+function syncClient(sub, timeout) {
+    // Soft on every failure: bundles.ts's fast path promises "any failure falls
+    // through to the real keychain read below". spawnSync reports most failures
+    // via r.error rather than throwing, but getCliLaunch/getAgentsBinPath DO
+    // throw on a broken install — a bunfs entry whose execPath is gone, or a
+    // browser/computer shim with no sibling index.js. Without this catch those
+    // turn a graceful fallback into a crash, and only on already-degraded
+    // installs, which is the worst time for it.
+    try {
+        const { command, args } = syncClientLaunch(sub);
+        return spawnSync(command, args, { encoding: 'utf-8', timeout });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Synchronous read for the hot path. Returns the cached resolved bundle, or
  * null if the agent isn't running / doesn't hold this bundle / anything fails
  * (soft — caller falls through to the real keychain). macOS only.
  */
-export function agentGetSync(name) {
+export function agentGetSync(name, harness = 'cli') {
     if (!agentSocketExists())
         return null;
-    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name, tokenPath()], {
-        encoding: 'utf-8',
-        timeout: 3000,
-    });
-    if (r.status !== 0 || !r.stdout)
+    const r = syncClient([SYNC_GET_CMD, name, harness], SYNC_GET_TIMEOUT_MS);
+    if (!r || r.status !== 0 || !r.stdout)
         return null;
     try {
-        const o = JSON.parse(r.stdout);
+        const o = JSON.parse(lastLine(r.stdout));
         if (!o || typeof o !== 'object' || !o.env)
             return null;
         return { bundle: o.bundle, env: o.env };
@@ -797,30 +850,28 @@ export function agentGetSync(name) {
         return null;
     }
 }
-/** Inline node program for a synchronous liveness ping. Connects, sends one
- * `{cmd:'ping'}`, exits 0 iff a valid ping response comes back, else 3. A stale
- * socket file with no listener refuses the connection immediately, so this
- * fast-fails without riding any cold-start logic. argv after -e: [execPath, <socket>]. */
-const SYNC_PING_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1];
-const c = net.createConnection(sock);
-let buf = '';
-const dead = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
-const timer = setTimeout(dead, 700);
-c.on('error', dead);
-c.on('connect', () => c.write(JSON.stringify({ cmd: 'ping' }) + '\\n'));
-c.setEncoding('utf-8');
-c.on('data', (d) => {
-  buf += d;
-  const nl = buf.indexOf('\\n');
-  if (nl < 0) return;
-  clearTimeout(timer);
-  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return dead(); }
-  try { c.destroy(); } catch (e) {}
-  process.exit(r && r.ok && r.cmd === 'ping' ? 0 : 3);
-});
-`;
+/**
+ * Last non-empty line of a child's stdout — the payload line.
+ *
+ * The inline `node -e` client this replaced was a bare node process that could
+ * only ever emit its own JSON. The replacement boots the real CLI, so anything
+ * the CLI prints on the way up shares that stream. Today the known chatter (the
+ * `~/.agents/ is N commits behind` notice) correctly goes to stderr, but a
+ * single future stdout write anywhere in startup would make `JSON.parse` throw
+ * and turn every cache hit back into a silent miss — i.e. quietly reintroduce
+ * the Touch-ID-on-every-read bug this fix closes, with no failing test to catch
+ * it. Anchoring on the last line makes the payload the terminator of the
+ * stream rather than the whole of it, so preceding chatter is inert.
+ */
+export function lastLine(stdout) {
+    const lines = stdout.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const t = lines[i].trim();
+        if (t)
+            return t;
+    }
+    return '';
+}
 /**
  * Synchronous liveness check: is a broker actually LISTENING and answering (not
  * just a lingering socket file)? Used to decide whether the auto-cache may take
@@ -834,36 +885,9 @@ export function agentReachableSync() {
         return false;
     if (!agentSocketExists())
         return false;
-    const r = spawnSync(process.execPath, ['-e', SYNC_PING_PROGRAM, socketPath()], { timeout: 1500 });
-    return r.status === 0 && !r.error;
+    const r = syncClient([SYNC_PING_CMD], SYNC_PING_TIMEOUT_MS);
+    return r !== null && r.status === 0 && !r.error;
 }
-/**
- * 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'), fs = require('fs');
-const sock = process.argv[1], name = process.argv[2], tokenPath = process.argv[3];
-let token; try { token = fs.readFileSync(tokenPath, 'utf-8').trim() || undefined; } catch (e) {}
-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, token }) + '\\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
@@ -877,10 +901,60 @@ export function agentEvictSync(name) {
         return;
     if (!agentSocketExists())
         return;
-    try {
-        spawnSync(process.execPath, ['-e', SYNC_LOCK_PROGRAM, socketPath(), name, tokenPath()], { timeout: 3000 });
+    // No try/catch: syncClient swallows its own failures and returns null.
+    syncClient([SYNC_LOCK_CMD, name], SYNC_LOCK_TIMEOUT_MS);
+}
+// ─── Top-level `__secrets-*` sync-client entrypoints ────────────────────────
+// The bodies behind the three spawns above. Each does one socket round-trip and
+// signals the parent through its exit code, mirroring the inline `node -e`
+// programs these replaced: 0 = hit/alive, 3 = miss/down. Lock deviates twice:
+// it reports 0 even when no broker answers, and 3 for an empty name, which it
+// refuses rather than forwarding as a lock-ALL (see runAgentLockSync).
+// Dispatched from index.ts BEFORE commander and before the startup statements,
+// so a cache hit never runs checkForUpdates() or forks a detached sync.
+/** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
+ * cache hit. Exit 0 = hit, 3 = miss or broker down. */
+export async function runAgentGetSync(name, harness = 'cli') {
+    const r = await request({ cmd: 'get', name, harness }, SOCKET_GET_TIMEOUT_MS);
+    if (r?.ok === true && r.cmd === 'get' && r.hit) {
+        // Trailing newline: the parent reads the LAST line (see lastLine), so the
+        // payload must terminate the stream even if anything ever precedes it.
+        //
+        // Awaited on the write callback, not fire-and-forget: stdout is a pipe here
+        // (the parent captures it), pipe writes are asynchronous, and the caller
+        // exits the process the moment this resolves. An unflushed write would be
+        // truncated on exit — the parent would see a partial or empty payload, treat
+        // it as a miss, and fall through to a keychain read, silently costing the
+        // Touch ID prompt this whole path exists to avoid.
+        const payload = JSON.stringify({ bundle: r.bundle, env: r.env }) + '\n';
+        await new Promise((resolve) => { process.stdout.write(payload, () => resolve()); });
+        return 0;
     }
-    catch { /* best-effort */ }
+    return 3;
+}
+/** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
+ * our protocol, 3 = nothing there. Deliberately does NOT gate on
+ * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
+ * synchronous warm path, and a version-skewed broker still answers reads. That
+ * matches the inline program this replaced. */
+export async function runAgentPingSync() {
+    const r = await request({ cmd: 'ping' }, SOCKET_PING_TIMEOUT_MS);
+    return r?.ok === true && r.cmd === 'ping' ? 0 : 3;
+}
+/** Body of `__secrets-lock <name>`. Best-effort evict; exit 0 even when no
+ * broker answers, so a missing broker never fails the mutating write that
+ * triggered it (agentEvictSync discards this either way).
+ *
+ * An empty name is refused rather than forwarded: the broker treats a nameless
+ * lock as lock-ALL (handleAgentRequest), so a bare `__secrets-lock` would wipe
+ * every held bundle and re-prompt Touch ID for each. That was unreachable while
+ * this was an inline `node -e` string; as a top-level argv token it is one typo
+ * away, and agentEvictSync only ever locks by name. */
+export async function runAgentLockSync(name) {
+    if (!name)
+        return 3;
+    await request({ cmd: 'lock', name }, SOCKET_LOCK_TIMEOUT_MS);
+    return 0;
 }
 // Key inside the cached entry's env that holds the JSON metadata snapshot.
 const META_SNAPSHOT_KEY = '__snapshot__';
@@ -992,10 +1066,10 @@ 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) {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = 'cli') {
     if (!onDarwin())
         return;
-    const payload = JSON.stringify({ name, bundle, env, ttlMs });
+    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness });
     // 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
@@ -1062,13 +1136,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);
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? 'cli');
     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) {
-    const r = await request({ cmd: 'load', name, bundle, env, ttlMs });
+export async function agentLoad(name, bundle, env, ttlMs, harness = 'cli') {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness });
     return r?.ok === true && r.cmd === 'load';
 }
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count