@phnx-labs/agents-cli 1.20.70 → 1.20.71

package/dist/commands/ssh.js

@@ -18,6 +18,7 @@ import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { addControlToken } from '../lib/serve/token.js';
 import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
@@ -27,7 +28,7 @@ import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-targe
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -244,10 +245,10 @@ async function probeRemoteHealth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const versionCmd = buildRemoteAgentsInvocation(['--version'], undefined, isWin ? 'windows' : undefined, env);
-    const versionRes = await sshExecAsync(target.name, versionCmd, { timeoutMs: 15000, multiplex: true });
+    const versionRes = await sshExecAsync(target.dialTarget, versionCmd, { timeoutMs: 15000, multiplex: true });
     const version = versionRes.code === 0 ? versionRes.stdout.trim().split(/\s+/)[0] || null : null;
     const doctorCmd = buildRemoteAgentsInvocation(['doctor', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const doctorRes = await sshExecAsync(target.name, doctorCmd, { timeoutMs: 30000, multiplex: true });
+    const doctorRes = await sshExecAsync(target.dialTarget, doctorCmd, { timeoutMs: 30000, multiplex: true });
     if (doctorRes.code !== 0) {
         throw new Error(doctorRes.timedOut ? 'timed out' : (doctorRes.stderr.trim() || `exit ${doctorRes.code ?? 'unknown'}`));
     }
@@ -280,6 +281,20 @@ async function runFleetStatus(opts) {
         name: t.device.name,
         platform: t.device.platform,
         skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
+        // Fail fast: the stats probe already tried this box with the same
+        // (registry) address. If it came back unreachable, don't spend another
+        // 15s+30s on version+doctor — skip straight to an unreachable row so one
+        // genuinely-offline device can't stall the whole matrix.
+        //
+        // Only trust this on a FRESH probe (`--refresh`/`--live`). loadFleetStats
+        // is cache-first (daemon-warmed ~3min), so a box that came back online
+        // since the last warm would otherwise be skipped to "unreachable" without
+        // a live attempt — a false negative. On a default run we still do the live
+        // probe (fast now that it dials the registry address).
+        ...(forceRefresh && statsMap.get(t.device.name)?.reachable === false && !t.skip
+            ? { skip: 'unreachable' }
+            : {}),
     }));
     const remote = await fanOutDevices(remoteTargets, probeRemoteHealth);
     for (const result of remote) {
@@ -333,7 +348,7 @@ async function probeRemoteAuth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const cmd = buildRemoteAgentsInvocation(['devices', 'ping', '--local', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const res = await sshExecAsync(target.name, cmd, { timeoutMs: 60000, multiplex: true });
+    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 60000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
     }
@@ -370,6 +385,7 @@ async function runFleetPing(opts) {
         name: t.device.name,
         platform: t.device.platform,
         skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
     }));
     const probeable = remoteTargets.filter((t) => !t.skip).length;
     const spinner = isInteractiveTerminal() && !opts.json
@@ -511,6 +527,8 @@ Typical workflow:
             process.exit(1);
         }
     });
+    // `agents fleet capture` — snapshot live state into agents.yaml fleet:.
+    registerFleetCaptureCommand(devicesCmd);
     devicesCmd
         .command('register <name>')
         .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
@@ -781,7 +799,7 @@ Typical workflow:
             return;
         }
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
-        const results = runFleet(targets, cmd);
+        const results = runFleet(targets, cmd, { self: machineId() });
         printFleetResults(results);
     });
     devicesCmd
@@ -800,7 +818,7 @@ Typical workflow:
             return;
         }
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
-        const results = runFleet(targets, cmd);
+        const results = runFleet(targets, cmd, { self: machineId() });
         printFleetResults(results);
     });
 }

package/dist/commands/usage.d.ts

@@ -10,4 +10,17 @@
  *     don't publish per-account usage today)
  */
 import type { Command } from 'commander';
+import type { AgentId } from '../lib/types.js';
+import { getUsageInfoForIdentity } from '../lib/usage.js';
+/** One agent's usage snapshot — the unit the text and --json renderers share. */
+export interface AgentUsageRecord {
+    agent: AgentId;
+    /** Plain agent name (no ANSI) — safe to emit in --json; the text table colorizes it. */
+    label: string;
+    status: 'unsupported' | 'no-version' | 'not-signed-in' | 'ok';
+    email?: string;
+    usage?: Awaited<ReturnType<typeof getUsageInfoForIdentity>>;
+}
 export declare function registerUsageCommand(program: Command): void;
+/** Render one usage record as the human table section. */
+export declare function formatAgentUsage(rec: AgentUsageRecord): string;

package/dist/commands/usage.js

@@ -13,13 +13,15 @@ const USAGE_SUPPORTED = new Set(['claude', 'codex', 'kimi', 'droid']);
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
+        .option('--json', 'Emit machine-readable JSON (per-agent usage snapshot) instead of the table')
         .addHelpText('after', `
 Examples:
   agents usage              Show usage for all installed agents
   agents usage claude       Show usage for Claude only
   agents usage codex        Show usage for Codex only
+  agents usage --json       Machine-readable snapshot for scripts
 `)
-        .action(async (agentFilter) => {
+        .action(async (agentFilter, options) => {
         let filter;
         if (agentFilter) {
             const resolved = resolveAgentName(agentFilter);
@@ -33,47 +35,67 @@ Examples:
             ? [filter]
             : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
         if (targets.length === 0) {
+            if (options.json) {
+                console.log('[]');
+                return;
+            }
             console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
             return;
         }
-        const sections = await Promise.all(targets.map(async (agentId) => renderAgentUsage(agentId)));
-        console.log(sections.filter(Boolean).join('\n\n'));
+        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId)));
+        if (options.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        console.log(records.map(formatAgentUsage).filter(Boolean).join('\n\n'));
     });
 }
-async function renderAgentUsage(agentId) {
-    const cfg = AGENTS[agentId];
-    const heading = agentLabel(agentId);
+/** Gather one agent's usage snapshot as structured data (shared by both renderers). */
+async function collectAgentUsage(agentId) {
+    // Plain name — color is applied only at text-render time (formatAgentUsage), so
+    // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
+    const label = AGENTS[agentId].name;
     if (!USAGE_SUPPORTED.has(agentId)) {
-        return [
-            `${heading}`,
-            `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`,
-        ].join('\n');
+        return { agent: agentId, label, status: 'unsupported' };
     }
     const versions = listInstalledVersions(agentId);
     const version = getGlobalDefault(agentId) || versions[0];
     if (!version) {
-        return [`${heading}`, `  ${chalk.dim('No version installed.')}`].join('\n');
+        return { agent: agentId, label, status: 'no-version' };
     }
     const home = getVersionHomePath(agentId, version);
     const info = await getAccountInfo(agentId, home);
     if (!info.usageKey && !info.accountKey) {
-        return [`${heading}`, `  ${chalk.dim('Not signed in.')}`].join('\n');
-    }
-    const usage = await getUsageInfoForIdentity({
-        agentId,
-        home,
-        info,
-        cliVersion: null,
-    });
-    const lines = [heading];
-    if (info.email)
-        lines.push(`  ${chalk.dim(info.email)}`);
-    const section = formatUsageSection(usage);
-    if (section.length === 0) {
-        lines.push(`  ${chalk.dim('No usage data available right now.')}`);
+        return { agent: agentId, label, status: 'not-signed-in' };
     }
-    else {
-        lines.push(...section);
+    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null });
+    return { agent: agentId, label, status: 'ok', email: info.email ?? undefined, usage };
+}
+/** Render one usage record as the human table section. */
+export function formatAgentUsage(rec) {
+    const cfg = AGENTS[rec.agent];
+    // Colorize the heading here (not in the record) so the plain `label` stays
+    // clean for --json while the text table keeps its per-agent color.
+    const heading = agentLabel(rec.agent);
+    switch (rec.status) {
+        case 'unsupported':
+            return [heading, `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`].join('\n');
+        case 'no-version':
+            return [heading, `  ${chalk.dim('No version installed.')}`].join('\n');
+        case 'not-signed-in':
+            return [heading, `  ${chalk.dim('Not signed in.')}`].join('\n');
+        case 'ok': {
+            const lines = [heading];
+            if (rec.email)
+                lines.push(`  ${chalk.dim(rec.email)}`);
+            const section = formatUsageSection(rec.usage);
+            if (section.length === 0) {
+                lines.push(`  ${chalk.dim('No usage data available right now.')}`);
+            }
+            else {
+                lines.push(...section);
+            }
+            return lines.join('\n');
+        }
     }
-    return lines.join('\n');
 }

package/dist/lib/commands.d.ts

@@ -89,6 +89,16 @@ export interface VersionCommandDiff {
 /**
  * Compare a version home's commands against central. Returns the reconciliation diff.
  */
+/**
+ * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
+ * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
+ * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
+ * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
+ * the orphan detector must NOT flag them — else `prune cleanup` proposes
+ * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
+ * system + extra marketplaces (no project layer), matching the trusted sources.
+ */
+export declare function listPluginCommandNames(): Set<string>;
 export declare function diffVersionCommands(agent: AgentId, version: string): VersionCommandDiff;
 /**
  * Install a single command from central into a specific version home.

package/dist/lib/commands.js

@@ -14,6 +14,7 @@ import { capableAgents, isCapable, supports } from './capabilities.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
+import { discoverPlugins } from './plugins.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 import { installGooseCommandToVersion, listGooseCommandsInVersion, gooseCommandMatches, removeGooseCommandFromVersion, } from './goose-commands.js';
 function compareVersions(a, b) {
@@ -311,8 +312,26 @@ function versionCommandMatches(agent, version, commandName) {
 /**
  * Compare a version home's commands against central. Returns the reconciliation diff.
  */
+/**
+ * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
+ * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
+ * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
+ * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
+ * the orphan detector must NOT flag them — else `prune cleanup` proposes
+ * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
+ * system + extra marketplaces (no project layer), matching the trusted sources.
+ */
+export function listPluginCommandNames() {
+    const names = new Set();
+    for (const plugin of discoverPlugins()) {
+        for (const cmd of plugin.commands)
+            names.add(`${plugin.name}-${cmd}`);
+    }
+    return names;
+}
 export function diffVersionCommands(agent, version) {
     const central = new Set(listCentralCommands());
+    const pluginCommands = listPluginCommandNames();
     const installed = new Set(listCommandsInVersionHome(agent, version));
     const toAdd = [];
     const toUpdate = [];
@@ -335,15 +354,20 @@ export function diffVersionCommands(agent, version) {
         }
     }
     for (const name of installed) {
-        if (!central.has(name)) {
-            orphans.push(name);
+        if (central.has(name)) {
+            const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+            const metadata = parseCommandMetadata(sourcePath);
+            if (!commandAppliesTo(agent, version, metadata).ok) {
+                toRemove.push(name);
+            }
             continue;
         }
-        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
-        const metadata = parseCommandMetadata(sourcePath);
-        if (!commandAppliesTo(agent, version, metadata).ok) {
-            toRemove.push(name);
-        }
+        // A plugin-bundled command (installed as `<plugin>-<cmd>`) is source-managed
+        // by its plugin — not an orphan. Only a name with no central AND no plugin
+        // source is genuinely unmanaged.
+        if (pluginCommands.has(name))
+            continue;
+        orphans.push(name);
     }
     return {
         agent,

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

@@ -8,6 +8,19 @@ export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
  * it against the shared injection guard. Throws if the device has no address.
  */
 export declare function sshTargetFor(device: DeviceProfile): string;
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

package/dist/lib/devices/connect.js

@@ -38,6 +38,26 @@ export function sshTargetFor(device) {
     assertValidSshTarget(target);
     return target;
 }
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export function fleetDialTarget(device) {
+    try {
+        return sshTargetFor(device);
+    }
+    catch {
+        return device.user ? `${device.user}@${device.name}` : device.name;
+    }
+}
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

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

@@ -70,17 +70,50 @@ export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?:
     stdout: string;
     stderr: string;
 };
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export declare function runLocalCommand(cmd: string[], opts?: {
+    timeoutMs?: number;
+}): {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+};
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
  * cannot inject shell metacharacters into the remote command line.
  */
 export declare function upgradeCommand(version?: string): string[];
+export interface RunFleetOptions {
+    /**
+     * Name of THIS machine. Its target runs the command **locally** (no ssh) — a
+     * box can't reliably ssh to itself and doesn't need to. Omit to ssh every
+     * target (the old behaviour). Callers pass `machineId()`.
+     */
+    self?: string;
+    /** Injectable ssh runner (tests). */
+    runner?: typeof runOnDevice;
+    /** Injectable local runner (tests). */
+    localRunner?: typeof runLocalCommand;
+}
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];
+export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
 /** Run one async probe per device in parallel, preserving input order. */
 export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;

package/dist/lib/devices/fleet.js

@@ -94,6 +94,39 @@ export function runOnDevice(device, cmd, opts = {}) {
         };
     }
 }
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export function runLocalCommand(cmd, opts = {}) {
+    try {
+        const res = spawnSync(cmd.join(' '), {
+            shell: true,
+            encoding: 'utf-8',
+            timeout: opts.timeoutMs ?? 600_000,
+        });
+        return {
+            code: res.status,
+            stdout: res.stdout?.toString() ?? '',
+            stderr: (res.stderr?.toString() ?? '') + (res.error ? String(res.error.message) : ''),
+        };
+    }
+    catch (err) {
+        return {
+            code: 1,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
@@ -110,10 +143,14 @@ export function upgradeCommand(version) {
 }
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export function runFleet(targets, cmd, runner = runOnDevice) {
+export function runFleet(targets, cmd, opts = {}) {
+    const runner = opts.runner ?? runOnDevice;
+    const localRunner = opts.localRunner ?? runLocalCommand;
     const results = [];
     for (const t of targets) {
         if (t.skip) {
@@ -126,7 +163,8 @@ export function runFleet(targets, cmd, runner = runOnDevice) {
             continue;
         }
         try {
-            const res = runner(t.device, cmd);
+            const isSelf = opts.self !== undefined && t.device.name === opts.self;
+            const res = isSelf ? localRunner(cmd) : runner(t.device, cmd);
             const ok = res.code === 0;
             const detail = (res.stderr || res.stdout).trim().slice(0, 200);
             results.push({

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

@@ -69,6 +69,36 @@ export declare function runDeviceSync(opts?: {
     soft?: boolean;
     mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
+export interface EnsureDevicesResult {
+    /** Names newly resolved from Tailscale and upserted into the registry. */
+    registered: string[];
+    /** Names that could not be resolved (not on the tailnet / tailscale absent). */
+    unresolved: string[];
+}
+/**
+ * Pure decision for `ensureDevicesRegistered`: split the wanted names into those
+ * to resolve+register (missing from the registry, present on the tailnet, not
+ * ignored) vs. unresolved (missing and either off-tailnet or ignored). Already-
+ * registered names need nothing. Pure so the bootstrap's filter matrix is
+ * unit-testable without a tailnet or registry writes.
+ */
+export interface WantedPartition {
+    toRegister: string[];
+    unresolved: string[];
+}
+export declare function partitionWantedDevices(wanted: string[], registered: Set<string>, tailscaleNames: Set<string>, ignored: Set<string>): WantedPartition;
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export declare function ensureDevicesRegistered(wantedNames: string[]): Promise<EnsureDevicesResult>;
 /**
  * The register/remove/ignore decision for the interactive curation picker.
  * Pure so the highest-risk reconcile logic is unit-testable without a tailnet

package/dist/lib/devices/sync.js

@@ -125,6 +125,56 @@ export async function runDeviceSync(opts = {}) {
         throw err;
     }
 }
+export function partitionWantedDevices(wanted, registered, tailscaleNames, ignored) {
+    const out = { toRegister: [], unresolved: [] };
+    for (const name of wanted) {
+        if (registered.has(name))
+            continue;
+        if (tailscaleNames.has(name) && !ignored.has(name))
+            out.toRegister.push(name);
+        else
+            out.unresolved.push(name);
+    }
+    return out;
+}
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export async function ensureDevicesRegistered(wantedNames) {
+    const registryBefore = await loadDevices();
+    const registered = new Set(Object.keys(registryBefore));
+    const missing = wantedNames.filter((n) => !registered.has(n));
+    if (missing.length === 0)
+        return { registered: [], unresolved: [] };
+    let nodes;
+    try {
+        nodes = parseTailscaleStatus(tailscaleStatusJson());
+    }
+    catch {
+        // Tailscale absent/unreachable — nothing resolvable; report all missing.
+        return { registered: [], unresolved: missing };
+    }
+    const ignored = await loadIgnored();
+    const tailscaleNames = new Set(nodes.map((n) => n.name));
+    const { toRegister, unresolved } = partitionWantedDevices(missing, registered, tailscaleNames, ignored);
+    const byName = new Map(nodes.map((n) => [n.name, n]));
+    const localUser = localLoginUser();
+    const done = [];
+    for (const name of toRegister) {
+        const input = withDefaultUser(nodeToDeviceInput(byName.get(name)), registryBefore[name]?.user, localUser);
+        await upsertDevice(name, input);
+        done.push(name);
+    }
+    return { registered: done, unresolved };
+}
 export function planDeviceReconciliation(allNames, keep, registered, ignored) {
     const keepSet = new Set(keep);
     const regSet = new Set(registered);