@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/lib/devices/known-hosts.d.ts

@@ -0,0 +1,62 @@
+/** Path to the CLI-managed known_hosts store (created lazily, mode 0600). */
+export declare function managedKnownHostsPath(): string;
+/** Ensure the parent directory of the managed store exists (mode 0700). */
+export declare function ensureManagedKnownHostsDir(file?: string): void;
+/** Read the managed store, or '' when it does not exist yet. */
+export declare function readManagedKnownHosts(file?: string): string;
+/**
+ * True if `host` has at least one pinned key line in `content`. Pure (content
+ * in) so the match logic is unit-testable without touching disk. Matching is
+ * case-insensitive on the hostname, as OpenSSH does.
+ */
+export declare function isHostPinnedIn(content: string, host: string): boolean;
+/** True if `host` is pinned in the managed store on disk. */
+export declare function isHostPinned(host: string, file?: string): boolean;
+/**
+ * The host-key-checking ssh options for a connection.
+ *
+ * Always points `UserKnownHostsFile` at the managed store so learned and pinned
+ * keys live in exactly one CLI-owned file. `StrictHostKeyChecking` is `yes` once
+ * the host is pinned (a key swap is refused) and `accept-new` before that
+ * (genuine first enrollment learns the key into the managed store, which pins it
+ * for every subsequent connect). Pure given `pinned`, so the policy is testable.
+ */
+export declare function hostKeyCheckingOpts(pinned: boolean, file?: string): string[];
+/**
+ * The key lines in `scanned` (ssh-keyscan output) not already present in
+ * `existing`. Comments and blank lines are dropped; whitespace is normalized so
+ * a re-scan of an already-pinned key is a no-op. Pure, so the idempotent-append
+ * contract is unit-testable without spawning ssh-keyscan.
+ */
+export declare function newKnownHostsLines(existing: string, scanned: string): string[];
+export interface PinResult {
+    /** True if the host is pinned in the managed store after this call. */
+    pinned: boolean;
+    /** How many new key lines were appended. */
+    added: number;
+}
+/**
+ * Merge `ssh-keyscan` output for `host` into the managed store at `file`,
+ * idempotently, and report whether `host` is pinned afterward. Split out from
+ * {@link pinHostKey} so the store-write half — the part that decides a scanned
+ * key now counts as pinned — is unit-testable with real keyscan text and no
+ * network (the spawn stays in `pinHostKey`).
+ */
+export declare function recordScannedKeys(host: string, scanned: string, file?: string): PinResult;
+/**
+ * `ssh-keyscan` a host at a trusted moment and append any new key lines to the
+ * managed store, idempotently. This is the explicit pin path; the implicit one
+ * is a normal `accept-new` connection whose learned key lands in the same store.
+ * Returns whether the host is pinned afterward.
+ *
+ * Host-name-agnostic: it scans whatever address it is handed, so it also pins a
+ * host `agents ssh` can't reach — notably a bare `~/.ssh/config` `Host` alias,
+ * which is not a registered device. The `--copy-creds` gate (commands/exec.ts)
+ * calls this for exactly that case so the credential copy is usable for
+ * ssh-config-alias hosts (RUSH-1767).
+ */
+export declare function pinHostKey(host: string, opts?: {
+    file?: string;
+    timeoutMs?: number;
+    port?: number;
+}): PinResult;

package/dist/lib/devices/known-hosts.js

@@ -0,0 +1,137 @@
+/**
+ * Managed known_hosts pinning for the device fleet (RUSH-1767).
+ *
+ * The shared SSH baseline uses `StrictHostKeyChecking=accept-new`
+ * (trust-on-first-use): it silently accepts whatever key answers on the FIRST
+ * connect, so a machine-in-the-middle present in that window is trusted forever
+ * and never re-checked. This module gives the CLI its own known_hosts store,
+ * kept apart from the user's `~/.ssh/known_hosts`, so a device's host key can be
+ * *pinned*: once a key is recorded here, connections verify against it with
+ * `StrictHostKeyChecking=yes`, so a later key swap is refused instead of
+ * silently re-accepted.
+ *
+ * The learn-then-pin flow: the first `agents ssh`/fleet connection to a host is
+ * still `accept-new`, but it writes the learned key into THIS store, which pins
+ * it for every subsequent connect. Credential copies (`run --host --copy-creds`)
+ * refuse to run against a host that isn't pinned here — see
+ * `commands/exec.ts` — so tokens never ride an unverified first connect.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { getCacheDir } from '../state.js';
+import { assertValidSshTarget } from '../ssh-exec.js';
+import { parseKnownHosts } from '../hosts/ssh-config.js';
+/** Path to the CLI-managed known_hosts store (created lazily, mode 0600). */
+export function managedKnownHostsPath() {
+    return path.join(getCacheDir(), 'devices', 'known_hosts');
+}
+/** Ensure the parent directory of the managed store exists (mode 0700). */
+export function ensureManagedKnownHostsDir(file = managedKnownHostsPath()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+}
+/** Read the managed store, or '' when it does not exist yet. */
+export function readManagedKnownHosts(file = managedKnownHostsPath()) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * True if `host` has at least one pinned key line in `content`. Pure (content
+ * in) so the match logic is unit-testable without touching disk. Matching is
+ * case-insensitive on the hostname, as OpenSSH does.
+ */
+export function isHostPinnedIn(content, host) {
+    const needle = host.trim().toLowerCase();
+    if (!needle)
+        return false;
+    return parseKnownHosts(content).some((h) => h.toLowerCase() === needle);
+}
+/** True if `host` is pinned in the managed store on disk. */
+export function isHostPinned(host, file = managedKnownHostsPath()) {
+    return isHostPinnedIn(readManagedKnownHosts(file), host);
+}
+/**
+ * The host-key-checking ssh options for a connection.
+ *
+ * Always points `UserKnownHostsFile` at the managed store so learned and pinned
+ * keys live in exactly one CLI-owned file. `StrictHostKeyChecking` is `yes` once
+ * the host is pinned (a key swap is refused) and `accept-new` before that
+ * (genuine first enrollment learns the key into the managed store, which pins it
+ * for every subsequent connect). Pure given `pinned`, so the policy is testable.
+ */
+export function hostKeyCheckingOpts(pinned, file = managedKnownHostsPath()) {
+    return [
+        '-o', `UserKnownHostsFile=${file}`,
+        '-o', `StrictHostKeyChecking=${pinned ? 'yes' : 'accept-new'}`,
+    ];
+}
+/**
+ * The key lines in `scanned` (ssh-keyscan output) not already present in
+ * `existing`. Comments and blank lines are dropped; whitespace is normalized so
+ * a re-scan of an already-pinned key is a no-op. Pure, so the idempotent-append
+ * contract is unit-testable without spawning ssh-keyscan.
+ */
+export function newKnownHostsLines(existing, scanned) {
+    const have = new Set(existing.split('\n').map((l) => l.trim()).filter(Boolean));
+    const seen = new Set();
+    const fresh = [];
+    for (const raw of scanned.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#') || have.has(line) || seen.has(line))
+            continue;
+        seen.add(line);
+        fresh.push(line);
+    }
+    return fresh;
+}
+/**
+ * Merge `ssh-keyscan` output for `host` into the managed store at `file`,
+ * idempotently, and report whether `host` is pinned afterward. Split out from
+ * {@link pinHostKey} so the store-write half — the part that decides a scanned
+ * key now counts as pinned — is unit-testable with real keyscan text and no
+ * network (the spawn stays in `pinHostKey`).
+ */
+export function recordScannedKeys(host, scanned, file = managedKnownHostsPath()) {
+    ensureManagedKnownHostsDir(file);
+    const existing = readManagedKnownHosts(file);
+    const fresh = newKnownHostsLines(existing, scanned);
+    if (fresh.length > 0) {
+        const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+        fs.appendFileSync(file, prefix + fresh.join('\n') + '\n', { mode: 0o600 });
+    }
+    return { pinned: isHostPinned(host, file), added: fresh.length };
+}
+/**
+ * `ssh-keyscan` a host at a trusted moment and append any new key lines to the
+ * managed store, idempotently. This is the explicit pin path; the implicit one
+ * is a normal `accept-new` connection whose learned key lands in the same store.
+ * Returns whether the host is pinned afterward.
+ *
+ * Host-name-agnostic: it scans whatever address it is handed, so it also pins a
+ * host `agents ssh` can't reach — notably a bare `~/.ssh/config` `Host` alias,
+ * which is not a registered device. The `--copy-creds` gate (commands/exec.ts)
+ * calls this for exactly that case so the credential copy is usable for
+ * ssh-config-alias hosts (RUSH-1767).
+ */
+export function pinHostKey(host, opts = {}) {
+    // Same injection guard as sshExec: a host starting with `-` (or carrying shell
+    // metacharacters) must never reach ssh-keyscan as a bare argv where it could
+    // be parsed as a flag.
+    assertValidSshTarget(host);
+    const file = opts.file ?? managedKnownHostsPath();
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    ensureManagedKnownHostsDir(file);
+    const args = ['-T', String(Math.max(1, Math.ceil(timeoutMs / 1000)))];
+    if (opts.port)
+        args.push('-p', String(opts.port));
+    args.push(host);
+    const res = spawnSync('ssh-keyscan', args, { encoding: 'utf-8', timeout: timeoutMs });
+    if (res.status !== 0 || !res.stdout) {
+        return { pinned: isHostPinned(host, file), added: 0 };
+    }
+    return recordScannedKeys(host, res.stdout, file);
+}

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;