@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/commands/skills.js

@@ -7,8 +7,8 @@ import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
+import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/plugins/skills.js';
+import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/installations/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
@@ -180,7 +180,7 @@ Examples:
                     const skillMdPath = path.join(localPath, 'SKILL.md');
                     if (fs.existsSync(skillMdPath)) {
                         const skillName = path.basename(localPath);
-                        const { validateSkillMetadata, countSkillRules } = await import('../lib/skills.js');
+                        const { validateSkillMetadata, countSkillRules } = await import('../lib/plugins/skills.js');
                         const parseResult = tryParseSkillMetadata(localPath);
                         const validation = validateSkillMetadata(parseResult.metadata, skillName);
                         // Warn if YAML is invalid

package/dist/commands/snapshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process consumer snapshot for pollers.
+ * `agents devices snapshot` — one-process consumer snapshot for pollers.
  *
  * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
  * fork storm with a single command. Does NOT replace `agents status`, which
@@ -8,4 +8,4 @@
  * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
  */
 import type { Command } from 'commander';
-export declare function registerSnapshotCommand(program: Command): void;
+export declare function registerSnapshotCommand(devicesCmd: Command): void;

package/dist/commands/snapshot.js

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process consumer snapshot for pollers.
+ * `agents devices snapshot` — one-process consumer snapshot for pollers.
  *
  * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
  * fork storm with a single command. Does NOT replace `agents status`, which
@@ -59,11 +59,11 @@ function renderHuman(snap) {
                 : 'system ok';
         console.log(`  ${'Sync'.padEnd(12)} ${sys} · ${need} version${need === 1 ? '' : 's'} need sync`);
     }
-    console.log(chalk.gray('\n  Machine-readable: agents snapshot --json\n' +
+    console.log(chalk.gray('\n  Machine-readable: agents devices snapshot --json\n' +
         '  Sync-only (unchanged): agents status --json'));
 }
-export function registerSnapshotCommand(program) {
-    const cmd = addHostOption(program
+export function registerSnapshotCommand(devicesCmd) {
+    const cmd = addHostOption(devicesCmd
         .command('snapshot')
         .description('One-process poll snapshot: install inventory + active sessions (optional feed/sync). Not the sync-status command — use `agents status` for drift.'))
         .option('--json', 'Emit the machine-readable FleetSnapshot contract (version 1)')
@@ -74,19 +74,19 @@ export function registerSnapshotCommand(program) {
     setHelpSections(cmd, {
         examples: `
       # One-shot inventory + local active sessions (JSON)
-      agents snapshot --json
+      agents devices snapshot --json
 
       # Same, plus open feed blocks for needs-you polls
-      agents snapshot --json --with-feed
+      agents devices snapshot --json --with-feed
 
       # Fleet-wide active sessions (matches sessions --active scope)
-      agents snapshot --json --all-hosts
+      agents devices snapshot --json --all-hosts
 
       # Inventory for one harness only (an AGI EXT-style usage poll)
-      agents snapshot --json --agent claude
+      agents devices snapshot --json --agent claude
 
       # Run the whole snapshot on another device
-      agents snapshot --json --host yosemite-s0
+      agents devices snapshot --json --device yosemite-s0
     `,
     });
     cmd.action(async (opts, command) => {

package/dist/commands/ssh.d.ts

@@ -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 type { Command } from 'commander';
 import { type FanOutDeviceTarget } from '../lib/devices/fleet.js';

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,6 +55,7 @@ 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, autoPoolMode, configuredDeviceRole, listConfiguredDeviceRoles, setConfiguredDeviceRole, } from '../lib/device-config.js';
@@ -62,7 +64,7 @@ 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
@@ -78,7 +80,9 @@ 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') : '';
-    const role = roleTag(d.name, listConfiguredDeviceRoles());
+    // `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 —
@@ -119,9 +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));
-    const deviceRoles = listConfiguredDeviceRoles();
+    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)) +
@@ -319,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,
@@ -435,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;
     }
@@ -982,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'] },
@@ -1001,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}`);
         }
@@ -1016,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());
@@ -1027,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})`));
         }
@@ -1037,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`."));
         }
@@ -1054,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) ────────────────────────────
@@ -1094,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}`)}`);
@@ -1114,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')
@@ -1130,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) {
@@ -1149,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;
@@ -1159,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;
         }
@@ -1180,22 +1266,26 @@ function registerDevicesCommands(program) {
      * 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 the SHARED block (`fleet.devices.<name>.config.role`)
-     * because every box has to agree on it. 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.
+     * 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 roles = listConfiguredDeviceRoles();
-            const mode = autoPoolMode();
             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);
@@ -1240,12 +1330,17 @@ function registerDevicesCommands(program) {
         // 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() });
+            writeJson({ device: name, role, autoPoolWorkers: listWorkerDevices({ roles }) });
             return;
         }
         console.log(chalk.green(`Marked '${name}' role=${role}.`));
-        const workers = listWorkerDevices();
+        const workers = listWorkerDevices({ roles });
         if (workers.length > 0) {
             console.log(chalk.gray(`\`--device auto\` now picks only from: ${workers.join(', ')}`));
         }
@@ -1254,7 +1349,9 @@ function registerDevicesCommands(program) {
         }
         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. */
+    /** 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__';
@@ -1262,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)');
@@ -1317,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) {
@@ -1335,10 +1443,13 @@ 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
@@ -1347,26 +1458,33 @@ function registerDevicesCommands(program) {
       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: role (worker|personal), see 'agents devices role',
       agents.max-concurrent, scheduler.enabled, daemon.enabled,
-      watchdog.enabled, tmux.enabled, browser.remote-control, browser.profile,
+      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 a PEER reads land in ~/.agents/agents.yaml under
-      fleet.devices.<name>.config and sync with 'agents repo push/pull'. The
-      keys only the owning box reads — scheduler.enabled, daemon.enabled,
-      tmux.enabled, browser.remote-control, browser.profile — stay in that
-      machine's own doc, never sync, and can only be set on the device itself.
-      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.
@@ -1397,9 +1515,10 @@ function registerDevicesCommands(program) {
       agents devices role --json                   # machine-readable
     `,
         notes: `
-      Roles are stored fleet-wide in ~/.agents/agents.yaml under
-      fleet.devices.<name>.config.role and travel with 'agents repo push/pull',
-      so a mark set on one box is the whole fleet's answer.
+      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):
@@ -1634,7 +1753,7 @@ function registerDevicesCommands(program) {
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         if (opts.json) {
-            const jsonRoles = listConfiguredDeviceRoles();
+            const jsonRoles = listConfiguredDeviceRoles(names);
             const autoPool = new Set(filterAutoPool(names, { roles: jsonRoles }));
             process.stdout.write(JSON.stringify(names.map((name) => {
                 const config = deviceConfigJson(name);
@@ -1817,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) {
@@ -1888,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 {
@@ -1922,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
@@ -2097,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.
@@ -2160,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 });