@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/devices/fleet.js

@@ -8,12 +8,14 @@
  * the remaining devices.
  */
 import { spawnSync } from 'child_process';
+import { isControlDevice } from './registry.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
 /**
  * Classify each registered device for a fleet operation.
  *
+ * - Control-only device (a cockpit, e.g. a paired iPhone) → skip `control`
  * - Tailscale-offline → skip `offline`
  * - No address → skip `no-address`
  * - Everything else is a target (including this machine, reached over ssh when
@@ -23,6 +25,11 @@ export function planFleetTargets(reg) {
     const names = Object.keys(reg).sort();
     return names.map((name) => {
         const device = reg[name];
+        // A control device drives the fleet but never runs agents — never a target
+        // for update/run/stats, whatever its platform reads as.
+        if (isControlDevice(device)) {
+            return { device, skip: 'control' };
+        }
         if (device.tailscale && !device.tailscale.online) {
             return { device, skip: 'offline' };
         }
@@ -42,6 +49,8 @@ export function skipLabel(reason) {
             return 'offline';
         case 'no-address':
             return 'no address';
+        case 'control':
+            return 'control device';
     }
 }
 /**

package/dist/lib/devices/registry.d.ts

@@ -1,5 +1,13 @@
 /** Operating-system family of a device, used to pick the remote shell. */
 export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
+/**
+ * What a device is *for*. A `worker` (the default) can run agents — it's dialed
+ * over SSH for sessions and eligible for run/team placement. A `control` device
+ * is a cockpit that drives the fleet but never executes agents itself (an
+ * iPhone/iPad running the companion app): it appears in the fleet but is never
+ * dialed for SSH nor scheduled work. Absent `role` means `worker`.
+ */
+export type DeviceRole = 'worker' | 'control';
 /** Remote shell dialect derived from the platform. */
 export type DeviceShell = 'powershell' | 'posix';
 /** How `agents ssh` authenticates to a device. Both are first-class, fully
@@ -41,9 +49,15 @@ export interface DeviceProfile {
     address: DeviceAddress;
     auth: DeviceAuth;
     tailscale?: DeviceTailscale;
+    /** What the device is for. Absent means `worker` (see {@link DeviceRole}). */
+    role?: DeviceRole;
     createdAt: string;
     updatedAt: string;
 }
+/** A device's effective role, defaulting to `worker` when unset. */
+export declare function deviceRole(d: DeviceProfile): DeviceRole;
+/** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
+export declare function isControlDevice(d: DeviceProfile): boolean;
 /** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
 /** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
@@ -74,6 +88,7 @@ export interface DeviceInput {
     address?: DeviceAddress;
     auth?: DeviceAuth;
     tailscale?: DeviceTailscale;
+    role?: DeviceRole;
 }
 /**
  * Create the device if absent, otherwise merge the supplied fields into the

package/dist/lib/devices/registry.js

@@ -19,6 +19,14 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+/** A device's effective role, defaulting to `worker` when unset. */
+export function deviceRole(d) {
+    return d.role ?? 'worker';
+}
+/** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
+export function isControlDevice(d) {
+    return deviceRole(d) === 'control';
+}
 function registryPath() {
     return getDevicesRegistryPath();
 }
@@ -170,6 +178,7 @@ export async function upsertDevice(name, input) {
             address: input.address ?? prev?.address ?? { via: 'manual' },
             auth: input.auth ?? prev?.auth ?? { method: 'key' },
             tailscale: input.tailscale ?? prev?.tailscale,
+            role: input.role ?? prev?.role,
             createdAt: prev?.createdAt ?? now,
             updatedAt: now,
         };

package/dist/lib/exec.d.ts

@@ -120,6 +120,15 @@ export interface ExecOptions {
     mcpConfigPath?: string;
     /** Raw args captured after `--` on the command line, forwarded verbatim to the underlying agent CLI. */
     passthroughArgs?: string[];
+    /**
+     * Tee-and-tail the child's stdout even when no budget cap is active, so the
+     * caller can scan it for rate/usage-limit messages. Claude prints billing
+     * refusals ("monthly spend limit", "out of usage credits") to STDOUT, not
+     * stderr — a fallback chain that only inspects stderr never cascades on
+     * them. Set by runWithFallback for every chain entry; harmless elsewhere
+     * (output is mirrored to the parent's stdout exactly like stdio:'inherit').
+     */
+    captureStdoutTail?: boolean;
     /**
      * Escape hatch for the interactive tmux spawn-wrap (see shouldWrapInTmux):
      * when true, spawn the agent directly instead of inside a shared-socket tmux
@@ -150,7 +159,7 @@ export declare function resolveInteractive(options: Pick<ExecOptions, 'interacti
  * @param piped        true when the parent's stdout is NOT a TTY (output piped)
  * @param capsActive   true when a budget watcher is attached (caps configured)
  */
-export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean): boolean;
+export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean, captureTail?: boolean): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**
@@ -274,8 +283,16 @@ export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
  *     `#{pane_pid}`, clean signal delivery on detach/kill).
  * Keys are filtered to valid identifiers so exported shell functions
  * (`BASH_FUNC_*%%`) can't make `env` choke.
+ *
+ * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
+ * the KEY names. The env map here carries resolved secrets bundles (options.env),
+ * so the real string would embed secret VALUES — which get persisted verbatim
+ * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
+ * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
-export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv): string;
+export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
+    redactEnvValues?: boolean;
+}): string;
 /**
  * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
  * (right-stripping each). Used by runInTmux to recap a fast-failed agent's

package/dist/lib/exec.js

@@ -147,12 +147,13 @@ export function resolveInteractive(options) {
  * @param piped        true when the parent's stdout is NOT a TTY (output piped)
  * @param capsActive   true when a budget watcher is attached (caps configured)
  */
-export function shouldTapStdout(interactive, piped, capsActive) {
+export function shouldTapStdout(interactive, piped, capsActive, captureTail = false) {
     if (interactive)
         return false;
     // Always pipe when the caller pipes us downstream (preserve composability),
-    // OR when caps are active so the watcher can read the stream at a TTY.
-    return piped || capsActive;
+    // when caps are active so the watcher can read the stream at a TTY, or when
+    // a fallback chain needs a stdout tail for rate-limit detection.
+    return piped || capsActive || captureTail;
 }
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -866,11 +867,17 @@ export function shouldWrapInTmux(ctx) {
  *     `#{pane_pid}`, clean signal delivery on detach/kill).
  * Keys are filtered to valid identifiers so exported shell functions
  * (`BASH_FUNC_*%%`) can't make `env` choke.
+ *
+ * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
+ * the KEY names. The env map here carries resolved secrets bundles (options.env),
+ * so the real string would embed secret VALUES — which get persisted verbatim
+ * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
+ * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
-export function buildTmuxAgentCommand(executable, args, env) {
+export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const envPrefix = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
-        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .map(([k, v]) => `${k}=${opts.redactEnvValues ? '<redacted>' : shellQuote(String(v))}`)
         .join(' ');
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
@@ -917,11 +924,16 @@ async function runInTmux(options, executable, args) {
     const cwd = options.cwd || process.cwd();
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
-    const cmd = buildTmuxAgentCommand(executable, args, buildExecEnv(options));
+    const execEnv = buildExecEnv(options);
+    // Launch with the real env (secret VALUES materialized into the pane); persist
+    // only a value-redacted copy in SessionMeta.cmd so resolved secrets never hit
+    // disk via the informational cmd field (RUSH-1758).
+    const cmd = buildTmuxAgentCommand(executable, args, execEnv);
+    const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
     if (options.sessionId)
         labels.sessionId = options.sessionId;
-    const meta = await createSession({ name, cmd, cwd, socket, source: 'cli', labels });
+    const meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
     const pane = meta.pane;
     if (pane) {
         // When the AGENT pane dies, detach the client (don't kill) so the session
@@ -990,7 +1002,7 @@ async function runInTmux(options, executable, args) {
             await surfacePaneFailure(before.status, `${options.agent} exited before it could start`);
         }
         await killSession(name, socket).catch(() => { });
-        return { exitCode: before.status ?? 0, stderr: '' };
+        return { exitCode: before.status ?? 0, stderr: '', stdout: '' };
     }
     await attachTmux({ socket, args: ['attach-session', '-t', name] });
     const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
@@ -1003,10 +1015,10 @@ async function runInTmux(options, executable, args) {
             await surfacePaneFailure(after.status, `${options.agent} exited`);
         }
         await killSession(name, socket).catch(() => { });
-        return { exitCode: after.status ?? 0, stderr: '' };
+        return { exitCode: after.status ?? 0, stderr: '', stdout: '' };
     }
     // Pane still alive → the user detached; keep the session for `agents focus`.
-    return { exitCode: 0, stderr: '' };
+    return { exitCode: 0, stderr: '', stdout: '' };
 }
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
@@ -1092,7 +1104,7 @@ async function spawnAgent(options) {
         // PIPE (and later tee) stdout whenever the live budget watcher must read it
         // — for ALL non-interactive runs when caps are active, regardless of TTY.
         // See shouldTapStdout() for the rationale (FIX 3, issue #346).
-        const tapStdout = shouldTapStdout(interactive, piped, watcherState !== null);
+        const tapStdout = shouldTapStdout(interactive, piped, watcherState !== null, options.captureStdoutTail);
         const stdio = interactive
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', tapStdout ? 'pipe' : 'inherit', 'pipe'];
@@ -1127,10 +1139,17 @@ async function spawnAgent(options) {
         timer.mark('startup');
         let budgetKilled = false;
         let budgetKillTimer;
+        let stdoutTail = '';
+        const STDOUT_TAIL_CAP = 16 * 1024;
         if (!interactive && tapStdout && child.stdout) {
             // TEE the child's stdout back to the parent's so the user still sees
             // output (mirrors stdio:'inherit') while we tap the same stream for usage.
             child.stdout.pipe(process.stdout);
+            // Keep a rolling TAIL (billing refusals arrive at the very end of a run)
+            // for the fallback chain's rate-limit scan.
+            child.stdout.on('data', (chunk) => {
+                stdoutTail = (stdoutTail + chunk.toString('utf-8')).slice(-STDOUT_TAIL_CAP);
+            });
             // Tap the same stream for budget usage events without consuming the pipe
             // (a 'data' listener and .pipe() both receive every chunk). Kill on breach.
             if (watcherState) {
@@ -1200,7 +1219,7 @@ async function spawnAgent(options) {
             // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
-            resolve({ exitCode, stderr: stderrBuffer });
+            resolve({ exitCode, stderr: stderrBuffer, stdout: stdoutTail });
         });
     });
 }
@@ -1282,6 +1301,12 @@ export const RATE_LIMIT_PATTERNS = [
     /too many requests/i,
     /api[\s_-]?overloaded/i,
     /\boverloaded\b/i,
+    // Claude billing refusals — "You've hit your org's monthly spend limit" and
+    // "You're out of usage credits". Both end the run with exit 1 and are exactly
+    // the condition a fallback chain exists to recover from. Printed to STDOUT,
+    // hence the stdout tail in SpawnResult.
+    /spend[\s-]?limit/i,
+    /out of (?:usage )?credits/i,
 ];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export function detectRateLimit(text) {
@@ -1370,6 +1395,9 @@ export async function runWithFallback(options) {
             prompt,
             env: envOverride ? { ...(options.env ?? {}), ...envOverride } : options.env,
             sessionId: pinnedSessionId ?? (i === 0 ? options.sessionId : undefined),
+            // Claude prints billing refusals (spend limit / out of credits) to
+            // stdout; tail it so the cascade check below can see them.
+            captureStdoutTail: true,
         };
         const label = version ? `${agent}@${version}` : agent;
         const modelSwapNote = sameHostRetry && envOverride
@@ -1397,7 +1425,7 @@ export async function runWithFallback(options) {
         const isLast = i === chain.length - 1;
         if (isLast)
             return result.exitCode;
-        if (!detectRateLimit(result.stderr)) {
+        if (!detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

package/dist/lib/fleet/apply.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
+ * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
+ * the real fleet over SSH and is verified end-to-end against live devices.
+ *
+ * Flow per device: probe → install/upgrade agents-cli → add missing agents →
+ * sync config → propagate login. Every step reuses an existing primitive
+ * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
+ */
+import type { DeviceProfile } from '../devices/registry.js';
+import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
+/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
+export declare function agentIdOf(spec: string): string;
+/** Source-side auth availability, computed once from `snapshotAuth`. */
+export interface SourceAuth {
+    /** Agent ids the source has a readable, propagatable credential file for. */
+    available: Set<string>;
+    /** Agent ids whose source auth is device-bound (macOS keychain). */
+    bound: Set<string>;
+    /** The captured file payloads, keyed by agent. */
+    filesByAgent: Map<string, AuthFilePayload[]>;
+}
+/**
+ * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
+ * the agent has no portable file, the source can't provide it (bound / not
+ * signed in), or the target consumes credentials from its own keychain.
+ */
+export declare function canPushLogin(agent: string, targetPlatform: string | undefined, src: SourceAuth): boolean;
+export interface DiffContext {
+    /** agents-cli version the source is on — the fleet target version. */
+    targetCliVersion: string;
+    sourceAuth: SourceAuth;
+}
+/** Pure: desired vs probed -> per-device diff + flat action list. */
+export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
+/** Probe one device: reachability + agents-cli version + installed agent ids. */
+export declare function probeDevice(device: DeviceProfile): DeviceProbe;
+export interface ApplyStep {
+    kind: FleetAction['kind'];
+    ok: boolean;
+    detail: string;
+}
+export interface DeviceApplyResult {
+    device: string;
+    ok: boolean;
+    steps: ApplyStep[];
+    note?: string;
+}
+export interface ExecContext {
+    targetCliVersion: string;
+    source: string;
+    sourceAuth: SourceAuth;
+    /** Set for a dry run — probe + plan only, execute nothing. */
+    dryRun?: boolean;
+}
+/** Execute one device's planned actions in order. Real SSH — no mocks. */
+export declare function reconcileDevice(row: DeviceDiff, device: DeviceProfile, ctx: ExecContext): DeviceApplyResult;
+/** Run a pool of async tasks with a concurrency cap, preserving input order. */
+export declare function pool<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Reconcile every device row in parallel (capped). */
+export declare function runFleetApply(rows: DeviceDiff[], nameToProfile: Map<string, DeviceProfile>, ctx: ExecContext, concurrency?: number): Promise<DeviceApplyResult[]>;
+/** Default home for source snapshots (overridable in tests). */
+export declare function sourceHome(): string;

package/dist/lib/fleet/apply.js

@@ -0,0 +1,214 @@
+/**
+ * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
+ * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
+ * the real fleet over SSH and is verified end-to-end against live devices.
+ *
+ * Flow per device: probe → install/upgrade agents-cli → add missing agents →
+ * sync config → propagate login. Every step reuses an existing primitive
+ * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
+ */
+import * as os from 'os';
+import { sshTargetFor } from '../devices/connect.js';
+import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
+import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
+import { sshExec } from '../ssh-exec.js';
+import { isPropagatableAgent, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './auth-sync.js';
+/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
+export function agentIdOf(spec) {
+    return spec.split('@')[0].trim();
+}
+/**
+ * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
+ * the agent has no portable file, the source can't provide it (bound / not
+ * signed in), or the target consumes credentials from its own keychain.
+ */
+export function canPushLogin(agent, targetPlatform, src) {
+    if (!isPropagatableAgent(agent))
+        return false;
+    if (src.bound.has(agent))
+        return false;
+    if (targetPlatform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(agent))
+        return false;
+    return src.available.has(agent);
+}
+/** Pure: desired vs probed -> per-device diff + flat action list. */
+export function diffFleet(desired, probes, ctx) {
+    const devices = [];
+    const actions = [];
+    for (const d of desired) {
+        const probe = probes.get(d.device) ?? {
+            device: d.device,
+            reachable: false,
+            installedAgents: [],
+            note: 'not probed',
+        };
+        const rowActions = [];
+        const loginBlocked = [];
+        if (probe.reachable) {
+            // agents-cli presence.
+            if (!probe.cliVersion) {
+                rowActions.push({ device: d.device, kind: 'install-cli', detail: `install agents-cli ${ctx.targetCliVersion}` });
+            }
+            else if (probe.cliVersion !== ctx.targetCliVersion) {
+                rowActions.push({ device: d.device, kind: 'upgrade-cli', detail: `agents-cli ${probe.cliVersion} -> ${ctx.targetCliVersion}` });
+            }
+            // agents.
+            for (const spec of d.agents) {
+                const id = agentIdOf(spec);
+                if (!probe.installedAgents.includes(id)) {
+                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, detail: `install ${spec}` });
+                }
+            }
+            // config.
+            if (d.sync.length > 0) {
+                rowActions.push({ device: d.device, kind: 'sync-config', detail: `sync config (${d.sync.join(', ')})` });
+            }
+            // login.
+            if (d.login === 'sync') {
+                for (const spec of d.agents) {
+                    const id = agentIdOf(spec);
+                    if (canPushLogin(id, probe.platform, ctx.sourceAuth)) {
+                        rowActions.push({ device: d.device, kind: 'push-login', agent: id, detail: `propagate ${id} login` });
+                    }
+                    else if (isPropagatableAgent(id) &&
+                        (ctx.sourceAuth.bound.has(id) || (probe.platform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(id)))) {
+                        // A login-propagation candidate we still can't push: the source token
+                        // is keychain-bound (unextractable), or the macOS target consumes its
+                        // own keychain. Surface those as manual — don't fake. Agents that were
+                        // never propagation candidates (no portable file), or a source that
+                        // simply isn't signed in, are silently skipped the same on every OS.
+                        loginBlocked.push(id);
+                        rowActions.push({ device: d.device, kind: 'needs-login', agent: id, detail: `${id} needs a manual login` });
+                    }
+                }
+            }
+        }
+        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked });
+        actions.push(...rowActions);
+    }
+    return { devices, actions };
+}
+// ---- execution (real SSH; verified end-to-end, not unit-mocked) ----
+function osHint(platform) {
+    return platform === 'windows' ? 'windows' : undefined;
+}
+/** POSIX login shells often miss the shims dir; inject it (mirrors doctor). */
+function remoteEnv(platform) {
+    return platform === 'windows' ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
+}
+/** Probe one device: reachability + agents-cli version + installed agent ids. */
+export function probeDevice(device) {
+    let target;
+    try {
+        target = sshTargetFor(device);
+    }
+    catch (e) {
+        return { device: device.name, reachable: false, platform: device.platform, installedAgents: [], note: e.message };
+    }
+    const hint = osHint(device.platform);
+    const ready = readyProbe(target, hint);
+    if (!ready.reachable) {
+        return { device: device.name, reachable: false, platform: device.platform, installedAgents: [], note: 'unreachable' };
+    }
+    let installed = [];
+    const remoteCmd = buildRemoteAgentsInvocation(['teams', 'doctor', '--json'], undefined, hint, remoteEnv(device.platform));
+    const res = sshExec(target, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code === 0) {
+        try {
+            const map = JSON.parse(res.stdout);
+            installed = Object.entries(map).filter(([, e]) => e?.installed).map(([k]) => k);
+        }
+        catch {
+            /* agents-cli present but doctor output unparsable — treat as no agents */
+        }
+    }
+    return {
+        device: device.name,
+        reachable: true,
+        platform: device.platform,
+        cliVersion: ready.version ?? undefined,
+        installedAgents: installed,
+    };
+}
+/** Execute one device's planned actions in order. Real SSH — no mocks. */
+export function reconcileDevice(row, device, ctx) {
+    if (!row.probe.reachable) {
+        return { device: row.device, ok: false, steps: [], note: row.probe.note ?? 'unreachable' };
+    }
+    const steps = [];
+    let target;
+    try {
+        target = sshTargetFor(device);
+    }
+    catch (e) {
+        return { device: row.device, ok: false, steps: [], note: e.message };
+    }
+    const hint = osHint(device.platform);
+    const env = remoteEnv(device.platform);
+    let ok = true;
+    const sshAgents = (args, input) => sshExec(target, buildRemoteAgentsInvocation(args, undefined, hint, env), { timeoutMs: 300000, multiplex: true, input });
+    // 1. agents-cli install/upgrade.
+    const cliAction = row.actions.find((a) => a.kind === 'install-cli' || a.kind === 'upgrade-cli');
+    if (cliAction) {
+        const r = bootstrapAgentsCli(target, ctx.targetCliVersion, hint);
+        steps.push({ kind: cliAction.kind, ok: r.ok, detail: cliAction.detail });
+        ok = ok && r.ok;
+    }
+    // 2. agents.
+    for (const a of row.actions.filter((x) => x.kind === 'add-agent')) {
+        const spec = a.detail.replace(/^install\s+/, '');
+        const r = sshAgents(['add', spec, '--yes']);
+        steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
+        ok = ok && r.code === 0;
+    }
+    // 3. config sync.
+    if (row.actions.some((a) => a.kind === 'sync-config')) {
+        const r = sshAgents(['sync']);
+        steps.push({ kind: 'sync-config', ok: r.code === 0, detail: `sync config` });
+        ok = ok && r.code === 0;
+    }
+    // 4. login propagation — one bundle for all pushable agents on this device.
+    const pushAgents = [...new Set(row.actions.filter((a) => a.kind === 'push-login').map((a) => a.agent))];
+    if (pushAgents.length > 0) {
+        const files = [];
+        for (const agent of pushAgents)
+            files.push(...(ctx.sourceAuth.filesByAgent.get(agent) ?? []));
+        const bundle = buildAuthBundle(ctx.source, files);
+        const r = sshAgents(['apply', '--recv-auth'], JSON.stringify(bundle));
+        steps.push({ kind: 'push-login', ok: r.code === 0, detail: `propagate login: ${pushAgents.join(', ')}` });
+        ok = ok && r.code === 0;
+    }
+    // Surface blocked logins as (non-fatal) informational steps.
+    for (const blocked of row.loginBlocked) {
+        steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });
+    }
+    return { device: row.device, ok, steps };
+}
+/** Run a pool of async tasks with a concurrency cap, preserving input order. */
+export async function pool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/** Reconcile every device row in parallel (capped). */
+export async function runFleetApply(rows, nameToProfile, ctx, concurrency = 6) {
+    return pool(rows, concurrency, async (row) => {
+        const profile = nameToProfile.get(row.device);
+        if (!profile)
+            return { device: row.device, ok: false, steps: [], note: 'no device profile' };
+        return reconcileDevice(row, profile, ctx);
+    });
+}
+/** Default home for source snapshots (overridable in tests). */
+export function sourceHome() {
+    return os.homedir();
+}

package/dist/lib/fleet/auth-sync.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Login/token propagation — the "one login instead of ~48 OAuth flows" core of
+ * `agents apply`.
+ *
+ * A source machine that is already signed in to a set of harnesses has portable
+ * credential files on disk (verified per-agent locations below). `snapshotAuth`
+ * captures those; `materializeAuth` writes them into the corresponding paths on
+ * a target device. Transport is the caller's job — `apply` streams the bundle
+ * over the existing (encrypted, authenticated) SSH channel via `sshExec`'s
+ * stdin `input`, so no app-layer crypto is layered on top of SSH here.
+ *
+ * Honest boundary: on macOS, claude and antigravity keep their tokens in the
+ * login keychain, ACL-bound to the harness process — unreadable by us. Those are
+ * classified `bound` and surfaced for a one-time manual login, never faked.
+ */
+import type { AuthFilePayload, AuthBundle, AuthSnapshotResult } from './types.js';
+/** A portable credential file location, relative to $HOME. */
+interface AuthFileSpec {
+    rel: string;
+    mode: number;
+}
+/**
+ * Verified portable auth-file locations per agent (home-relative). Sourced from
+ * live inspection of a Linux fleet box + the agent registry. Agents absent here
+ * have no portable credential file we can propagate.
+ */
+export declare const FLEET_AUTH_FILES: Record<string, AuthFileSpec[]>;
+/** Agents whose macOS credentials live in the ACL-bound login keychain. */
+export declare const KEYCHAIN_BOUND_ON_MAC: ReadonlySet<string>;
+/** Which agents `apply` can propagate auth for at all. */
+export declare function isPropagatableAgent(agent: string): boolean;
+export interface SnapshotOptions {
+    /** Home directory to read credential files from. */
+    home: string;
+    /** Platform of the source machine (`process.platform`). */
+    platform: NodeJS.Platform;
+}
+/**
+ * Capture portable credential files for the given agents from a source home.
+ * Returns the readable file payloads plus the list of agents whose auth is
+ * device-bound (macOS keychain) and therefore cannot be captured. Agents that
+ * are simply not signed in (no file on disk) are silently omitted — nothing to
+ * propagate, not an error.
+ */
+export declare function snapshotAuth(agents: string[], opts: SnapshotOptions): AuthSnapshotResult;
+/** Assemble the plaintext bundle shipped to a target. */
+export declare function buildAuthBundle(source: string, files: AuthFilePayload[]): AuthBundle;
+export interface MaterializeOptions {
+    /** Home directory to write credential files into. */
+    home: string;
+}
+export interface MaterializeResult {
+    /** Agent ids that received at least one file. */
+    written: string[];
+    /** `rel: reason` for any file that failed. */
+    errors: string[];
+}
+/**
+ * Write a captured auth bundle into a target home. Parent dirs are created; the
+ * captured POSIX mode is restored (0600 for credentials). Writing through an
+ * existing symlink lands in the agent's active version home, which is exactly
+ * what per-version credential carry-forward expects.
+ */
+export declare function materializeAuth(bundle: AuthBundle, opts: MaterializeOptions): MaterializeResult;
+/** Parse + validate a bundle received on stdin (the remote `--_recv-auth` path). */
+export declare function parseAuthBundle(raw: string): AuthBundle;
+export {};