@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/run-trace-sync.js

@@ -0,0 +1,77 @@
+/**
+ * Auto-sync this device's just-finished session trace when a local, headless
+ * `agents run` exits (PHNX-3628).
+ *
+ * Why exit-armed + spawn, exactly like `run-notify`: the sync reads this
+ * device's `sessions.db` and PUTs redacted shards over the network — async work
+ * that CANNOT run inside a `process.on('exit')` handler (Node runs no more
+ * microtasks after exit). So, mirroring `notifyDesktop`, on exit we SPAWN a
+ * detached `agents traces sync` and unref it; it finishes after the parent is
+ * gone, and the run itself returns immediately instead of waiting on the PUTs.
+ *
+ * The upload is incremental by construction (`syncTraces` de-dups by the
+ * `traces-sync.json` mtime watermark), so the spawned sync pushes essentially
+ * just the session that finished, not the whole history.
+ *
+ * Default policy: fire ONLY when the user has ALREADY opted into the traces
+ * store — i.e. they are signed in AND have run `agents traces sync` at least
+ * once (`hasSyncedBefore`). A user who never synced is never touched. Opt out
+ * of a given run with `--no-trace-sync` or `AGENTS_NO_TRACE_SYNC=1`.
+ *
+ * Local runs only: a run placed on another machine (`--device`/`--on`/
+ * `--computer`/`--where device:`, `--lease`, `--box`, or `--cloud`) has its
+ * trajectory on the REMOTE box, not this device's `sessions.db`, so arming here
+ * would upload nothing useful — the remote box runs its own exit sync. The
+ * caller gates every remote-placement signal out before arming (it reuses the
+ * file's own `hostTargetGiven` predicate plus `--lease`/`--box`; `--cloud`
+ * returns earlier).
+ */
+import { spawn } from 'child_process';
+import { getCliLaunch } from './cli-entry.js';
+import { readSession } from './identity/client.js';
+import { hasSyncedBefore } from './traces/sync.js';
+/**
+ * The policy gate, pure and unit-testable. `disabled` is the resolved
+ * `--no-trace-sync` (commander maps it to `traceSync === false`).
+ */
+export function shouldAutoSyncTraces(disabled) {
+    if (disabled)
+        return false;
+    if (process.env.AGENTS_NO_TRACE_SYNC === '1')
+        return false;
+    if (!readSession())
+        return false; // not signed in → nothing to authenticate an upload
+    if (!hasSyncedBefore())
+        return false; // never opted into the traces store
+    return true;
+}
+/**
+ * Arm a fire-and-forget `agents traces sync` for when this process exits.
+ * No-op unless {@link shouldAutoSyncTraces} passes. Best-effort by
+ * construction: a missing binary or a stalled child never affects the run.
+ */
+export function armRunFinishTraceSync(opts = {}) {
+    if (!shouldAutoSyncTraces(!!opts.disabled))
+        return;
+    process.on('exit', () => {
+        try {
+            // Re-invoke this CLI through getCliLaunch, NOT a hand-rolled
+            // [process.execPath, process.argv[1], …] — under the compiled standalone
+            // binary argv[1] is the bun virtual entry (/$bunfs/root/agents), which
+            // would become a bogus subcommand and silently no-op the whole feature
+            // (cli-entry.ts). The spawned `traces sync` is a fresh process with its
+            // own event loop, so its own per-request network timeouts (syncTraces)
+            // bound it — a watchdog here could never fire anyway (Node runs no loop
+            // after an 'exit' handler returns), so we do not pretend to add one.
+            const { command, args } = getCliLaunch(['traces', 'sync']);
+            const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+            // A child that never starts (ENOENT) emits an async 'error'; without a
+            // listener Node re-throws it as uncaught. Swallow — this is best-effort.
+            child.on('error', () => { });
+            child.unref();
+        }
+        catch {
+            // A synchronous spawn failure must never change the run's exit outcome.
+        }
+    });
+}

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>;