@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/secrets/filestore.js

@@ -21,7 +21,7 @@
  * item and its keychain twin carry identical names:
  *   `agents-cli.bundles.<name>` and `agents-cli.secrets.<bundle>.<key>`.
  */
-import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -210,6 +210,128 @@ export function decryptForFallback(enc, passphrase) {
     const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
     return plaintext.toString('utf8');
 }
+// ---------- bundle-metadata plaintext cache (PHNX-3585) ----------
+//
+// Enumerating file-backed bundles — `agents secrets list`, and the
+// account-rotation `readAccountRegistry` on the `agents run` hot path — decrypts
+// EVERY bundle's metadata item, and each decrypt runs a fresh scrypt KDF (~12ms)
+// because every `.enc` file carries its own random salt. On a box with dozens of
+// bundles that is hundreds of ms of pure KDF before the harness even starts (the
+// ~0.55s New-Claude boot cost in PHNX-3585).
+//
+// Bundle METADATA is non-secret by contract (secrets/bundles.ts `writeBundle`:
+// "Metadata is non-sensitive by contract", stored no-ACL so `secrets list`
+// enumerates without Touch ID) — the vars hold `keychain:`/`env:`/literal REFS,
+// never the secret bytes, which live in separate `agents-cli.secrets.<bundle>.*`
+// value items. So its decrypted JSON is safe to cache in cleartext, at the SAME
+// 0600 protection as the ciphertext beside it.
+//
+// The cache keys each entry on the `.enc` file's (mtimeMs,size) plus a
+// passphrase fingerprint, so ANY bundle write (new mtime/size) or passphrase
+// change (new fingerprint; rotation also re-writes every file) misses and
+// re-derives — no staleness, self-healing on any miss. It is scoped to the
+// metadata namespace ONLY (`agents-cli.bundles.`); secret VALUE items are never
+// read through it, so no secret is ever written to the cache.
+const META_ITEM_PREFIX = 'agents-cli.bundles.';
+function isMetaItem(item) {
+    return item.startsWith(META_ITEM_PREFIX);
+}
+let metaCache = null;
+let metaCacheDirty = false;
+let metaCacheFlushRegistered = false;
+function metaCachePath() {
+    // A SIBLING of the store dir, never inside it — the same rule the store lock
+    // above follows, so a rotation's store-dir rename / `.rotate-*` sweep never
+    // moves or reaps it. Under `~/.agents/.cache/`, so it is machine-local and
+    // never enters `agents repo push/pull`.
+    return `${fileDir()}.meta-cache.json`;
+}
+function passphraseFingerprint() {
+    // Non-reversible tag, never the passphrase itself — so a passphrase change
+    // invalidates the cache without the key ever landing on disk in the clear.
+    return createHash('sha256').update(getPassphrase()).digest('hex').slice(0, 16);
+}
+function loadMetaCache() {
+    if (metaCache)
+        return metaCache;
+    const keyFp = passphraseFingerprint();
+    try {
+        const doc = JSON.parse(fs.readFileSync(metaCachePath(), 'utf8'));
+        if (doc && doc.v === 1 && doc.keyFp === keyFp && doc.entries && typeof doc.entries === 'object') {
+            metaCache = doc;
+            return metaCache;
+        }
+    }
+    catch {
+        /* absent or corrupt — rebuild from scratch */
+    }
+    metaCache = { v: 1, keyFp, entries: {} };
+    return metaCache;
+}
+/** Decrypted metadata for `item` if the cache holds a fresh entry, else null. */
+function metaCacheGet(item, fp) {
+    let st;
+    try {
+        st = fs.statSync(fp);
+    }
+    catch {
+        return null;
+    }
+    const e = loadMetaCache().entries[item];
+    return e && e.mtimeMs === st.mtimeMs && e.size === st.size ? e.plain : null;
+}
+/** Record freshly-decrypted metadata for `item`, flushed once at process exit.
+ *  `snapshot` is the pre-readFileSync stat — the identity of the bytes just
+ *  decrypted. Skip the put if a post-decrypt stat does not match: a concurrent
+ *  writer during scrypt must not pin that plaintext to the new file identity. */
+function metaCachePut(item, fp, plain, snapshot) {
+    try {
+        const now = fs.statSync(fp);
+        if (now.mtimeMs !== snapshot.mtimeMs || now.size !== snapshot.size)
+            return;
+    }
+    catch {
+        return;
+    }
+    loadMetaCache().entries[item] = { mtimeMs: snapshot.mtimeMs, size: snapshot.size, plain };
+    metaCacheDirty = true;
+    if (!metaCacheFlushRegistered) {
+        metaCacheFlushRegistered = true;
+        process.on('exit', flushMetaCache);
+    }
+}
+/** Drop a cached entry the moment its file is rewritten or removed, so a
+ *  same-process write→read never returns pre-write metadata (mtime/size alone
+ *  can collide within a millisecond on an unchanged-length rewrite). */
+function metaCacheEvict(item) {
+    if (!isMetaItem(item))
+        return;
+    const cache = metaCache;
+    if (cache && cache.entries[item]) {
+        delete cache.entries[item];
+        metaCacheDirty = true;
+    }
+}
+function flushMetaCache() {
+    if (!metaCacheDirty || !metaCache)
+        return;
+    metaCacheDirty = false;
+    // Prune entries whose `.enc` file is gone so churn can't grow the cache without
+    // bound; a surviving stale entry would re-validate against mtime/size anyway.
+    for (const item of Object.keys(metaCache.entries)) {
+        if (!fs.existsSync(fileFor(item)))
+            delete metaCache.entries[item];
+    }
+    try {
+        ensureFileDir();
+        const tmp = `${metaCachePath()}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(metaCache), { mode: 0o600 });
+        fs.renameSync(tmp, metaCachePath());
+    }
+    catch {
+        /* the cache is advisory — a write failure just re-derives next run */
+    }
+}
 // ---------- file backend ----------
 function fileFor(item) {
     return path.join(fileDir(), `${item}.enc`);
@@ -226,6 +348,26 @@ function fileGet(item) {
     if (!fs.existsSync(fp)) {
         throw new Error(`Secret '${item}' not found in encrypted store.`);
     }
+    // Non-secret metadata short-circuits the scrypt decrypt when the file is
+    // unchanged (see the cache block above). Secret VALUE items skip the cache
+    // entirely, so they always decrypt fresh and never touch cleartext storage.
+    const metaItem = isMetaItem(item);
+    if (metaItem) {
+        const hit = metaCacheGet(item, fp);
+        if (hit !== null)
+            return hit;
+    }
+    // Identity of the bytes we are about to decrypt. A post-decrypt stat would
+    // attribute this plaintext to a concurrent writer's new file.
+    let snapshot;
+    if (metaItem) {
+        try {
+            snapshot = fs.statSync(fp);
+        }
+        catch {
+            snapshot = undefined;
+        }
+    }
     const raw = fs.readFileSync(fp, 'utf8');
     let parsed;
     try {
@@ -234,12 +376,16 @@ function fileGet(item) {
     catch {
         throw new Error(`Encrypted secret file ${fp} is corrupt (not valid JSON).`);
     }
+    let plain;
     try {
-        return decryptForFallback(parsed, getPassphrase());
+        plain = decryptForFallback(parsed, getPassphrase());
     }
     catch {
         throw new Error(`Failed to decrypt '${item}'. Wrong AGENTS_SECRETS_PASSPHRASE or tampered file.`);
     }
+    if (metaItem && snapshot)
+        metaCachePut(item, fp, plain, snapshot);
+    return plain;
 }
 function fileGetBatch(items) {
     const out = new Map();
@@ -262,12 +408,13 @@ function fileSet(item, value) {
         const enc = encryptForFallback(value, getPassphrase());
         fs.writeFileSync(fileFor(item), JSON.stringify(enc), { mode: 0o600 });
     });
+    metaCacheEvict(item);
 }
 function fileDelete(item) {
     const fp = fileFor(item);
     if (!fs.existsSync(fp))
         return true; // idempotent, matches secret-tool clear
-    return withStoreLock(() => {
+    const deleted = withStoreLock(() => {
         // Re-check under the lock — a rotation may have swapped the dir since the
         // pre-lock existence probe above.
         if (!fs.existsSync(fp))
@@ -275,6 +422,8 @@ function fileDelete(item) {
         fs.unlinkSync(fp);
         return true;
     });
+    metaCacheEvict(item);
+    return deleted;
 }
 function fileList(prefix) {
     const dir = fileDir();
@@ -921,6 +1070,18 @@ export function _resetFileStoreForTest(opts = {}) {
     warnedAutoPassphrase = false;
     lockAcquireTimeoutMsOverride = null;
     lockStaleMsOverride = null;
+    // Drop the in-memory metadata cache so a test that repoints the store dir or
+    // passphrase never reads another fixture's cached plaintext (the on-disk cache
+    // is per-dir and keyed by the passphrase fingerprint, so it self-invalidates
+    // too, but the process-level map must be cleared explicitly).
+    metaCache = null;
+    metaCacheDirty = false;
+}
+/** Test-only: flush the in-memory metadata cache to disk now. Production flushes
+ *  once at process exit; a test needs the on-disk copy mid-run to simulate the
+ *  next `agents` process reading it. */
+export function _flushMetaCacheForTest() {
+    flushMetaCache();
 }
 /** Test-only: shorten the store-lock acquire timeout so a contended-lock assertion
  *  fails fast instead of waiting out the 30s production budget. */

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

@@ -34,6 +34,8 @@ export interface PushBundleOptions {
     agentOnly?: boolean;
     /** Non-secret literals whose bundle value kind must survive the dotenv transport. */
     literalValues?: Record<string, string>;
+    /** Per-SSH-operation deadline. Async daemon callers must set this explicitly. */
+    timeoutMs?: number;
 }
 export interface PushBundleResult {
     ok: boolean;
@@ -121,3 +123,11 @@ export declare function planPushTransport(resolved: ResolvedBundleForPush, bundl
 export declare function pushResolvedBundleToHost(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;
 /** Resolve and push in one call — for a single host. */
 export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;
+/**
+ * Async, kill-bounded push for daemon services. It preserves the foreground
+ * primitive's transport, read-back verification, and literal restoration; only
+ * the SSH execution strategy differs.
+ */
+export declare function pushResolvedBundleToHostAsync(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;
+/** Resolve locally once, then run the daemon-safe async push. */
+export declare function pushBundleToHostAsync(bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;

package/dist/lib/secrets/push.js

@@ -19,10 +19,10 @@
  *   reading a bundle can prompt (Touch ID); doing it per host would prompt per
  *   host. `export --device a,b,c` resolves once and pushes three times.
  */
-import { sshExec } from '../ssh-exec.js';
+import { sshExec, sshExecAsync } from '../ssh-exec.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
-import { remoteSecretsRaw, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, credentialTransportSshOpts, } from './remote.js';
+import { remoteSecretsRaw, remoteSecretsRawAsync, verifyRemoteKeychainPush, verifyRemoteKeychainPushAsync, keychainWriteFailureMessage, buildRemoteFileImportCommand, credentialTransportSshOpts, } from './remote.js';
 import { readAndResolveBundleEnv } from './bundles.js';
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
@@ -138,8 +138,8 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
     // the raw-`ssh` branch's half of that; the `remote-secrets` branch and the
     // read-back/policy/literal follow-ups pass `secret: true` for the same posture.
     const res = plan.kind === 'ssh'
-        ? sshExec(host, plan.remoteCmd, { input: plan.input, hostKeyOpts: credentialTransportSshOpts(host).hostKeyOpts, multiplex: plan.multiplex })
-        : remoteSecretsRaw(host, plan.args, { input: plan.input, osLookupName: host, secret: true });
+        ? sshExec(host, plan.remoteCmd, { input: plan.input, timeoutMs: opts.timeoutMs, hostKeyOpts: credentialTransportSshOpts(host).hostKeyOpts, multiplex: plan.multiplex })
+        : remoteSecretsRaw(host, plan.args, { input: plan.input, timeoutMs: opts.timeoutMs, osLookupName: host, secret: true });
     if (res.code === null) {
         return fail(res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed'));
     }
@@ -154,7 +154,7 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
     //   - file: a forwarded AGENTS_SECRETS_PASSPHRASE keys ciphertext to a secret
     //     the destination daemon does not hold (PHNX-2371).
     // Read the bundle back the way a later resolve will and FAIL LOUDLY.
-    const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host, secret: true });
+    const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host, secret: true, timeoutMs: opts.timeoutMs });
     if (!verdict.ok) {
         if (opts.remoteBackend === 'keychain' && verdict.kind === 'locked-keychain') {
             return fail(keychainWriteFailureMessage(host, bundle, verdict.reason));
@@ -168,12 +168,12 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
         return fail(`pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
     }
     for (const step of planLiteralRestoration(bundle, opts.literalValues)) {
-        const removed = remoteSecretsRaw(host, step.removeArgs, { osLookupName: host, secret: true });
+        const removed = remoteSecretsRaw(host, step.removeArgs, { osLookupName: host, secret: true, timeoutMs: opts.timeoutMs });
         if (removed.code !== 0) {
             const msg = (removed.stderr || removed.stdout || '').trim();
             return fail(`pushed '${bundle}' but could not replace transported ${step.key}${msg ? `: ${msg}` : ''}`);
         }
-        const literal = remoteSecretsRaw(host, step.addArgs, { osLookupName: host, secret: true });
+        const literal = remoteSecretsRaw(host, step.addArgs, { osLookupName: host, secret: true, timeoutMs: opts.timeoutMs });
         if (literal.code !== 0) {
             const msg = (literal.stderr || literal.stdout || '').trim();
             return fail(`pushed '${bundle}' but could not preserve literal ${step.key}${msg ? `: ${msg}` : ''}`);
@@ -192,3 +192,82 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
 export function pushBundleToHost(bundle, host, opts) {
     return pushResolvedBundleToHost(resolveBundleForPush(bundle, opts.operation, { agentOnly: opts.agentOnly }), bundle, host, opts);
 }
+/**
+ * Async, kill-bounded push for daemon services. It preserves the foreground
+ * primitive's transport, read-back verification, and literal restoration; only
+ * the SSH execution strategy differs.
+ */
+export async function pushResolvedBundleToHostAsync(resolved, bundle, host, opts) {
+    const fail = (message) => ({ ok: false, host, bundle, keyCount: resolved.keyCount, message });
+    const plan = planPushTransport(resolved, bundle, host, opts);
+    if (plan.kind === 'refuse')
+        return fail(plan.message);
+    const res = plan.kind === 'ssh'
+        ? await sshExecAsync(host, plan.remoteCmd, {
+            input: plan.input,
+            timeoutMs: opts.timeoutMs,
+            hostKeyOpts: credentialTransportSshOpts(host).hostKeyOpts,
+            multiplex: plan.multiplex,
+        })
+        : await remoteSecretsRawAsync(host, plan.args, {
+            input: plan.input,
+            timeoutMs: opts.timeoutMs,
+            osLookupName: host,
+            secret: true,
+        });
+    if (res.code === null)
+        return fail(res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed'));
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        return fail(`remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`);
+    }
+    const verdict = await verifyRemoteKeychainPushAsync(host, bundle, Object.keys(resolved.env), {
+        osLookupName: host,
+        secret: true,
+        timeoutMs: opts.timeoutMs,
+    });
+    if (!verdict.ok) {
+        if (opts.remoteBackend === 'keychain' && verdict.kind === 'locked-keychain') {
+            return fail(keychainWriteFailureMessage(host, bundle, verdict.reason));
+        }
+        if (opts.remoteBackend === 'file') {
+            return fail(`${host}: pushed '${bundle}' but the remote could not decrypt it (${verdict.reason}). ` +
+                `File-backend export never forwards AGENTS_SECRETS_PASSPHRASE — the remote keys ` +
+                `the bundle under its own machine-local key. If the destination still cannot read, ` +
+                `unset a stale AGENTS_SECRETS_PASSPHRASE there (\`agents doctor\`).`);
+        }
+        return fail(`pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
+    }
+    for (const step of planLiteralRestoration(bundle, opts.literalValues)) {
+        const removed = await remoteSecretsRawAsync(host, step.removeArgs, {
+            osLookupName: host,
+            secret: true,
+            timeoutMs: opts.timeoutMs,
+        });
+        if (removed.code !== 0) {
+            const msg = (removed.stderr || removed.stdout || '').trim();
+            return fail(`pushed '${bundle}' but could not replace transported ${step.key}${msg ? `: ${msg}` : ''}`);
+        }
+        const literal = await remoteSecretsRawAsync(host, step.addArgs, {
+            osLookupName: host,
+            secret: true,
+            timeoutMs: opts.timeoutMs,
+        });
+        if (literal.code !== 0) {
+            const msg = (literal.stderr || literal.stdout || '').trim();
+            return fail(`pushed '${bundle}' but could not preserve literal ${step.key}${msg ? `: ${msg}` : ''}`);
+        }
+    }
+    const remoteMsg = (res.stdout || '').trim().split('\n').map((line) => line.trim()).filter(Boolean).pop();
+    return {
+        ok: true,
+        host,
+        bundle,
+        keyCount: resolved.keyCount,
+        message: remoteMsg || `${resolved.keyCount} key(s) exported`,
+    };
+}
+/** Resolve locally once, then run the daemon-safe async push. */
+export function pushBundleToHostAsync(bundle, host, opts) {
+    return pushResolvedBundleToHostAsync(resolveBundleForPush(bundle, opts.operation, { agentOnly: opts.agentOnly }), bundle, host, opts);
+}

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

@@ -6,6 +6,14 @@
  * and injects it ephemerally without persisting it locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
+export declare const REMOTE_TIMEOUT_MS = 30000;
+export interface RemoteSecretsRawOptions {
+    tty?: boolean;
+    input?: string;
+    osLookupName?: string;
+    secret?: boolean;
+    timeoutMs?: number;
+}
 /**
  * SSH options for secret-carrying transport. Pins the managed host key and
  * disables multiplex so no reusable control socket lingers for other invocations.
@@ -53,12 +61,9 @@ export declare function splitBundleRef(ref: string): {
  * result. Used by browse commands; `tty` forces `-tt` so remote passphrase
  * prompts can surface.
  */
-export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
-    tty?: boolean;
-    input?: string;
-    osLookupName?: string;
-    secret?: boolean;
-}): SshExecResult;
+export declare function remoteSecretsRaw(target: string, args: string[], opts?: RemoteSecretsRawOptions): SshExecResult;
+/** Async, kill-bounded inverse of {@link remoteSecretsRaw} for daemon callers. */
+export declare function remoteSecretsRawAsync(target: string, args: string[], opts?: RemoteSecretsRawOptions): Promise<SshExecResult>;
 /**
  * Run a remote `agents secrets <args>` foreground with local stdio inherited,
  * so the remote sees a real TTY and its passphrase prompt surfaces and reads
@@ -122,7 +127,14 @@ export declare function keychainWriteFailureMessage(host: string, bundle: string
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
     secret?: boolean;
+    timeoutMs?: number;
 }): RemoteKeychainWriteVerification;
+/** Async, kill-bounded read-back verification for daemon-originated pushes. */
+export declare function verifyRemoteKeychainPushAsync(target: string, bundle: string, pushedKeys: string[], opts?: {
+    osLookupName?: string;
+    secret?: boolean;
+    timeoutMs?: number;
+}): Promise<RemoteKeychainWriteVerification>;
 /**
  * `bash -lc` command + stdin payload for a file-backed remote import.
  *

package/dist/lib/secrets/remote.js

@@ -5,7 +5,7 @@
  * Browse streams remote stdout verbatim; use resolves a bundle to an env map
  * and injects it ephemerally without persisting it locally.
  */
-import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { sshExec, sshExecAsync, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { emitSecretAudit } from './audit.js';
 import { sshTargetFor } from '../hosts/types.js';
@@ -13,7 +13,7 @@ import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { isLoaderOrInterpreterEnv } from './bundles.js';
 import { isHostPinned, hostKeyCheckingOpts } from '../devices/known-hosts.js';
-const REMOTE_TIMEOUT_MS = 30_000;
+export const REMOTE_TIMEOUT_MS = 30_000;
 /** The host part of an ssh target (`user@host` -> `host`) for known_hosts matching. */
 function hostKeyLookupName(target) {
     return target.split('@').pop() ?? target;
@@ -125,7 +125,20 @@ export function remoteSecretsRaw(target, args, opts = {}) {
         ? { ...posture, extraSshArgs: ['-tt'], multiplex: false }
         : posture;
     return sshExec(target, remoteCmd, {
-        timeoutMs: REMOTE_TIMEOUT_MS,
+        timeoutMs: opts.timeoutMs ?? REMOTE_TIMEOUT_MS,
+        input: opts.input,
+        ...conn,
+    });
+}
+/** Async, kill-bounded inverse of {@link remoteSecretsRaw} for daemon callers. */
+export function remoteSecretsRawAsync(target, args, opts = {}) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
+    const posture = opts.secret ? credentialTransportSshOpts(target) : {};
+    const conn = opts.tty
+        ? { ...posture, extraSshArgs: ['-tt'], multiplex: false }
+        : posture;
+    return sshExecAsync(target, remoteCmd, {
+        timeoutMs: opts.timeoutMs ?? REMOTE_TIMEOUT_MS,
         input: opts.input,
         ...conn,
     });
@@ -270,9 +283,21 @@ export function keychainWriteFailureMessage(host, bundle, reason) {
 export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
     const res = sshExec(target, remoteCmd, {
-        timeoutMs: REMOTE_TIMEOUT_MS,
+        timeoutMs: opts.timeoutMs ?? REMOTE_TIMEOUT_MS,
+        ...(opts.secret ? credentialTransportSshOpts(target) : {}),
+    });
+    return evaluateRemoteKeychainPushResult(pushedKeys, res);
+}
+/** Async, kill-bounded read-back verification for daemon-originated pushes. */
+export async function verifyRemoteKeychainPushAsync(target, bundle, pushedKeys, opts = {}) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
+    const res = await sshExecAsync(target, remoteCmd, {
+        timeoutMs: opts.timeoutMs ?? REMOTE_TIMEOUT_MS,
         ...(opts.secret ? credentialTransportSshOpts(target) : {}),
     });
+    return evaluateRemoteKeychainPushResult(pushedKeys, res);
+}
+function evaluateRemoteKeychainPushResult(pushedKeys, res) {
     if (res.code !== 0) {
         const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
         const stderr = `${why}${(res.stderr || res.stdout || '').trim() ? `: ${(res.stderr || res.stdout).trim()}` : ''}`;

package/dist/lib/secrets/reserved-sync.d.ts

@@ -1,11 +1,13 @@
 import { type PushBundleResult } from './push.js';
 import { type DeviceProfile } from '../devices/registry.js';
-import type { DeviceProbe } from '../fleet/types.js';
+import { type SharedAuthStatus } from '../fleet-shared-state.js';
+/** Each import/read-back SSH operation gets this deadline plus the SSH hard-kill grace. */
+export declare const AUTH_SYNC_PUSH_DEADLINE_MS = 20000;
 export interface AuthSyncDevice {
     name: string;
     reachable: boolean;
     pinned: boolean;
-    remoteHasAuth: boolean;
+    remoteAuth: SharedAuthStatus | 'unknown';
 }
 export type AuthSyncPlanItem = {
     action: 'push';
@@ -15,8 +17,10 @@ export type AuthSyncPlanItem = {
     device: string;
     reason: string;
 };
-export declare function planAuthBundlePush(localAuthOk: boolean, devices: AuthSyncDevice[]): AuthSyncPlanItem[];
+export declare function planAuthBundlePush(localAuthOk: boolean, localIsPublisher: boolean, devices: AuthSyncDevice[]): AuthSyncPlanItem[];
 export interface AuthSyncResult {
+    publisher: string | null;
+    stateChanged: boolean;
     pushed: string[];
     skipped: Array<{
         device: string;
@@ -27,10 +31,6 @@ export interface AuthSyncResult {
         message: string;
     }>;
 }
-export interface AuthSyncProbe {
-    reachable: boolean;
-    remoteHasAuth: boolean;
-}
 export interface AuthSyncDeps {
     inspectLocal?: () => {
         exists: boolean;
@@ -38,28 +38,29 @@ export interface AuthSyncDeps {
     };
     listDevices?: () => DeviceProfile[];
     localName?: string;
+    userAgentsDir?: string;
     isPinned?: (name: string) => boolean;
-    /**
-     * Per-device reachability + auth presence. Default: `probeDevice({ withSecrets: true })`
-     * — the same remote-presence probe `fleet apply` uses in `decideSecretPush`.
-     */
-    probe?: (device: DeviceProfile) => AuthSyncProbe;
-    push?: (bundle: string, host: string) => PushBundleResult;
+    push?: (bundle: string, host: string) => Promise<PushBundleResult>;
     sshTarget?: (device: DeviceProfile) => string;
 }
+export interface PublishAuthVerdictOptions {
+    inspectLocal?: () => {
+        exists: boolean;
+        ok: boolean;
+    };
+    localName?: string;
+    userAgentsDir?: string;
+}
+export interface PublishAuthVerdictResult {
+    device: string;
+    status: SharedAuthStatus;
+    changed: boolean;
+    error: string | null;
+}
+/** Publish only safe readiness metadata; useful immediately before a repo push. */
+export declare function publishReservedAuthVerdict(options?: PublishAuthVerdictOptions): PublishAuthVerdictResult;
 /**
- * Map a `fleet apply` device probe onto the auth-sync skip/push inputs.
- *
- * Presence is an own-property check on `remoteBundles` (same gate as
- * `decideSecretPush`): a missing listing, a parse failure, or a prototype
- * name must all mean "not present, so push" — never "present, so skip".
- */
-export declare function authPresenceFromProbe(probe: DeviceProbe): AuthSyncProbe;
-/** Production default: live SSH probe of reachability + `secrets list --json`. */
-export declare function defaultAuthSyncProbe(device: DeviceProfile): AuthSyncProbe;
-/**
- * Push the local file-backed `auth` bundle to every pinned registered device
- * that does not already have it. No-op when the local bundle is missing or on
- * the wrong backend (doctor flags that separately).
+ * Publish local readiness, elect one ready source, then asynchronously provision
+ * only peers whose shared verdict says the bundle is missing.
  */
-export declare function syncReservedAuthBundle(deps?: AuthSyncDeps): AuthSyncResult;
+export declare function syncReservedAuthBundle(deps?: AuthSyncDeps): Promise<AuthSyncResult>;