@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/commands/ssh.js

@@ -7,7 +7,7 @@
  * (offline → fail fast instead of a 2-minute hang), platform-aware exec
  * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
  * Rendering the registry to an ssh_config include also lets plain ssh / scp /
- * rsync / `agents sessions --host` resolve the same logical names.
+ * rsync / `agents sessions --device` resolve the same logical names.
  */
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
@@ -31,6 +31,7 @@ import { defaultPickerChecked, localLoginUser, planDeviceReconciliation, runDevi
 import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-target.js';
 import { deriveMirroredCwd } from '../lib/project-root.js';
 import { clearPendingSentinel } from '../lib/devices/pending.js';
+import { getDeviceDiscoveryStatus, setDeviceDiscoveryStatus } from '../lib/devices/discovery-policy.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
@@ -54,14 +55,16 @@ import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { collectLocalHarnessInventory, groupByAccount, renderAccountsMatrix, renderHarnessMatrix, } from '../lib/devices/harness-inventory.js';
 import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js';
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort, registerLeaseCommand } from './lease.js';
+import { registerSnapshotCommand } from './snapshot.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
 import { runFleetLogin } from '../lib/fleet/remote-login.js';
-import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec } from '../lib/device-config.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec, autoPoolMode, configuredDeviceRole, listConfiguredDeviceRoles, setConfiguredDeviceRole, } from '../lib/device-config.js';
+import { filterAutoPool, listWorkerDevices } from '../lib/devices/pool.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet.
  * `isInteractive` marks the configured interactive host (`devices config <name> interactive.host`). */
-function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
+function deviceSummary(d, isSelf = false, stats, isInteractive = false, roles) {
     d = resolveDeviceProfile(d);
     const addr = hostNameFor(d) ?? chalk.gray('no address');
     // Prefer a fresh live verdict (this run's probe, else the written-back
@@ -77,7 +80,22 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
     const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
-    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}`;
+    // `roles` defaults to a single-device roster so a fleet-wide `role` default
+    // still reaches this device even when it has no per-device doc of its own.
+    const role = roleTag(d.name, roles ?? listConfiguredDeviceRoles([d.name]));
+    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
+}
+/** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
+ * an unmarked device is the common case and must not add a column of noise. */
+function roleTag(name, roles) {
+    const role = roles[name];
+    if (!role)
+        return '';
+    if (role === 'worker')
+        return chalk.green('  worker');
+    if (role === 'personal')
+        return chalk.yellow('  personal');
+    return chalk.gray('  control');
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -105,8 +123,11 @@ function pctCell(v, width) {
  * capacity summary is appended whenever stats were gathered.
  */
 function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
-    if (!statsMap)
-        return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost));
+    if (!statsMap) {
+        const roles = listConfiguredDeviceRoles(names);
+        return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost, roles));
+    }
+    const deviceRoles = listConfiguredDeviceRoles(names);
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
@@ -149,7 +170,7 @@ function renderDeviceTable(reg, names, self, statsMap, full = false, interactive
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
         const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
-        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}`);
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}${roleTag(name, deviceRoles)}`);
     }
     // Fleet capacity summary — total cores + how much RAM is free right now.
     const cap = fleetCapacity(statsMap.values());
@@ -304,13 +325,16 @@ async function runInteractiveDeviceSync() {
     for (const name of plan.toRegister) {
         const input = withDefaultUser(nodeToDeviceInput(byName.get(name)), reg[name]?.user, localUser);
         await upsertDevice(name, input);
+        setDeviceDiscoveryStatus(name, 'approved');
     }
     for (const name of plan.toUnignore)
         await removeIgnored(name);
     for (const name of plan.toRemove)
         await removeDevice(name);
-    for (const name of plan.toIgnore)
+    for (const name of plan.toIgnore) {
         await addIgnored(name);
+        setDeviceDiscoveryStatus(name, 'ignored');
+    }
     const parts = [
         chalk.green(`${plan.toRegister.length} registered`),
         plan.toRemove.length ? chalk.yellow(`${plan.toRemove.length} removed`) : null,
@@ -420,11 +444,14 @@ async function probeRemoteHealth(target) {
         inventory: parsed.fleet,
     };
 }
-/** Effective device-scoped config, keyed by the canonical YAML key. */
+/** Device-layer config only (not fleet defaults), keyed by the canonical YAML key. */
 function deviceConfigJson(name) {
     const config = {};
     for (const entry of listConfig({ device: name })) {
-        if (entry.spec.scope !== 'device' || entry.value === undefined)
+        // The device's OWN layer only — a fleet-default value is not this
+        // device's setting (the effective profile fields already carry the
+        // merged view via resolveDeviceProfile).
+        if (entry.source !== 'device')
             continue;
         config[entry.spec.yamlKey] = entry.value;
     }
@@ -967,9 +994,10 @@ function registerDevicesCommands(program) {
         notes: '`agents fleet` is an alias for `agents devices` — same subcommands.',
     });
     registerLeaseCommand(devicesCmd);
+    registerSnapshotCommand(devicesCmd);
     registerCommandGroups(devicesCmd, [
         { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'rm'] },
-        { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts'] },
+        { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts', 'snapshot'] },
         { title: 'Disposable devices', names: ['lease'] },
         { title: 'Configure a device', names: ['config', 'render'] },
         { title: 'Fleet operations', names: ['update', 'run', 'login', 'pair-ios', 'capture', 'apply'] },
@@ -986,6 +1014,8 @@ function registerDevicesCommands(program) {
         const spinner = ora('Reading tailscale status...').start();
         try {
             const res = await runDeviceSync();
+            for (const name of res.syncedNames)
+                setDeviceDiscoveryStatus(name, 'approved');
             const extra = res.pending.length ? chalk.gray(` (${res.pending.length} new)`) : '';
             spinner.succeed(`Synced ${res.synced} device${res.synced === 1 ? '' : 's'} from Tailscale${extra}`);
         }
@@ -1001,7 +1031,7 @@ function registerDevicesCommands(program) {
     registerFleetApplyAlias(devicesCmd);
     devicesCmd
         .command('register <name>')
-        .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
+        .description('Register a discovered node and sync the approval through agents.yaml fleet.discovery.')
         .action(async (name) => {
         try {
             const nodes = parseTailscaleStatus(tailscaleStatusJson());
@@ -1012,6 +1042,7 @@ function registerDevicesCommands(program) {
             }
             await removeIgnored(name); // a re-registered node is no longer dismissed
             const d = await upsertDevice(name, nodeToDeviceInput(node));
+            setDeviceDiscoveryStatus(name, 'approved');
             clearPendingSentinel(name); // drop the notification immediately
             console.log(chalk.green(`Registered '${name}'`) + chalk.gray(` (${d.platform})`));
         }
@@ -1022,11 +1053,12 @@ function registerDevicesCommands(program) {
     });
     devicesCmd
         .command('ignore <name>')
-        .description('Dismiss a node from auto-discovery so it is never re-suggested (and remove it from the registry if present).')
+        .description('Dismiss a node and sync the decision through agents.yaml fleet.discovery (also removes it locally).')
         .action(async (name) => {
         try {
             await removeDevice(name);
             await addIgnored(name);
+            setDeviceDiscoveryStatus(name, 'ignored');
             clearPendingSentinel(name); // drop the notification immediately
             console.log(chalk.green(`Ignored '${name}'`) + chalk.gray(" — it won't be suggested again. Undo with `agents devices unignore`."));
         }
@@ -1039,11 +1071,13 @@ function registerDevicesCommands(program) {
         .command('unignore <name>')
         .description('Undo `ignore`: allow a node to be discovered and registered again.')
         .action(async (name) => {
+        const portableWasIgnored = getDeviceDiscoveryStatus(name) === 'ignored';
         const ok = await removeIgnored(name);
-        if (!ok) {
+        if (!ok && !portableWasIgnored) {
             console.error(chalk.gray(`'${name}' was not ignored.`));
             return;
         }
+        setDeviceDiscoveryStatus(name, undefined);
         console.log(chalk.green(`No longer ignoring '${name}'`) + chalk.gray(' — run `agents devices sync` to register it.'));
     });
     // ─── devices config (unified settings surface) ────────────────────────────
@@ -1079,18 +1113,39 @@ function registerDevicesCommands(program) {
     };
     /** The device-scope config entries for `name` (what the config surface edits). */
     const deviceConfigEntries = (name) => listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
+    /** Render one entry's effective value with its layer tag. */
+    const entryValueText = (e) => {
+        if (e.source === 'default')
+            return chalk.gray('— (default)');
+        const tag = e.source === 'fleet' ? chalk.yellow('  (fleet default)') : e.source === 'user' ? chalk.gray('  (user scope)') : '';
+        return chalk.cyan(JSON.stringify(e.value)) + tag;
+    };
     /** Print the full resolved config for a device (bare invocation, non-menu). */
     const printDevicesConfig = (name, json) => {
         const entries = deviceConfigEntries(name);
         if (json) {
             const config = {};
             for (const e of entries)
-                if (e.value !== undefined)
-                    config[e.spec.name] = e.value;
+                config[e.spec.name] = { value: e.value ?? null, source: e.source };
             writeJson({ device: name, config });
             return;
         }
         console.log(chalk.bold(`Config for '${name}'`));
+        for (const e of entries) {
+            console.log(`  ${e.spec.name.padEnd(24)} ${entryValueText(e)}${chalk.gray(`  ${e.spec.description}`)}`);
+        }
+    };
+    /** Print the fleet-wide defaults layer (`config --fleet`, bare). */
+    const printFleetConfig = (json) => {
+        const entries = listConfig({ fleet: true }).filter((e) => e.spec.scope === 'device');
+        if (json) {
+            const config = {};
+            for (const e of entries)
+                config[e.spec.name] = { value: e.value ?? null, source: e.source };
+            writeJson({ fleet: true, config });
+            return;
+        }
+        console.log(chalk.bold('Fleet-wide config defaults') + chalk.gray('  (every device inherits these unless it overrides the key)'));
         for (const e of entries) {
             const value = e.value === undefined ? chalk.gray('— (default)') : chalk.cyan(JSON.stringify(e.value));
             console.log(`  ${e.spec.name.padEnd(24)} ${value}${chalk.gray(`  ${e.spec.description}`)}`);
@@ -1099,11 +1154,60 @@ function registerDevicesCommands(program) {
     /**
      * The `devices config` engine — shared by the config command's action and
      * every tombstone. `quiet` performs the write with no output (a tombstone
-     * that prints its own legacy shape). Throws on a bad key/value; callers map
-     * that to exit 1.
+     * that prints its own legacy shape). `fleet` targets the fleet-wide defaults
+     * layer instead of a device (`name` is then unused). Throws on a bad
+     * key/value; callers map that to exit 1.
      */
     const runDevicesConfig = async (name, key, valueParts, opts) => {
         const spec = key ? configKeySpec(key) : undefined; // unknown key → throw listing the valid keys
+        // ── Fleet-defaults layer (`--fleet`): no device involved.
+        if (opts.fleet) {
+            if (spec && spec.scope === 'user') {
+                throw new Error(`Config key '${spec.name}' is user-scope (already fleet-wide) — --fleet does not apply.`);
+            }
+            if (opts.unset) {
+                if (!spec)
+                    throw new Error('--unset needs a key: agents devices config --fleet <key> --unset');
+                unsetConfigValue(spec.name, { fleet: true });
+                if (opts.quiet)
+                    return;
+                if (opts.json)
+                    writeJson({ fleet: true, key: spec.name, value: null, source: 'default' });
+                else
+                    console.log(chalk.green(`Unset ${spec.name}`) + chalk.gray(' in the fleet defaults.'));
+                return;
+            }
+            if (spec && valueParts.length > 0) {
+                let value;
+                if (spec.type === 'string-list') {
+                    const existing = getConfigValue(spec.name, { fleet: true }).value ?? [];
+                    value = [...existing, valueParts.join(' ')];
+                }
+                else {
+                    value = parseConfigValueInput(spec, valueParts.join(' '));
+                }
+                setConfigValue(spec.name, value, { fleet: true });
+                if (opts.quiet)
+                    return;
+                if (opts.json)
+                    writeJson({ fleet: true, key: spec.name, value, source: 'fleet' });
+                else
+                    console.log(chalk.green(`Set ${spec.name} = ${JSON.stringify(value)}`) + chalk.gray(' as the fleet-wide default.'));
+                return;
+            }
+            if (spec) {
+                const entry = getConfigValue(spec.name, { fleet: true });
+                if (opts.quiet)
+                    return;
+                if (opts.json)
+                    writeJson({ fleet: true, key: spec.name, value: entry.value ?? null, source: entry.source });
+                else
+                    console.log(`  ${spec.name.padEnd(24)} ${entryValueText(entry)}${chalk.gray(`  ${spec.description}`)}`);
+                return;
+            }
+            printFleetConfig(Boolean(opts.json));
+            return;
+        }
         // User-scope keys (interactive.host) are stored centrally — the device name
         // is syntax only, so an unregistered name is not an error for them.
         if (!spec || spec.scope === 'device')
@@ -1115,9 +1219,9 @@ function registerDevicesCommands(program) {
             if (opts.quiet)
                 return;
             if (opts.json)
-                writeJson({ device: name, key: spec.name, value: null });
+                writeJson({ device: name, key: spec.name, value: null, source: 'default' });
             else
-                console.log(chalk.green(`Unset ${spec.name}`) + chalk.gray(` on '${name}' — back to the default.`));
+                console.log(chalk.green(`Unset ${spec.name}`) + chalk.gray(` on '${name}' — falls back to the fleet default / built-in behavior.`));
             return;
         }
         if (spec && valueParts.length > 0) {
@@ -1134,7 +1238,7 @@ function registerDevicesCommands(program) {
             if (opts.quiet)
                 return;
             if (opts.json)
-                writeJson({ device: name, key: spec.name, value });
+                writeJson({ device: name, key: spec.name, value, source: 'device' });
             else
                 console.log(chalk.green(`Set ${spec.name} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
             return;
@@ -1144,13 +1248,10 @@ function registerDevicesCommands(program) {
             if (opts.quiet)
                 return;
             if (opts.json) {
-                writeJson({ device: name, key: spec.name, value: entry.value ?? null });
-            }
-            else if (entry.value === undefined) {
-                console.log(`  ${spec.name.padEnd(24)} ${chalk.gray('— (default)')}${chalk.gray(`  ${spec.description}`)}`);
+                writeJson({ device: name, key: spec.name, value: entry.value ?? null, source: entry.source });
             }
             else {
-                console.log(`  ${spec.name.padEnd(24)} ${chalk.cyan(JSON.stringify(entry.value))}${chalk.gray(`  ${spec.description}`)}`);
+                console.log(`  ${spec.name.padEnd(24)} ${entryValueText(entry)}${chalk.gray(`  ${spec.description}`)}`);
             }
             return;
         }
@@ -1161,7 +1262,96 @@ function registerDevicesCommands(program) {
         }
         await runDevicesConfigMenu(name);
     };
-    /** The interactive settings menu: pick a key, edit it, repeat. TTY-only. */
+    /**
+     * The `devices role` engine — read or write the fleet-wide role mark, and say
+     * what it does to automatic placement.
+     *
+     * A role written here lands in that device's tracked per-device doc
+     * (`devices/<name>/agents.yaml` `config.role`) and syncs with repo
+     * push/pull. The vocabulary is deliberately `worker | personal` only: a
+     * paired cockpit's `control` role lives in the per-machine device registry,
+     * is written by `agents devices pair-ios`, and is what the existing
+     * dial-exclusion filters (`isControlDevice`) read. Accepting `control` here
+     * too would promise a fleet-wide dial exclusion this key cannot deliver —
+     * those filters read each box's own registry, so the mark would only hold
+     * on the machine that ran the command.
+     */
+    const runDevicesRole = async (name, role, opts) => {
+        if (!name) {
+            if (role)
+                throw new Error('Name a device: agents devices role <name> <worker|personal>');
+            const reg = await loadDevices();
+            // The full registered roster, not just online — a fleet-wide `role`
+            // default must reach a registered device even when it has no per-device
+            // doc of its own, or it silently falls out of the worker allowlist.
+            const roles = listConfiguredDeviceRoles(Object.keys(reg));
+            const mode = autoPoolMode();
+            const online = Object.entries(reg)
+                .filter(([, d]) => d?.tailscale?.online !== false)
+                .map(([n]) => n);
+            const pool = filterAutoPool(online, { mode, roles });
+            if (opts.json) {
+                writeJson({ mode, roles, autoPool: pool });
+                return;
+            }
+            const marked = Object.entries(roles);
+            if (marked.length === 0) {
+                console.log(chalk.gray('No device is marked. `--device auto` considers every online device.'));
+            }
+            else {
+                for (const [device, r] of marked) {
+                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : chalk.gray;
+                    console.log(`  ${device.padEnd(20)} ${tint(r)}`);
+                }
+            }
+            console.log();
+            console.log(chalk.bold('--device auto picks from: ') + (pool.length > 0 ? pool.join(', ') : chalk.red('nothing — no eligible device')));
+            if (mode === 'all')
+                console.log(chalk.gray('auto.pool=all — worker marks are ignored (a personal device is still excluded).'));
+            return;
+        }
+        await mustGetDevice(name);
+        if (opts.clear || role === 'none') {
+            setConfiguredDeviceRole(name, undefined);
+            if (opts.json)
+                writeJson({ device: name, role: null });
+            else
+                console.log(chalk.green(`Cleared the role on '${name}'.`));
+            return;
+        }
+        if (!role) {
+            const current = configuredDeviceRole(name);
+            if (opts.json)
+                writeJson({ device: name, role: current ?? null });
+            else
+                console.log(`  ${name.padEnd(20)} ${current ? chalk.cyan(current) : chalk.gray('— (unmarked)')}`);
+            return;
+        }
+        // configuredDeviceRole's key spec validates the value; a bad one throws with
+        // the accepted list, which the command's catch turns into exit 1.
+        setConfiguredDeviceRole(name, role);
+        // Full registered roster, mirroring the bare-listing branch above — a
+        // fleet-wide `role` default must reach a doc-less registered device here
+        // too, or `autoPoolWorkers` under-reports the allowlist right after this
+        // write changed it.
+        const roles = listConfiguredDeviceRoles(Object.keys(await loadDevices()));
+        if (opts.json) {
+            writeJson({ device: name, role, autoPoolWorkers: listWorkerDevices({ roles }) });
+            return;
+        }
+        console.log(chalk.green(`Marked '${name}' role=${role}.`));
+        const workers = listWorkerDevices({ roles });
+        if (workers.length > 0) {
+            console.log(chalk.gray(`\`--device auto\` now picks only from: ${workers.join(', ')}`));
+        }
+        else {
+            console.log(chalk.gray('No device is marked worker, so `--device auto` still considers every online device.'));
+        }
+        console.log(chalk.gray('Sync it to the fleet with `agents repo push`.'));
+    };
+    /** The interactive settings menu: pick a key, edit it, repeat. TTY-only.
+     * Shows EFFECTIVE values (with a fleet tag when inherited); edits always
+     * write the device layer. */
     const runDevicesConfigMenu = async (name) => {
         const { select, input, confirm } = await import('@inquirer/prompts');
         const DONE = '__done__';
@@ -1169,12 +1359,12 @@ function registerDevicesCommands(program) {
             for (;;) {
                 const entries = deviceConfigEntries(name);
                 const picked = await select({
-                    message: `Config for '${name}' — pick a key to edit:`,
+                    message: `Config for '${name}' — pick a key to edit (writes the device layer):`,
                     pageSize: Math.min(entries.length + 1, 20),
                     choices: [
                         ...entries.map((e) => {
-                            const value = e.value !== undefined
-                                ? chalk.cyan(JSON.stringify(e.value))
+                            const value = e.source !== 'default'
+                                ? entryValueText(e)
                                 : chalk.gray(e.spec.defaultValue !== undefined
                                     ? `default: ${JSON.stringify(e.spec.defaultValue)}`
                                     : 'unset (default)');
@@ -1224,14 +1414,25 @@ function registerDevicesCommands(program) {
         }
     };
     const configCmd = devicesCmd
-        .command('config <name> [key] [value...]')
+        .command('config [name] [key] [value...]')
         .description('Get, set, or unset a device’s settings (scheduler, agent cap, ssh overrides, auto-launch, notes). ' +
         'Bare opens an interactive settings menu (TTY) or prints the resolved config (piped). ' +
-        'Stored centrally in ~/.agents/agents.yaml under fleet.devices.<name>.config — synced, so any box can configure any device.')
-        .option('--unset', 'reset the key to its default (removes the stored value)')
-        .option('--json', 'output machine-readable JSON')
+        'Per-device values live in the tracked devices/<name>/agents.yaml config: block; --fleet targets the ' +
+        'fleet-wide defaults (central fleet.defaults.config) every device inherits unless it overrides the key.')
+        .option('--fleet', 'target the fleet-wide defaults layer instead of a device (first positional is the key)')
+        .option('--unset', 'reset the key at that layer (a device key then inherits the fleet default)')
+        .option('--json', 'output machine-readable JSON (each key carries its source: device | fleet | default)')
         .action(async (name, key, valueParts, opts) => {
         try {
+            if (opts.fleet) {
+                // Positionals shift left: the first one is the key, the rest the value.
+                const fleetValue = [key, ...(valueParts ?? [])].filter((v) => v !== undefined);
+                await runDevicesConfig(undefined, name, fleetValue, opts);
+                return;
+            }
+            if (!name) {
+                throw new Error('Missing device name. Usage: agents devices config <name> [key] [value] — or --fleet <key> <value> for the fleet-wide defaults.');
+            }
             await runDevicesConfig(name, key, valueParts ?? [], opts);
         }
         catch (err) {
@@ -1242,38 +1443,97 @@ function registerDevicesCommands(program) {
     setHelpSections(configCmd, {
         examples: `
       agents devices config mac-mini                            # settings menu (TTY) / print config (piped)
-      agents devices config mac-mini agents.max-concurrent 4    # cap concurrent agents
+      agents devices config mac-mini agents.max-concurrent 4    # cap concurrent agents on mac-mini
       agents devices config mac-mini scheduler.enabled off      # no routines firing there
-      agents devices config mac-mini scheduler.enabled          # read one key back
-      agents devices config mac-mini scheduler.enabled --unset  # back to the default
+      agents devices config mac-mini scheduler.enabled          # read the effective value back
+      agents devices config mac-mini scheduler.enabled --unset  # inherit the fleet default again
+      agents devices config --fleet scheduler.enabled off       # fleet-wide default (all devices)
+      agents devices config --fleet agents.max-concurrent 2     # every box caps at 2 unless it overrides
+      agents devices config --fleet                             # print the fleet defaults layer
       agents devices config mac-mini notes "runs the releases"  # append an operator note
       agents devices config win-mini ssh.auth password          # password auth…
       agents devices config win-mini ssh.bundle muqsit          # …from this secrets bundle
       agents devices config worker ssh.identity-file ~/.ssh/worker_ed25519
+      agents devices config mac-mini role worker                 # same as \`agents devices role mac-mini worker\`
       agents devices config mac-mini auto-launch.enabled off    # exclude from AGI EXT auto-launch
       agents devices config mac-mini auto-launch.preferred on   # boost in auto-launch ranking
       agents devices config zion interactive.host zion          # user scope: where agents show YOU artifacts
-      agents devices config mac-mini --json                     # machine-readable
+      agents devices config mac-mini --json                     # machine-readable, per-key source
     `,
         notes: `
-      Keys: agents.max-concurrent, scheduler.enabled, daemon.enabled,
-      watchdog.enabled, browser.remote-control, browser.profile, notes,
-      ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
+      Keys: role (worker|personal), see 'agents devices role',
+      agents.max-concurrent, scheduler.enabled, daemon.enabled,
+      watchdog.enabled, tmux.enabled, browser.remote-control,
+      browser.task-idle-minutes, browser.profile,
+      notes, ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
       ssh.identity-file, platform (windows|linux|macos|unknown),
       auto-launch.enabled, auto-launch.preferred — plus the user-scope
       interactive.host (stored centrally; the device name is syntax only).
 
+      Three layers, read in order — built-in default < fleet default
+      (--fleet, central fleet.defaults.config) < per-device value
+      (devices/<name>/agents.yaml config:). Both files are tracked and sync
+      with 'agents repo push/pull'; per-device files are conflict-free because
+      each machine writes only its own folder. --unset removes the value at
+      the targeted layer, so a device key falls back to the fleet default.
+
       Booleans take on/off (or true/false). 'notes' appends one entry per
-      invocation. Values land in ~/.agents/agents.yaml under
-      fleet.devices.<name>.config and sync with 'agents repo push/pull'.
-      ssh.* / platform / user overlay the discovered registry profile at dial
-      time. scheduler.enabled / daemon.enabled take effect when the daemon
-      reloads or restarts on that device.
+      invocation. ssh.* / platform / user overlay the discovered registry
+      profile at dial time. scheduler.enabled / daemon.enabled take effect
+      when the daemon reloads or restarts on that device. Machine-local keys
+      (scheduler.enabled, daemon.enabled, tmux.enabled, browser.remote-control,
+      browser.task-idle-minutes, browser.profile) can only be read or set on
+      the device itself; --fleet still writes a fleet-wide default those boxes
+      inherit until they override.
 
       The retired subcommands still work and forward here: configure, note,
       set, set-interactive, enable, disable, prefer, unprefer.
     `,
     });
+    const roleCmd = devicesCmd
+        .command('role [name] [role]')
+        .description('Show or set what a device is for: worker (agents run here) or personal (you sit here — never picked automatically). ' +
+        'Marking any device worker makes `--device auto` an allowlist over the marked workers.')
+        .option('--clear', 'remove the mark, returning the device to unmarked')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, role, opts) => {
+        try {
+            await runDevicesRole(name, role, opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(roleCmd, {
+        examples: `
+      agents devices role                          # who is marked what, and what --device auto would pick
+      agents devices role yosemite-s0 worker       # agents spin up here
+      agents devices role yosemite-s1 worker       # …and here; auto now rotates over these two only
+      agents devices role zion personal            # your laptop — keep automatic placement off it
+      agents devices role yosemite-s0 --clear      # unmark
+      agents devices role --json                   # machine-readable
+    `,
+        notes: `
+      Roles live in that device's tracked per-device doc
+      (devices/<name>/agents.yaml config.role) and travel with
+      'agents repo push/pull', so a mark set on one box is the whole fleet's
+      answer.
+
+      Effect on '--device auto' (agents run, teams, agents ssh auto, and the AGI
+      EXT launch commands, which all resolve placement through the CLI):
+        no device marked  -> every online device, as before
+        any worker marked -> ONLY the marked workers
+        personal          -> never picked, under either state
+
+      Turn the allowlist off with 'agents config set auto.pool all'; a personal
+      box stays excluded, since that is what the mark is for.
+
+      A paired iPhone/iPad cockpit is a separate role: 'agents devices pair-ios'
+      marks it control in that box's device registry, and the fleet never dials
+      it — including for placement. This command does not set that role.
+    `,
+    });
     /** Deprecation notice for a retired subcommand — STDERR only, so a --json consumer's stdout stays parseable. */
     const configTombstoneNotice = (retired, replacement) => {
         console.error(chalk.yellow(`Deprecated: "agents devices ${retired}" is now "agents devices ${replacement}". Running that for you.\n`));
@@ -1493,12 +1753,19 @@ function registerDevicesCommands(program) {
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         if (opts.json) {
+            const jsonRoles = listConfiguredDeviceRoles(names);
+            const autoPool = new Set(filterAutoPool(names, { roles: jsonRoles }));
             process.stdout.write(JSON.stringify(names.map((name) => {
                 const config = deviceConfigJson(name);
                 const health = statsMap?.get(name);
                 return {
                     ...resolveDeviceProfile(reg[name]),
                     interactive: name === interactiveHost,
+                    // Roles as machine-readable fields: `role` is what the operator
+                    // marked (absent when unmarked), `autoPool` is the answer that
+                    // matters to a caller — may `--device auto` pick this box.
+                    ...(jsonRoles[name] ? { role: jsonRoles[name] } : {}),
+                    autoPool: autoPool.has(name),
                     ...(config ? { config } : {}),
                     ...(health ? { health: { ...health, headroom: headroom(health) } } : {}),
                 };
@@ -1669,6 +1936,7 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
                 user,
                 address: { via: 'manual', dnsName: isIp ? undefined : host, ip: isIp ? host : undefined },
             });
+            setDeviceDiscoveryStatus(name, 'approved');
             console.log(chalk.green(`Added device '${name}'`) + chalk.gray(` (${d.platform}, ${user ? user + '@' : ''}${host})`));
         }
         catch (err) {
@@ -1740,6 +2008,7 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
             const existing = await getDevice(name);
             if (existing) {
                 await upsertDevice(name, { role: 'control' });
+                setDeviceDiscoveryStatus(name, 'approved');
                 marked = true;
             }
             else {
@@ -1774,6 +2043,7 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
             console.error(chalk.red(`Unknown device '${name}'.`));
             process.exit(1);
         }
+        setDeviceDiscoveryStatus(name, undefined);
         console.log(chalk.green(`Removed device '${name}'`));
     });
     devicesCmd
@@ -1949,7 +2219,7 @@ is refused with a clear message instead of self-dialing.
 An interactive login with no command mirrors the home-relative directory you
 launched from — 'agents ssh yosemite-s0' from ~/src/app lands in ~/src/app on
 the target when it exists, else the remote home. Same portable-cwd rule as
-'agents run --host'. Passing a command keeps the remote home.
+'agents run --device'. Passing a command keeps the remote home.
 `)
         .action(async (name, cmd) => {
         // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
@@ -2012,7 +2282,7 @@ the target when it exists, else the remote home. Same portable-cwd rule as
             const pinned = addr ? isHostPinned(addr) : false;
             // Interactive login (no cmd): mirror the caller's project directory on
             // the target when the same home-relative checkout exists there, matching
-            // `agents run --host` (deriveMirroredCwd). Best-effort — a missing dir
+            // `agents run --device` (deriveMirroredCwd). Best-effort — a missing dir
             // falls back to the remote home. An explicit `cmd` keeps its cwd (RUSH-2412).
             const mirrorCwd = cmd.length === 0 ? deriveMirroredCwd(process.cwd()) : undefined;
             const { args, env } = buildSshInvocation(device, cmd, shim, { pinned }, { interactiveCwd: mirrorCwd });

package/dist/commands/subagents.js

@@ -14,7 +14,7 @@ import { homeDir } from '../lib/platform/index.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
-import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
+import { listInstalledVersions, syncResourcesToVersion, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/installations/versions.js';
 import { getSubagentsDir, recordVersionResources } from '../lib/state.js';
 import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';