@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/commands/ssh.js

@@ -21,7 +21,8 @@ import { machineId } from '../lib/session/sync/config.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { registerFleetApplyAlias } from './apply.js';
-import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, setAutoLaunchEnabled, setAutoLaunchPreferred, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
+import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
+import { resolveDeviceProfile } from '../lib/devices/resolve-profile.js';
 import { collectReachabilityWriteBacks, deviceOnlineState } from '../lib/devices/reachability.js';
 import { addControlToken } from '../lib/serve/token.js';
 import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
@@ -36,6 +37,7 @@ import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentity
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
+import { isRolloutSuccess, verifyFleetRollout, } from '../lib/devices/rollout-verify.js';
 import { fleetCapacity, fmtBytes, headroom, } from '../lib/devices/health.js';
 import { buildFleetHealthReport, renderFleetMatrix, renderFleetSummary, renderFleetWarnings, } from '../lib/devices/health-report.js';
 import { loadFleetStats, readStatsCache } from '../lib/devices/stats-cache.js';
@@ -43,19 +45,24 @@ import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
 import { checkSyncStatus, countOrphans } from '../lib/drift.js';
 import { checkAllClis } from '../lib/teams/agents.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
+import { listTasks, resolveTaskRef } from '../lib/hosts/tasks.js';
+import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
+import { stopDispatchedTask } from '../lib/hosts/dispatch.js';
+import { terminalWidth, truncateToWidth } from '../lib/session/width.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 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 } from './lease.js';
-import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
+import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort, registerLeaseCommand } from './lease.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 } from '../lib/device-config.js';
-import { setHelpSections } from '../lib/help.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec } from '../lib/device-config.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 set-interactive`). */
+ * `isInteractive` marks the configured interactive host (`devices config <name> interactive.host`). */
 function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
+    d = resolveDeviceProfile(d);
     const addr = hostNameFor(d) ?? chalk.gray('no address');
     // Prefer a fresh live verdict (this run's probe, else the written-back
     // reachability) over the stale tailscale.online snapshot (RUSH-1965).
@@ -113,7 +120,9 @@ function renderDeviceTable(reg, names, self, statsMap, full = false, interactive
         chalk.gray('headroom');
     lines.push(head);
     for (const name of names) {
-        const d = reg[name];
+        // Effective profile: the operator's central config (ssh.*/platform/user)
+        // overlays the discovery record, so the table shows what would be dialed.
+        const d = resolveDeviceProfile(reg[name]);
         const isSelf = name === self;
         const marker = isSelf ? chalk.cyan('▸ ') : '  ';
         const label = isSelf ? chalk.bold.cyan(name.padEnd(16)) : chalk.bold(name.padEnd(16));
@@ -180,7 +189,7 @@ export function renderLeasedBoxesSection(boxes, nowSecs) {
             chalk.gray(fmtIdleShort(b, nowSecs).padEnd(12)) +
             chalk.gray(fmtExpiresShort(b, nowSecs)));
     }
-    lines.push(chalk.gray('  Reuse a box with `agents run --box <slug>` · stop with `agents lease stop <slug>`'));
+    lines.push(chalk.gray('  Reuse a box with `agents run --box <slug>` · stop with `agents devices lease stop <slug>`'));
     return lines;
 }
 /** The leased-box rows for the devices list, or [] when crabbox can't be read. */
@@ -309,26 +318,51 @@ async function runInteractiveDeviceSync() {
     ].filter(Boolean);
     console.log(parts.join(chalk.gray(' · ')));
 }
-/** Print a per-device result table for fleet update/run. */
-function printFleetResults(results) {
+/**
+ * Print a per-device result table for fleet update/run.
+ *
+ * `verifications` is supplied only by the rollout (`agents fleet update`), which
+ * re-probes what `agents` resolves to on each upgraded box. A box that upgraded
+ * with `exit 0` but still resolves to another copy — the dev-install shadow of
+ * RUSH-2446 — is rendered `stale` / `unverified`, counted as **not upgraded**,
+ * and makes the command exit non-zero. An `exit 0` alone never reads as `ok` on
+ * a rollout again.
+ */
+function printFleetResults(results, verifications) {
     const nameW = Math.max(8, ...results.map((r) => r.name.length));
     console.log(chalk.bold('DEVICE'.padEnd(nameW)) + '  ' +
-        chalk.bold('STATUS'.padEnd(8)) + '  ' +
+        chalk.bold('STATUS'.padEnd(10)) + '  ' +
         chalk.bold('DETAIL'));
+    let notUpgraded = 0;
     for (const r of results) {
-        const status = r.status === 'ok' ? chalk.green('ok'.padEnd(8)) :
-            r.status === 'skipped' ? chalk.gray('skipped'.padEnd(8)) :
-                chalk.red('failed'.padEnd(8));
+        const verified = r.status === 'ok' ? verifications?.get(r.name) : undefined;
+        if (verified && !isRolloutSuccess(verified.verdict))
+            notUpgraded++;
+        const label = r.status === 'skipped' ? chalk.gray('skipped'.padEnd(10)) :
+            r.status === 'failed' ? chalk.red('failed'.padEnd(10)) :
+                verified === undefined ? chalk.green('ok'.padEnd(10)) :
+                    verified.verdict === 'on-target' ? chalk.green('ok'.padEnd(10)) :
+                        verified.verdict === 'unverified' ? chalk.yellow('unverified'.padEnd(10)) :
+                            chalk.red('stale'.padEnd(10));
         const detail = r.status === 'skipped' ? chalk.gray(skipLabel(r.reason)) :
             r.status === 'failed' ? chalk.red(r.detail || `exit ${r.code ?? '?'}`) :
-                chalk.gray(r.code === 0 ? 'exit 0' : '');
-        console.log(`${r.name.padEnd(nameW)}  ${status}  ${detail}`);
+                verified === undefined ? chalk.gray(r.code === 0 ? 'exit 0' : '') :
+                    verified.verdict === 'on-target' ? chalk.gray(verified.detail) :
+                        verified.verdict === 'unverified' ? chalk.yellow(verified.detail) :
+                            chalk.red(verified.detail);
+        console.log(`${r.name.padEnd(nameW)}  ${label}  ${detail}`);
     }
-    const ok = results.filter((r) => r.status === 'ok').length;
     const failed = results.filter((r) => r.status === 'failed').length;
     const skipped = results.filter((r) => r.status === 'skipped').length;
-    console.log(chalk.gray(`${ok} ok · ${failed} failed · ${skipped} skipped`));
-    if (failed > 0)
+    const ok = results.filter((r) => r.status === 'ok').length - notUpgraded;
+    const parts = [`${ok} ok`, `${failed} failed`, `${skipped} skipped`];
+    if (verifications)
+        parts.splice(1, 0, `${notUpgraded} not upgraded`);
+    console.log(chalk.gray(parts.join(' · ')));
+    if (notUpgraded > 0) {
+        console.log(chalk.yellow('A box that upgraded but still resolves elsewhere runs OLD code — remove the stale install that owns the `agents` name on that box, or reorder PATH. `agents doctor` names it.'));
+    }
+    if (failed > 0 || notUpgraded > 0)
         process.exitCode = 1;
 }
 async function localHealthRow(self, stats) {
@@ -386,6 +420,16 @@ async function probeRemoteHealth(target) {
         inventory: parsed.fleet,
     };
 }
+/** Effective device-scoped config, 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)
+            continue;
+        config[entry.spec.yamlKey] = entry.value;
+    }
+    return Object.keys(config).length > 0 ? config : undefined;
+}
 async function runFleetStatus(opts) {
     const reg = await loadDevices();
     const self = machineId();
@@ -418,7 +462,7 @@ async function runFleetStatus(opts) {
     const remoteTargets = remoteFleetTargets(planned, self)
         .map((t) => ({
         name: t.device.name,
-        platform: t.device.platform,
+        platform: resolveDeviceProfile(t.device).platform,
         // Fail fast: gate the expensive version+doctor dials on the reachability
         // verdict the cheap stats probe already computed one step earlier. A box
         // it found unreachable skips straight to an `unreachable` row instead of
@@ -513,7 +557,20 @@ async function runFleetStatus(opts) {
     }
     const report = buildFleetHealthReport(rows, new Date(), { self });
     if (opts.json) {
-        console.log(JSON.stringify(report, null, 2));
+        const interactiveHost = getConfigValue('interactive.host').value;
+        console.log(JSON.stringify({
+            ...report,
+            devices: report.devices.map((row) => {
+                const registered = reg[row.name];
+                const config = deviceConfigJson(row.name);
+                return {
+                    ...row,
+                    profile: registered ? resolveDeviceProfile(registered) : { name: row.name },
+                    interactive: row.name === interactiveHost,
+                    ...(config ? { config } : {}),
+                };
+            }),
+        }, null, 2));
     }
     else if (opts.verbose) {
         // Full grid: the auth/CLI/sync/version columns and the warnings rollup.
@@ -575,11 +632,10 @@ export async function raceFleetPingDeadline(fanOut, remoteTargets, overallTimeou
 }
 async function runFleetPing(opts) {
     const self = machineId();
-    const cliVersion = getCliVersion();
+    const { refreshLocalFleetAuthState } = await import('../lib/daemon-ticks.js');
     // --local: probe just this host. Used both directly and as the fan-out worker.
     if (opts.local) {
-        const rows = await probeLocalFleetAuth({ cliVersion });
-        writeFleetAuthRows(self, rows);
+        const { authRows: rows } = await refreshLocalFleetAuthState();
         if (opts.json) {
             console.log(JSON.stringify({ host: self, rows }));
         }
@@ -596,12 +652,11 @@ async function runFleetPing(opts) {
     const reg = await loadDevices();
     const planned = planFleetTargets(reg);
     const results = [];
-    const localRows = await probeLocalFleetAuth({ cliVersion });
-    writeFleetAuthRows(self, localRows);
+    const { authRows: localRows } = await refreshLocalFleetAuthState();
     results.push({ host: self, rows: localRows });
     const remoteTargets = remoteFleetTargets(planned, self).map((t) => ({
         name: t.device.name,
-        platform: t.device.platform,
+        platform: resolveDeviceProfile(t.device).platform,
         skip: t.skip,
         dialTarget: fleetDialTarget(t.device),
         extraSshArgs: deviceIdentityArgs(t.device),
@@ -671,7 +726,7 @@ async function probeRemoteHarnesses(target, refresh) {
  * the local and remote rows. Bounded by the same per-device + overall deadlines
  * as `fleet ping`, so one unreachable box can never stall the glance.
  */
-async function collectFleetHarnesses(opts) {
+export async function collectFleetHarnesses(opts) {
     const self = machineId();
     const want = opts.devices?.length ? new Set(opts.devices) : null;
     const results = [];
@@ -683,7 +738,7 @@ async function collectFleetHarnesses(opts) {
     const planned = planFleetTargets(reg);
     let remoteTargets = remoteFleetTargets(planned, self).map((t) => ({
         name: t.device.name,
-        platform: t.device.platform,
+        platform: resolveDeviceProfile(t.device).platform,
         skip: t.skip,
         dialTarget: fleetDialTarget(t.device),
         extraSshArgs: deviceIdentityArgs(t.device),
@@ -736,7 +791,7 @@ async function runDevicesHarnesses(opts) {
         for (const line of renderHarnessMatrix(results))
             console.log(line);
 }
-async function runDevicesAccounts(opts) {
+export async function runDevicesAccounts(opts) {
     if (opts.local) {
         const rows = await collectLocalHarnessInventory({ agents: opts.agents, refresh: opts.refresh });
         if (opts.json)
@@ -880,26 +935,45 @@ function registerDevicesCommands(program) {
     const devicesCmd = program
         .command('devices')
         .alias('fleet')
-        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.')
-        .addHelpText('after', `
-Typical workflow:
-  agents devices sync            # curate: pick which tailscale nodes to keep (TTY)
-  agents devices sync --yes      # non-interactive: register all non-ignored nodes
-  agents devices list            # see what's registered (★ = interactive host)
-  agents devices ignore ipad165  # dismiss a node so it's never re-suggested
-  agents devices disable zion    # exclude a device from Factory auto-launch
-  agents devices prefer mac-mini # boost a device in Factory auto-launch ranking
-  agents devices set-interactive zion        # where agents show YOU artifacts
-  agents devices configure mac-mini --max-agents 4 --scheduler off
-  agents devices note mac-mini "runs the releases — don't reboot"
-  agents devices set win-mini --auth password --bundle muqsit
-  agents devices set worker --auth key --identity-file ~/.ssh/worker_ed25519
-  agents devices render --write  # write ~/.ssh/config.d/agents include
-  agents fleet update            # roll out latest agents-cli to every online device
-  agents fleet run uname -a      # run a command on every online device
+        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.');
+    setHelpSections(devicesCmd, {
+        examples: `
+      Discover & register:
+        agents devices sync            # pick which tailscale nodes to keep (TTY)
+        agents devices sync --yes      # register all non-ignored nodes
+        agents devices ignore ipad165  # dismiss a node so it's never re-suggested
+
+      Inspect:
+        agents devices list            # what's registered (★ = interactive host)
+        agents devices status          # live reachability + load
+        agents devices ping            # quick liveness probe
+        agents devices lease list      # disposable crabbox devices available for reuse
+
+      Configure a device:
+        agents devices config mac-mini                       # settings menu (TTY) / print (piped)
+        agents devices config mac-mini agents.max-concurrent 4
+        agents devices config mac-mini scheduler.enabled off
+        agents devices config mac-mini notes "runs the releases"
+        agents devices config win-mini ssh.auth password
+        agents devices config worker ssh.identity-file ~/.ssh/worker_ed25519
+        agents devices config mac-mini auto-launch.enabled off
+        agents devices config mac-mini interactive.host zion # where agents show YOU artifacts
+        agents devices render --write  # write ~/.ssh/config.d/agents include
 
-\`agents fleet\` is an alias for \`agents devices\` — same subcommands.
-`);
+      Fleet operations:
+        agents fleet update              # roll out latest agents-cli everywhere
+        agents fleet run uname -a        # run a command on every online device
+    `,
+        notes: '`agents fleet` is an alias for `agents devices` — same subcommands.',
+    });
+    registerLeaseCommand(devicesCmd);
+    registerCommandGroups(devicesCmd, [
+        { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'rm'] },
+        { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts'] },
+        { title: 'Disposable devices', names: ['lease'] },
+        { title: 'Configure a device', names: ['config', 'render'] },
+        { title: 'Fleet operations', names: ['update', 'run', 'login', 'pair-ios', 'capture', 'apply'] },
+    ]);
     devicesCmd
         .command('sync')
         .description('Ingest `tailscale status --json` into device profiles. In a terminal, opens a checkbox to register/unregister nodes; with --yes, registers every non-ignored node.')
@@ -972,14 +1046,247 @@ Typical workflow:
         }
         console.log(chalk.green(`No longer ignoring '${name}'`) + chalk.gray(' — run `agents devices sync` to register it.'));
     });
+    // ─── devices config (unified settings surface) ────────────────────────────
+    //
+    // ONE command for every per-device setting: `agents devices config <name>
+    // [key] [value] [--unset] [--json]`. The retired subcommands (configure,
+    // note, set-interactive, set, enable/disable/prefer/unprefer) are hidden
+    // tombstones below — each prints a deprecation notice on STDERR (so a --json
+    // consumer's stdout stays parseable) and delegates to this same engine,
+    // preserving its old output shape and exit codes.
+    /** Parse a raw CLI string into a config key's typed value (bool/int pass validation, strings verbatim). */
+    const parseConfigValueInput = (spec, raw) => {
+        switch (spec.type) {
+            case 'int': {
+                const n = Number(raw);
+                if (!Number.isInteger(n))
+                    throw new Error(`Config key '${spec.name}' expects an integer, got '${raw}'.`);
+                return n;
+            }
+            case 'bool': {
+                if (raw === 'on' || raw === 'true')
+                    return true;
+                if (raw === 'off' || raw === 'false')
+                    return false;
+                throw new Error(`Config key '${spec.name}' expects on/off (or true/false), got '${raw}'.`);
+            }
+            default:
+                return raw;
+        }
+    };
+    const writeJson = (payload) => {
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    };
+    /** The device-scope config entries for `name` (what the config surface edits). */
+    const deviceConfigEntries = (name) => listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
+    /** 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;
+            writeJson({ device: name, config });
+            return;
+        }
+        console.log(chalk.bold(`Config for '${name}'`));
+        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}`)}`);
+        }
+    };
+    /**
+     * 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.
+     */
+    const runDevicesConfig = async (name, key, valueParts, opts) => {
+        const spec = key ? configKeySpec(key) : undefined; // unknown key → throw listing the valid keys
+        // 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')
+            await mustGetDevice(name);
+        if (opts.unset) {
+            if (!spec)
+                throw new Error('--unset needs a key: agents devices config <name> <key> --unset');
+            unsetConfigValue(spec.name, { device: name });
+            if (opts.quiet)
+                return;
+            if (opts.json)
+                writeJson({ device: name, key: spec.name, value: null });
+            else
+                console.log(chalk.green(`Unset ${spec.name}`) + chalk.gray(` on '${name}' — back to the default.`));
+            return;
+        }
+        if (spec && valueParts.length > 0) {
+            let value;
+            if (spec.type === 'string-list') {
+                // List keys (notes) APPEND — one entry per invocation.
+                const existing = getConfigValue(spec.name, { device: name }).value ?? [];
+                value = [...existing, valueParts.join(' ')];
+            }
+            else {
+                value = parseConfigValueInput(spec, valueParts.join(' '));
+            }
+            setConfigValue(spec.name, value, { device: name });
+            if (opts.quiet)
+                return;
+            if (opts.json)
+                writeJson({ device: name, key: spec.name, value });
+            else
+                console.log(chalk.green(`Set ${spec.name} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
+            return;
+        }
+        if (spec) {
+            const entry = getConfigValue(spec.name, { device: name });
+            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}`)}`);
+            }
+            else {
+                console.log(`  ${spec.name.padEnd(24)} ${chalk.cyan(JSON.stringify(entry.value))}${chalk.gray(`  ${spec.description}`)}`);
+            }
+            return;
+        }
+        // Bare: TTY → the interactive settings menu; piped/--json → print.
+        if (opts.json || !isInteractiveTerminal()) {
+            printDevicesConfig(name, Boolean(opts.json));
+            return;
+        }
+        await runDevicesConfigMenu(name);
+    };
+    /** The interactive settings menu: pick a key, edit it, repeat. TTY-only. */
+    const runDevicesConfigMenu = async (name) => {
+        const { select, input, confirm } = await import('@inquirer/prompts');
+        const DONE = '__done__';
+        try {
+            for (;;) {
+                const entries = deviceConfigEntries(name);
+                const picked = await select({
+                    message: `Config for '${name}' — pick a key to edit:`,
+                    pageSize: Math.min(entries.length + 1, 20),
+                    choices: [
+                        ...entries.map((e) => {
+                            const value = e.value !== undefined
+                                ? chalk.cyan(JSON.stringify(e.value))
+                                : chalk.gray(e.spec.defaultValue !== undefined
+                                    ? `default: ${JSON.stringify(e.spec.defaultValue)}`
+                                    : 'unset (default)');
+                            return { value: e.spec.name, name: `${e.spec.name.padEnd(24)} ${value}  ${chalk.gray(e.spec.description)}` };
+                        }),
+                        { value: DONE, name: 'Done' },
+                    ],
+                });
+                if (picked === DONE)
+                    return;
+                const spec = configKeySpec(picked);
+                if (spec.type === 'bool') {
+                    const current = getConfigValue(picked, { device: name }).value;
+                    const next = await confirm({
+                        message: `${picked} — enable?`,
+                        default: current ?? spec.defaultValue ?? true,
+                    });
+                    setConfigValue(picked, next, { device: name });
+                    console.log(chalk.green(`Set ${picked} = ${next}`) + chalk.gray(` on '${name}'.`));
+                }
+                else if (spec.type === 'string-list') {
+                    const text = await input({ message: `${picked} — append an entry (empty to go back):` });
+                    if (text.trim().length > 0) {
+                        const existing = getConfigValue(picked, { device: name }).value ?? [];
+                        setConfigValue(picked, [...existing, text.trim()], { device: name });
+                        console.log(chalk.green(`Noted on '${name}':`) + ` ${text.trim()}`);
+                    }
+                }
+                else {
+                    const current = getConfigValue(picked, { device: name }).value;
+                    const raw = await input({
+                        message: `${picked}:`,
+                        default: current === undefined ? undefined : String(current),
+                    });
+                    if (raw.trim().length === 0)
+                        continue;
+                    const value = parseConfigValueInput(spec, raw.trim());
+                    setConfigValue(spec.name, value, { device: name });
+                    console.log(chalk.green(`Set ${spec.name} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
+                }
+            }
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return; // ctrl-c / esc — leave the menu quietly
+            throw err;
+        }
+    };
+    const configCmd = devicesCmd
+        .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')
+        .action(async (name, key, valueParts, opts) => {
+        try {
+            await runDevicesConfig(name, key, valueParts ?? [], opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    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 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 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 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
+    `,
+        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,
+      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).
+
+      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.
+
+      The retired subcommands still work and forward here: configure, note,
+      set, set-interactive, enable, disable, prefer, unprefer.
+    `,
+    });
+    /** 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`));
+    };
     devicesCmd
-        .command('enable <name>')
-        .description('Allow a registered device to be auto-picked by Factory agent launches.')
+        .command('enable <name>', { hidden: true })
         .action(async (name) => {
         try {
+            configTombstoneNotice('enable <name>', 'config <name> auto-launch.enabled on');
             await mustGetDevice(name);
-            await setAutoLaunchEnabled(name, true);
-            console.log(chalk.green(`Enabled '${name}'`) + chalk.gray(' for Factory auto-launch.'));
+            // Back to the default (enabled) = remove the key.
+            await runDevicesConfig(name, 'auto-launch.enabled', [], { unset: true, quiet: true });
+            console.log(chalk.green(`Enabled '${name}'`) + chalk.gray(' for AGI EXT auto-launch.'));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -987,13 +1294,13 @@ Typical workflow:
         }
     });
     devicesCmd
-        .command('disable <name>')
-        .description('Exclude a registered device from Factory auto-launch. It can still be picked manually via (Pick Host).')
+        .command('disable <name>', { hidden: true })
         .action(async (name) => {
         try {
+            configTombstoneNotice('disable <name>', 'config <name> auto-launch.enabled off');
             await mustGetDevice(name);
-            await setAutoLaunchEnabled(name, false);
-            console.log(chalk.green(`Disabled '${name}'`) + chalk.gray(' for Factory auto-launch.'));
+            await runDevicesConfig(name, 'auto-launch.enabled', ['off'], { quiet: true });
+            console.log(chalk.green(`Disabled '${name}'`) + chalk.gray(' for AGI EXT auto-launch.'));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -1001,13 +1308,13 @@ Typical workflow:
         }
     });
     devicesCmd
-        .command('prefer <name>')
-        .description('Boost a registered device in Factory auto-launch ranking.')
+        .command('prefer <name>', { hidden: true })
         .action(async (name) => {
         try {
+            configTombstoneNotice('prefer <name>', 'config <name> auto-launch.preferred on');
             await mustGetDevice(name);
-            await setAutoLaunchPreferred(name, true);
-            console.log(chalk.green(`Preferred '${name}'`) + chalk.gray(' for Factory auto-launch.'));
+            await runDevicesConfig(name, 'auto-launch.preferred', ['on'], { quiet: true });
+            console.log(chalk.green(`Preferred '${name}'`) + chalk.gray(' for AGI EXT auto-launch.'));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -1015,30 +1322,31 @@ Typical workflow:
         }
     });
     devicesCmd
-        .command('unprefer <name>')
-        .description('Remove the auto-launch preference boost from a device.')
+        .command('unprefer <name>', { hidden: true })
         .action(async (name) => {
         try {
+            configTombstoneNotice('unprefer <name>', 'config <name> auto-launch.preferred off');
             await mustGetDevice(name);
-            await setAutoLaunchPreferred(name, false);
-            console.log(chalk.green(`No longer preferring '${name}'`) + chalk.gray(' for Factory auto-launch.'));
+            // Back to the default (not preferred) = remove the key.
+            await runDevicesConfig(name, 'auto-launch.preferred', [], { unset: true, quiet: true });
+            console.log(chalk.green(`No longer preferring '${name}'`) + chalk.gray(' for AGI EXT auto-launch.'));
         }
         catch (err) {
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
-    const setInteractiveCmd = devicesCmd
-        .command('set-interactive [name]')
-        .description('Get or set the interactive host — the one device that shows YOU artifacts (browser opens, dashboards, rendered plans). Stored fleet-wide as config.interactiveHost in central agents.yaml.')
+    devicesCmd
+        .command('set-interactive [name]', { hidden: true })
         .option('--unset', 'clear the interactive host')
         .option('--json', 'output machine-readable JSON')
         .action(async (name, opts) => {
         try {
+            configTombstoneNotice('set-interactive [name]', 'config <name> interactive.host <name>');
             if (opts.unset) {
                 unsetConfigValue('interactive.host');
                 if (opts.json)
-                    process.stdout.write(JSON.stringify({ interactiveHost: null }, null, 2) + '\n');
+                    writeJson({ interactiveHost: null });
                 else
                     console.log(chalk.green('Cleared the interactive host.'));
                 return;
@@ -1047,20 +1355,20 @@ Typical workflow:
                 await mustGetDevice(name);
                 setConfigValue('interactive.host', name);
                 if (opts.json)
-                    process.stdout.write(JSON.stringify({ interactiveHost: name }, null, 2) + '\n');
+                    writeJson({ interactiveHost: name });
                 else
                     console.log(chalk.green(`Interactive host: '${name}'`) + chalk.gray(' — agents show you artifacts there. Clear with --unset.'));
                 return;
             }
             const current = getConfigValue('interactive.host').value;
             if (opts.json) {
-                process.stdout.write(JSON.stringify({ interactiveHost: current ?? null }, null, 2) + '\n');
+                writeJson({ interactiveHost: current ?? null });
             }
             else if (current) {
                 console.log(`${chalk.bold('Interactive host:')} ${chalk.cyan(current)}`);
             }
             else {
-                console.log(chalk.gray("No interactive host set. Set one with 'agents devices set-interactive <name>'."));
+                console.log(chalk.gray("No interactive host set. Set one with 'agents devices config <name> interactive.host <name>'."));
             }
         }
         catch (err) {
@@ -1068,123 +1376,65 @@ Typical workflow:
             process.exit(1);
         }
     });
-    setHelpSections(setInteractiveCmd, {
-        examples: `
-      agents devices set-interactive zion      # zion is where artifacts open for you
-      agents devices set-interactive           # print the current interactive host
-      agents devices set-interactive --unset   # back to no interactive host
-      agents devices set-interactive --json    # machine-readable (for skills)
-    `,
-        notes: `
-      The interactive host answers "which online macOS device do I show this on?"
-      so skills stop guessing. It is marked ★ interactive in 'agents devices list'.
-      The value syncs fleet-wide (central agents.yaml, config.interactiveHost);
-      per-device settings live under 'agents devices configure' instead.
-    `,
-    });
-    const configureCmd = devicesCmd
-        .command('configure <name>')
-        .description('Get or set per-device config: --max-agents, --scheduler. Written to ~/.agents/devices/<name>/agents.yaml (works for any device — the devices/ tree syncs). Unset = default behavior.')
-        .option('--max-agents <n>', 'cap concurrent agents (Factory auto-launch counts device-wide; teams placement counts the team’s roster on the device)')
-        .option('--scheduler <on|off>', 'allow the routines scheduler (daemon) to fire on this device (takes effect on daemon reload/restart)')
+    devicesCmd
+        .command('configure <name>', { hidden: true })
+        .option('--max-agents <n>', 'cap concurrent agents')
+        .option('--scheduler <on|off>', 'allow the routines scheduler (daemon) to fire on this device')
         .option('--json', 'output machine-readable JSON')
         .action(async (name, opts) => {
         try {
+            configTombstoneNotice('configure <name> [--max-agents N] [--scheduler on|off]', 'config <name> <key> <value>');
             await mustGetDevice(name);
-            const parseOnOff = (flag, raw) => {
-                if (raw === 'on')
-                    return true;
-                if (raw === 'off')
-                    return false;
-                throw new Error(`--${flag} expects 'on' or 'off', got '${raw}'.`);
-            };
             const writes = [];
-            if (opts.maxAgents !== undefined) {
-                const n = Number(opts.maxAgents);
-                if (!Number.isInteger(n))
-                    throw new Error(`--max-agents expects an integer, got '${opts.maxAgents}'.`);
-                writes.push(['agents.max-concurrent', n]);
-            }
-            if (opts.scheduler !== undefined)
-                writes.push(['scheduler.enabled', parseOnOff('scheduler', opts.scheduler)]);
-            if (writes.length > 0) {
-                for (const [key, value] of writes)
-                    setConfigValue(key, value, { device: name });
-                if (!opts.json) {
-                    for (const [key, value] of writes) {
-                        console.log(chalk.green(`Set ${key} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
-                    }
+            if (opts.maxAgents !== undefined)
+                writes.push(['agents.max-concurrent', opts.maxAgents]);
+            if (opts.scheduler !== undefined) {
+                if (opts.scheduler !== 'on' && opts.scheduler !== 'off') {
+                    throw new Error(`--scheduler expects 'on' or 'off', got '${opts.scheduler}'.`);
                 }
+                writes.push(['scheduler.enabled', opts.scheduler]);
             }
-            if (opts.json || writes.length === 0) {
-                const entries = listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
-                if (opts.json) {
-                    const config = {};
-                    for (const e of entries)
-                        if (e.value !== undefined)
-                            config[e.spec.name] = e.value;
-                    process.stdout.write(JSON.stringify({ device: name, config }, null, 2) + '\n');
-                }
-                else {
-                    console.log(chalk.bold(`Config for '${name}'`));
-                    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}`)}`);
-                    }
-                }
+            for (const [key, value] of writes) {
+                await runDevicesConfig(name, key, [value], { quiet: Boolean(opts.json) });
             }
+            if (opts.json)
+                printDevicesConfig(name, true);
+            else if (writes.length === 0)
+                printDevicesConfig(name, false);
         }
         catch (err) {
             console.error(chalk.red(err.message));
             process.exit(1);
         }
     });
-    setHelpSections(configureCmd, {
-        examples: `
-      agents devices configure mac-mini --max-agents 4      # cap concurrent agents
-      agents devices configure mac-mini --scheduler off     # no routines firing there
-      agents devices configure mac-mini                     # print its current config
-      agents devices configure mac-mini --json              # machine-readable
-    `,
-        notes: `
-      Run it on any machine for any device: the value lands in
-      ~/.agents/devices/<name>/agents.yaml locally and reaches the device on the
-      next 'agents repo push/pull'. Unset keys keep today's behavior.
-      --scheduler takes effect when the daemon reloads or restarts on that
-      device ('agents routines start' / the reload a 'routines add' sends).
-      For the default browser profile use 'agents browser profiles set-default
-      <name>'; for free-form text use 'agents devices note'.
-    `,
-    });
-    const noteCmd = devicesCmd
-        .command('note <name> [text...]')
-        .description('Append a free-form note to a device (repeat to append more). No text prints the notes; --clear empties them.')
+    devicesCmd
+        .command('note <name> [text...]', { hidden: true })
         .option('--clear', 'remove all notes from the device')
         .option('--json', 'output machine-readable JSON')
         .action(async (name, text, opts) => {
         try {
+            configTombstoneNotice('note <name> [text...]', 'config <name> notes <text>');
             await mustGetDevice(name);
             if (opts.clear) {
-                unsetConfigValue('notes', { device: name });
+                await runDevicesConfig(name, 'notes', [], { unset: true, quiet: true });
                 if (opts.json)
-                    process.stdout.write(JSON.stringify({ device: name, notes: [] }, null, 2) + '\n');
+                    writeJson({ device: name, notes: [] });
                 else
                     console.log(chalk.green(`Cleared notes on '${name}'.`));
                 return;
             }
             if (text.length > 0) {
-                const existing = getConfigValue('notes', { device: name }).value ?? [];
-                const notes = [...existing, text.join(' ')];
-                setConfigValue('notes', notes, { device: name });
+                await runDevicesConfig(name, 'notes', text, { quiet: true });
+                const notes = getConfigValue('notes', { device: name }).value ?? [];
                 if (opts.json)
-                    process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+                    writeJson({ device: name, notes });
                 else
                     console.log(chalk.green(`Noted on '${name}':`) + ` ${text.join(' ')}`);
                 return;
             }
             const notes = getConfigValue('notes', { device: name }).value ?? [];
             if (opts.json) {
-                process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+                writeJson({ device: name, notes });
             }
             else if (notes.length > 0) {
                 console.log(chalk.bold(`Notes for '${name}'`));
@@ -1192,7 +1442,7 @@ Typical workflow:
                     console.log(`  ${chalk.gray('•')} ${n}`);
             }
             else {
-                console.log(chalk.gray(`No notes on '${name}'. Add one with 'agents devices note ${name} "..."'.`));
+                console.log(chalk.gray(`No notes on '${name}'. Add one with 'agents devices config ${name} notes "..."'.`));
             }
         }
         catch (err) {
@@ -1200,45 +1450,15 @@ Typical workflow:
             process.exit(1);
         }
     });
-    setHelpSections(noteCmd, {
-        examples: `
-      agents devices note mac-mini "runs the releases — don't reboot"
-      agents devices note mac-mini "4 displays attached"   # appends a second note
-      agents devices note mac-mini                         # print its notes
-      agents devices note mac-mini --clear                 # drop them all
-    `,
-        notes: `
-      Notes are operator memory for a box (why it exists, what to never do to
-      it). They sync like every other device doc; 'agents devices list --json'
-      carries them under config.notes.
-    `,
-    });
-    /** Device-scope config block for `list --json`, keyed by yamlKey (set keys only). */
-    const deviceConfigJson = (name) => {
-        const config = {};
-        for (const entry of listConfig({ device: name })) {
-            if (entry.spec.scope !== 'device' || entry.value === undefined)
-                continue;
-            config[entry.spec.yamlKey] = entry.value;
-        }
-        return Object.keys(config).length > 0 ? config : undefined;
-    };
     const runList = async (opts = {}) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
         const interactiveHost = getConfigValue('interactive.host').value;
-        if (opts.json) {
-            // Registry + local device docs, always fast — the Factory extension polls
-            // this path. Each row carries its device-scope `config` (maxAgents,
-            // schedulerEnabled, notes, defaultBrowserProfile — set keys
-            // only) and an `interactive` flag for the configured interactive host.
-            process.stdout.write(JSON.stringify(names.map((n) => {
-                const config = deviceConfigJson(n);
-                return { ...reg[n], interactive: n === interactiveHost, ...(config ? { config } : {}) };
-            }), null, 2) + '\n');
-            return;
-        }
         if (names.length === 0) {
+            if (opts.json) {
+                process.stdout.write('[]\n');
+                return;
+            }
             console.log(chalk.gray("No devices. Run 'agents devices sync' or 'agents devices add <name> <user@host>'."));
             return;
         }
@@ -1272,6 +1492,19 @@ Typical workflow:
             if (statsMap)
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(names.map((name) => {
+                const config = deviceConfigJson(name);
+                const health = statsMap?.get(name);
+                return {
+                    ...resolveDeviceProfile(reg[name]),
+                    interactive: name === interactiveHost,
+                    ...(config ? { config } : {}),
+                    ...(health ? { health: { ...health, headroom: headroom(health) } } : {}),
+                };
+            }), null, 2) + '\n');
+            return;
+        }
         console.log(chalk.bold(`Devices (${names.length})`));
         for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost))
             console.log(line);
@@ -1295,7 +1528,7 @@ Typical workflow:
         .command('list')
         .alias('ls')
         .description('List registered devices with platform, address, reachability, and live resource headroom.')
-        .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
+        .option('--json', 'output effective device profiles, config, and health as a JSON array')
         .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
         .option('--refresh', 'force a live probe of every device, bypassing the cache')
         .option('--live', 'alias of --refresh (shorter to type)')
@@ -1444,8 +1677,7 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         }
     });
     devicesCmd
-        .command('set <name>')
-        .description('Update fields on an existing device (platform, user, auth).')
+        .command('set <name>', { hidden: true })
         .option('--platform <platform>', 'windows | linux | macos')
         .option('--user <user>', 'login user')
         .option('--auth <method>', 'key | password')
@@ -1455,21 +1687,35 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         .option('--clear-identity-file', 'return key auth to ssh-agent/default-key discovery')
         .action(async (name, opts) => {
         try {
+            configTombstoneNotice('set <name> [--platform|--user|--auth|--bundle|--bundle-key|--identity-file …]', 'config <name> <ssh.*|platform> <value>');
             const existing = await mustGetDevice(name);
-            const nextMethod = opts.auth ?? existing.auth.method;
+            const nextMethod = opts.auth ?? resolveDeviceProfile(existing).auth.method;
             if (opts.identityFile && nextMethod !== 'key') {
                 throw new Error('--identity-file requires key auth; pass --auth key in the same command.');
             }
-            const auth = opts.auth || opts.bundle || opts.bundleKey || opts.identityFile || opts.clearIdentityFile
-                ? nextMethod === 'key'
-                    ? { method: nextMethod, identityFile: opts.clearIdentityFile ? undefined : (opts.identityFile ?? existing.auth.identityFile) }
-                    : { method: nextMethod, bundle: opts.bundle ?? existing.auth.bundle, bundleKey: opts.bundleKey ?? existing.auth.bundleKey }
-                : undefined;
-            const d = await upsertDevice(name, {
-                platform: opts.platform ?? undefined,
-                user: opts.user ?? undefined,
-                auth,
-            });
+            const writes = [];
+            if (opts.platform)
+                writes.push({ key: 'platform', value: opts.platform });
+            if (opts.user)
+                writes.push({ key: 'ssh.user', value: opts.user });
+            if (opts.auth)
+                writes.push({ key: 'ssh.auth', value: opts.auth });
+            if (opts.bundle)
+                writes.push({ key: 'ssh.bundle', value: opts.bundle });
+            if (opts.bundleKey)
+                writes.push({ key: 'ssh.bundle-key', value: opts.bundleKey });
+            if (opts.identityFile)
+                writes.push({ key: 'ssh.identity-file', value: opts.identityFile });
+            if (opts.clearIdentityFile)
+                writes.push({ key: 'ssh.identity-file' }); // unset
+            if (writes.length === 0) {
+                printDevicesConfig(name, false);
+                return;
+            }
+            for (const w of writes) {
+                await runDevicesConfig(name, w.key, w.value !== undefined ? [w.value] : [], { unset: w.value === undefined, quiet: true });
+            }
+            const d = resolveDeviceProfile((await mustGetDevice(name)));
             console.log(chalk.green(`Updated device '${name}'`) + chalk.gray(` (auth: ${d.auth.method}${d.auth.bundle ? ` via ${d.auth.bundle}` : ''})`));
         }
         catch (err) {
@@ -1550,8 +1796,25 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
     });
     devicesCmd
         .command('update')
-        .description('Roll out agents-cli to every online registered device (`agents upgrade --yes` on each). Offline devices are skipped.')
+        .description('Roll out agents-cli to every online registered device (`agents upgrade --yes` on each), then verify each box actually runs the new version. Offline devices are skipped.')
         .argument('[version]', 'Target version or dist-tag (default: latest)')
+        .addHelpText('after', `
+Examples:
+  agents fleet update                        # roll out latest, then verify each box
+  agents fleet update 1.22.35                # pin the target version
+  agents devices update                      # same command under the devices group
+
+After each upgrade the rollout asks the box what \`agents\` resolves to and what
+version that copy reports. A box that upgraded with exit 0 but still resolves to
+another install — a stale copy in a second node prefix, a Homebrew shim, or a
+hand-made link that sits earlier on PATH than the npm global — is reported
+\`stale\` with its resolved path, counted as NOT upgraded, and makes the command
+exit non-zero. Remove the install that owns the name, or reorder PATH on that
+box; \`agents doctor\` names it.
+
+A box whose probe cannot answer (no POSIX shell, e.g. Windows) is reported
+\`unverified\` rather than counted as a success.
+`)
         .action(async (version) => {
         let cmd;
         try {
@@ -1568,8 +1831,13 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
             return;
         }
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
-        const results = runFleet(targets, cmd, { self: machineId() });
-        printFleetResults(results);
+        const self = machineId();
+        const results = runFleet(targets, cmd, { self });
+        // `exit 0` from the upgrade only proves the npm global moved. Ask each box
+        // what `agents` actually resolves to before calling the rollout a success
+        // (RUSH-2446) — a dev install shadowing the global keeps running old code.
+        const verifications = verifyFleetRollout(targets, results, version, { self });
+        printFleetResults(results, verifications);
     });
     devicesCmd
         .command('run <cmd...>')
@@ -1590,6 +1858,74 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         const results = runFleet(targets, cmd, { self: machineId() });
         printFleetResults(results);
     });
+    devicesCmd
+        .command('ps')
+        .description('List agent tasks dispatched to devices with `agents run --device <name> --no-follow`. Reconciles each still-`running` record against the remote before listing. View a log with `agents logs <id>`.')
+        .option('--json', 'Output JSON')
+        .action((opts) => doDeviceTaskPs(!!opts.json));
+    devicesCmd
+        .command('stop <id>')
+        .alias('kill')
+        .description('Terminate a running dispatched task from this machine (SIGTERM the remote process group; marks it failed/143).')
+        .action((id) => doDeviceTaskStop(id));
+}
+/**
+ * `agents devices ps` — list tasks dispatched to devices (`agents run --device
+ * <name> --no-follow`). Heals any 'running' record whose local follower died
+ * (dropped connection, laptop sleep) against the remote `.exit` before listing,
+ * so a finished run never shows stuck at 'running'.
+ */
+async function doDeviceTaskPs(json) {
+    const tasks = reconcileRunningTasks(listTasks());
+    if (json) {
+        console.log(JSON.stringify(tasks, null, 2));
+        return;
+    }
+    if (tasks.length === 0) {
+        console.log(chalk.gray('No dispatched tasks yet. Dispatch one: agents run <agent> "<task>" --device <name> --no-follow'));
+        return;
+    }
+    const cols = terminalWidth();
+    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('NAME').padEnd(16) + chalk.bold('DEVICE').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
+    for (const t of tasks) {
+        const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
+        const nameCol = truncateToWidth(t.name ?? chalk.gray('-'), 15).padEnd(16);
+        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 16 + 10 + 11)));
+        console.log(t.id.padEnd(11) + nameCol + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
+    }
+}
+/** `agents devices stop <id>` — terminate a running dispatched task from the origin machine. */
+async function doDeviceTaskStop(ref) {
+    // Heal first so we don't try to kill a process that already exited.
+    const current = resolveTaskRef(ref);
+    if (!current) {
+        console.log(chalk.red(`Unknown task "${ref}".`));
+        process.exitCode = 1;
+        return;
+    }
+    const task = reconcileRunningTasks([current])[0] ?? current;
+    if (task.status !== 'running') {
+        console.log(chalk.gray(`Task ${task.id} is already ${task.status}` + (task.exitCode !== undefined ? ` (exit ${task.exitCode})` : '') + '.'));
+        return;
+    }
+    try {
+        const stopped = stopDispatchedTask(task);
+        const statusColor = stopped.status === 'completed' ? chalk.green : chalk.yellow;
+        const exitNote = stopped.exitCode === 143
+            ? 'exit 143 / SIGTERM'
+            : stopped.exitCode !== undefined
+                ? `exit ${stopped.exitCode}`
+                : stopped.status;
+        console.log(chalk.green(`Stopped ${stopped.id}`) +
+            chalk.gray(` on ${stopped.host}`) +
+            '  ' + statusColor(stopped.status) +
+            chalk.gray(` (${exitNote})`));
+        console.log(chalk.gray(`Logs: agents logs ${stopped.id}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err?.message ?? err));
+        process.exitCode = 1;
+    }
 }
 /** Register the `agents ssh` smart wrapper. */
 function registerSshWrapper(program) {
@@ -1644,14 +1980,17 @@ the target when it exists, else the remote home. Same portable-cwd rule as
         // `user@device` (same device, login user overridden — dialed via its
         // Tailscale route, not LAN DNS), or an ad-hoc `user@host`/`host` literal.
         // A bare unregistered alias still errors as "Unknown device".
-        const device = await resolveDeviceTarget(target);
-        if (!device) {
+        const resolvedTarget = await resolveDeviceTarget(target);
+        if (!resolvedTarget) {
             // Not a registered device — it may be a leased crabbox box slug. ssh into
             // it directly (crabbox@<tailnet|ip>:2222) before giving up.
             trySshLeasedBox(target, cmd); // exits the process on a match
             console.error(chalk.red(`Unknown device '${target}'. See 'agents devices list'.`));
             process.exit(1);
         }
+        // The effective profile: central config (ssh.*/platform/user) overlaid on
+        // the discovery record.
+        const device = resolveDeviceProfile(resolvedTarget);
         // Preflight: a device Tailscale last saw offline would otherwise hang
         // for the full ConnectTimeout. Fail fast with a clear message instead.
         if (device.tailscale && !device.tailscale.online) {