@phnx-labs/agents-cli 1.20.64 → 1.20.66

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

package/dist/lib/fleet/auth-sync.js

@@ -0,0 +1,142 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+/**
+ * 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 const FLEET_AUTH_FILES = {
+    claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
+    codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
+    gemini: [{ rel: '.gemini/oauth_creds.json', mode: 0o600 }],
+    grok: [{ rel: '.grok/auth.json', mode: 0o600 }],
+    kimi: [{ rel: '.kimi-code/credentials/kimi-code.json', mode: 0o600 }],
+    opencode: [{ rel: '.local/share/opencode/auth.json', mode: 0o600 }],
+    droid: [
+        { rel: '.factory/auth.v2.file', mode: 0o600 },
+        { rel: '.factory/auth.v2.key', mode: 0o600 },
+    ],
+    antigravity: [{ rel: '.gemini/antigravity-cli/antigravity-oauth-token', mode: 0o600 }],
+};
+/** Agents whose macOS credentials live in the ACL-bound login keychain. */
+export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
+/** Which agents `apply` can propagate auth for at all. */
+export function isPropagatableAgent(agent) {
+    return agent in FLEET_AUTH_FILES;
+}
+/**
+ * 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 function snapshotAuth(agents, opts) {
+    const files = [];
+    const bound = [];
+    for (const agent of agents) {
+        const specs = FLEET_AUTH_FILES[agent];
+        if (!specs)
+            continue; // not propagatable — caller surfaces separately if desired
+        if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
+            bound.push(agent);
+            continue;
+        }
+        for (const spec of specs) {
+            const abs = path.join(opts.home, spec.rel);
+            let stat;
+            try {
+                stat = fs.statSync(abs);
+            }
+            catch {
+                continue; // not signed in for this agent — nothing to carry
+            }
+            if (!stat.isFile())
+                continue;
+            const content = fs.readFileSync(abs); // follows symlinks into version homes
+            files.push({
+                agent,
+                rel: spec.rel,
+                contentB64: content.toString('base64'),
+                mode: (stat.mode & 0o777) || spec.mode,
+            });
+        }
+    }
+    return { files, bound };
+}
+/** Assemble the plaintext bundle shipped to a target. */
+export function buildAuthBundle(source, files) {
+    return { v: 1, source, files };
+}
+/**
+ * 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 function materializeAuth(bundle, opts) {
+    const written = new Set();
+    const errors = [];
+    for (const f of bundle.files) {
+        const abs = path.join(opts.home, f.rel);
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, Buffer.from(f.contentB64, 'base64'));
+            fs.chmodSync(abs, f.mode || 0o600);
+            written.add(f.agent);
+        }
+        catch (e) {
+            errors.push(`${f.rel}: ${e.message}`);
+        }
+    }
+    return { written: [...written], errors };
+}
+/** Parse + validate a bundle received on stdin (the remote `--_recv-auth` path). */
+export function parseAuthBundle(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`auth bundle is not valid JSON: ${e.message}`);
+    }
+    if (typeof doc !== 'object' || doc === null)
+        throw new Error('auth bundle must be an object.');
+    const o = doc;
+    if (o.v !== 1)
+        throw new Error(`unsupported auth bundle version ${JSON.stringify(o.v)}.`);
+    if (typeof o.source !== 'string')
+        throw new Error('auth bundle missing source.');
+    if (!Array.isArray(o.files))
+        throw new Error('auth bundle missing files[].');
+    for (const f of o.files) {
+        if (typeof f !== 'object' || f === null ||
+            typeof f.agent !== 'string' ||
+            typeof f.rel !== 'string' ||
+            typeof f.contentB64 !== 'string' ||
+            typeof f.mode !== 'number') {
+            throw new Error('auth bundle has a malformed file entry.');
+        }
+        // Reject path traversal — rel must stay under $HOME.
+        const rel = f.rel;
+        if (rel.startsWith('/') || rel.split('/').includes('..')) {
+            throw new Error(`auth bundle rejected unsafe path: ${rel}`);
+        }
+    }
+    return doc;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Parse + validate the `fleet:` block of a profile manifest and resolve it into
+ * per-device desired state.
+ *
+ * `fleet:` is additive to the `Meta` schema (`types.ts`). Any `-f <file>` that
+ * carries a `fleet:` block is a valid manifest, so `ag apply -f agents.yaml`
+ * works against the project file. The functions here are pure (no SSH, no
+ * registry I/O) so they're fully unit-testable; device enumeration is injected.
+ */
+import type { FleetManifest, DeviceDesired } from './types.js';
+/** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
+export declare function parseFleetManifest(raw: unknown): FleetManifest;
+/** Read a YAML file and extract + validate its `fleet:` block. */
+export declare function readFleetFile(filePath: string): FleetManifest;
+export interface ResolveContext {
+    /** Device names currently online (used to expand `devices: all`). */
+    onlineDevices: string[];
+    /** All registered device names (used to validate explicit entries). */
+    registeredDevices: string[];
+    /** The source machine, always excluded from the target set. */
+    source: string;
+}
+/**
+ * Expand a manifest into concrete per-device desired states. `devices: all`
+ * expands to every online registered device minus the source; an explicit map
+ * validates each name against the registry. Devices with no desired agents,
+ * sync scopes, and `login: skip` are still returned (probe/report only).
+ */
+export declare function resolveDesired(manifest: FleetManifest, ctx: ResolveContext): DeviceDesired[];

package/dist/lib/fleet/manifest.js

@@ -0,0 +1,127 @@
+/**
+ * Parse + validate the `fleet:` block of a profile manifest and resolve it into
+ * per-device desired state.
+ *
+ * `fleet:` is additive to the `Meta` schema (`types.ts`). Any `-f <file>` that
+ * carries a `fleet:` block is a valid manifest, so `ag apply -f agents.yaml`
+ * works against the project file. The functions here are pure (no SSH, no
+ * registry I/O) so they're fully unit-testable; device enumeration is injected.
+ */
+import * as fs from 'fs';
+import * as yaml from 'yaml';
+const LOGIN_MODES = ['sync', 'skip'];
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+function validateLogin(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string' || !LOGIN_MODES.includes(v)) {
+        throw new Error(`fleet: ${where}.login must be one of ${LOGIN_MODES.join(' | ')} (got ${JSON.stringify(v)}).`);
+    }
+    return v;
+}
+function validateDefaults(v, where) {
+    if (v === undefined)
+        return {};
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+        throw new Error(`fleet: ${where} must be a mapping.`);
+    }
+    const o = v;
+    if (o.agents !== undefined && !isStringArray(o.agents)) {
+        throw new Error(`fleet: ${where}.agents must be a list of agent specs (e.g. [claude@latest]).`);
+    }
+    if (o.sync !== undefined && !isStringArray(o.sync)) {
+        throw new Error(`fleet: ${where}.sync must be a list of scope names (e.g. [user]).`);
+    }
+    return {
+        agents: o.agents,
+        sync: o.sync,
+        login: validateLogin(o.login, where),
+    };
+}
+/** Validate a raw `fleet:` object (already YAML-parsed) into a typed manifest. */
+export function parseFleetManifest(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('fleet: block must be a mapping with a `devices:` key.');
+    }
+    const o = raw;
+    const defaults = validateDefaults(o.defaults, 'defaults');
+    if (o.devices === undefined) {
+        throw new Error('fleet: a `devices:` key is required (use `devices: all` or an explicit map).');
+    }
+    let devices;
+    if (o.devices === 'all') {
+        devices = 'all';
+    }
+    else if (typeof o.devices === 'object' && o.devices !== null && !Array.isArray(o.devices)) {
+        const map = {};
+        for (const [name, ov] of Object.entries(o.devices)) {
+            // An empty entry (`device: {}`) inherits defaults — represent as {}.
+            const merged = ov == null ? {} : validateDefaults(ov, `devices.${name}`);
+            map[name] = merged;
+        }
+        devices = map;
+    }
+    else {
+        throw new Error(`fleet: devices must be the string 'all' or a mapping of device -> overrides (got ${JSON.stringify(o.devices)}).`);
+    }
+    return { defaults, devices };
+}
+/** Read a YAML file and extract + validate its `fleet:` block. */
+export function readFleetFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Manifest not found: ${filePath}`);
+    }
+    let doc;
+    try {
+        doc = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Failed to parse YAML in ${filePath}: ${e.message}`);
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw new Error(`${filePath} is not a mapping — no fleet: block to apply.`);
+    }
+    const fleet = doc.fleet;
+    if (fleet === undefined) {
+        throw new Error(`${filePath} has no fleet: block. Add one to declare the profile (see \`agents apply --help\`).`);
+    }
+    return parseFleetManifest(fleet);
+}
+/** Merge a per-device override over defaults into a concrete desired state. */
+function mergeDesired(device, defaults, override) {
+    return {
+        device,
+        agents: override.agents ?? defaults.agents ?? [],
+        sync: override.sync ?? defaults.sync ?? [],
+        login: override.login ?? defaults.login ?? 'sync',
+    };
+}
+/**
+ * Expand a manifest into concrete per-device desired states. `devices: all`
+ * expands to every online registered device minus the source; an explicit map
+ * validates each name against the registry. Devices with no desired agents,
+ * sync scopes, and `login: skip` are still returned (probe/report only).
+ */
+export function resolveDesired(manifest, ctx) {
+    const defaults = manifest.defaults ?? {};
+    const out = [];
+    if (manifest.devices === 'all') {
+        for (const name of ctx.onlineDevices) {
+            if (name === ctx.source)
+                continue;
+            out.push(mergeDesired(name, defaults, {}));
+        }
+        return out;
+    }
+    for (const [name, override] of Object.entries(manifest.devices)) {
+        if (name === ctx.source)
+            continue;
+        if (!ctx.registeredDevices.includes(name)) {
+            throw new Error(`fleet: device '${name}' is not a registered device. Run \`agents devices add ${name}\` or fix the manifest.`);
+        }
+        out.push(mergeDesired(name, defaults, override));
+    }
+    return out;
+}