@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/device-config.js

@@ -1,31 +1,43 @@
 /**
- * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ * Device/user config keys — typed read/write over the central agents.yaml store.
  *
  * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
- *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
- *                    fleet-wide via `agents repo push/pull`)
- *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
- *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *   - user scope     → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                      fleet-wide via `agents repo push/pull`)
+ *   - device scope   → split by `visibility`, which asks WHO READS IT:
+ *       · `shared`   → central `fleet.devices.<name>.config`, because a PEER
+ *                      reads it (the ssh keys and platform to dial the box,
+ *                      agents.max-concurrent for placement, auto-launch and
+ *                      notes for fleet views). Names and non-secret values only
+ *                      (a secrets-bundle NAME is fine; a credential never is).
+ *       · `machine`  → the owning box's own doc, never the shared file, because
+ *                      nothing off-box reads it (browser.profile,
+ *                      browser.remote-control, scheduler.enabled,
+ *                      daemon.enabled).
  *
- * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
- * partition/overlay logic stays the single writer. Another device's doc is
- * read/written in place — the devices/ tree syncs via the DotAgents repo, so
- * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
- * target a peer (`--device`-style).
+ * That split exists because "central for everything" put 13 machines on one
+ * tracked path and they stopped being able to pull. `browser.remote-control` is
+ * also a consent flag — syncing one box's opt-in to the rest was a security bug,
+ * not just churn.
  *
- * `browser.profile` is NOT a `config:` key — it is the existing
- * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
- * and set/get route to it so there is one source of truth (no duplicate key).
+ * The device registry (`~/.agents/.history/devices/registry.json`) stays the
+ * DISCOVERY cache (address, tailscale snapshot, reachability); the profile
+ * fields config can override (ssh.*, platform, user) are overlaid onto it at
+ * read time by `lib/devices/resolve-profile.ts`.
  *
- * Unset always means today's behavior.
+ * Legacy stores (per-device `devices/<host>/agents.yaml` config and
+ * `.history/devices/auto-launch.json`) are folded into the central block once
+ * by `lib/devices/config-migration.ts`, invoked on the first read/write in a
+ * process — after migration there is ONE read path, no fallback branches.
+ *
+ * Unset always means today's behavior (the documented default).
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'yaml';
-import { META_HEADER, getUserAgentsDir, readMeta, updateMeta } from './state.js';
-import { atomicWriteFileSync } from './fs-atomic.js';
+import { readMeta, updateMeta } from './state.js';
 import { machineId } from './machine-id.js';
 import { assertValidDeviceName } from './devices/registry.js';
+import { fleetDevicesMapForWrite, migrateDeviceConfigToCentral } from './devices/config-migration.js';
+const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
+const SSH_AUTH_METHODS = ['key', 'password'];
 export const CONFIG_KEYS = [
     {
         name: 'interactive.host',
@@ -43,35 +55,56 @@ export const CONFIG_KEYS = [
             }
         },
     },
+    {
+        name: 'usage.primary-host',
+        yamlKey: 'usagePrimaryHost',
+        scope: 'user',
+        type: 'string',
+        description: 'Device whose usage snapshots are authoritative for fleet-wide usage reporting.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
     {
         name: 'browser.profile',
         yamlKey: 'defaultBrowserProfile',
         scope: 'device',
+        visibility: 'machine',
         type: 'string',
-        field: 'defaultBrowserProfile',
         description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser profiles set-default`).',
     },
     {
         name: 'agents.max-concurrent',
         yamlKey: 'maxAgents',
         scope: 'device',
+        visibility: 'shared',
         type: 'int',
         description: 'Cap on concurrent agents on this device. What counts toward it depends on the consumer: ' +
-            'Factory auto-launch counts device-wide running agents; teams placement counts the team’s own roster on the device.',
+            'AGI EXT auto-launch counts device-wide running agents; teams placement counts the team’s own roster on the device.',
         validate: (v) => (v >= 1 ? null : 'agents.max-concurrent must be >= 1.'),
     },
     {
         name: 'scheduler.enabled',
         yamlKey: 'schedulerEnabled',
         scope: 'device',
+        visibility: 'machine',
         type: 'bool',
+        defaultValue: true,
         description: 'Whether the routines scheduler (daemon) may fire on this device.',
     },
     {
         name: 'daemon.enabled',
         yamlKey: 'daemonEnabled',
         scope: 'device',
+        visibility: 'machine',
         type: 'bool',
+        defaultValue: true,
         description: 'Whether the daemon may run on this device at all (secrets broker, browser IPC, watchdog, and the ' +
             'routines scheduler). Disabling is the top-level kill switch: nothing auto-starts the daemon while it ' +
             'is set, including `routines add`/`routines start`/`routines catchup`/webhook triggers. ' +
@@ -81,14 +114,18 @@ export const CONFIG_KEYS = [
         name: 'watchdog.enabled',
         yamlKey: 'watchdogEnabled',
         scope: 'device',
+        visibility: 'shared',
         type: 'bool',
+        defaultValue: false,
         description: 'Whether the daemon runs the watchdog pass on this device.',
     },
     {
         name: 'browser.remote-control',
         yamlKey: 'browserRemoteControl',
         scope: 'device',
+        visibility: 'machine',
         type: 'bool',
+        defaultValue: false,
         description: "Whether other fleet machines may drive THIS device's browser over `browser --host <this-device>`. " +
             'Default off — a fleet-remote drive is refused until the owner runs `agents browser remote-control on`.',
     },
@@ -96,8 +133,81 @@ export const CONFIG_KEYS = [
         name: 'notes',
         yamlKey: 'notes',
         scope: 'device',
+        visibility: 'shared',
         type: 'string-list',
-        description: 'Free-form operator notes about this device (one entry per `agents devices note`).',
+        description: 'Free-form operator notes about this device (one entry per `agents devices config <name> notes <text>`).',
+    },
+    {
+        name: 'ssh.user',
+        yamlKey: 'sshUser',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'SSH login user for the device — overrides the registry profile’s user at dial time.',
+    },
+    {
+        name: 'ssh.auth',
+        yamlKey: 'sshAuth',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'SSH auth method: `key` (ssh agent / on-disk keys) or `password` (pulled from a secrets bundle).',
+        validate: (v) => SSH_AUTH_METHODS.includes(v)
+            ? null
+            : `ssh.auth must be one of ${SSH_AUTH_METHODS.join(' | ')}.`,
+    },
+    {
+        name: 'ssh.bundle',
+        yamlKey: 'sshBundle',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'Secrets bundle holding the SSH password (for ssh.auth=password). A bundle NAME — never a secret value.',
+    },
+    {
+        name: 'ssh.bundle-key',
+        yamlKey: 'sshBundleKey',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: "Key within the bundle whose value is the password (default 'password').",
+    },
+    {
+        name: 'ssh.identity-file',
+        yamlKey: 'sshIdentityFile',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'Explicit private-key path for key auth (passed to OpenSSH with IdentitiesOnly=yes).',
+    },
+    {
+        name: 'platform',
+        yamlKey: 'platform',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'OS family of the device — picks PowerShell vs POSIX on the remote end. Overrides the discovered platform.',
+        validate: (v) => DEVICE_PLATFORMS.includes(v)
+            ? null
+            : `platform must be one of ${DEVICE_PLATFORMS.join(' | ')}.`,
+    },
+    {
+        name: 'auto-launch.enabled',
+        yamlKey: 'autoLaunchEnabled',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'bool',
+        defaultValue: true,
+        description: 'Whether AGI EXT auto-launch may pick this device (default on).',
+    },
+    {
+        name: 'auto-launch.preferred',
+        yamlKey: 'autoLaunchPreferred',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'bool',
+        defaultValue: false,
+        description: 'Boost this device in AGI EXT auto-launch ranking (default off).',
     },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
@@ -136,159 +246,254 @@ function assertValidValue(spec, value) {
     if (err)
         throw new Error(`Invalid value for '${spec.name}': ${err}`);
 }
-// ─── Sibling-device doc access ────────────────────────────────────────────────
-/** Path to any device's doc (self or a peer) under the synced devices/ tree. */
-function deviceDocPath(device) {
-    return path.join(getUserAgentsDir(), 'devices', device, 'agents.yaml');
-}
+// ─── Migration hook ───────────────────────────────────────────────────────────
+let migrationDone = false;
 /**
- * Read a device doc directly. Returns null when the file does not exist. A
- * malformed file is a hard error — silently returning null would let the next
- * write wipe the device's pins/default (same contract as the device registry).
- * A valid-but-non-map document (a bare string, a list) is the same kind of
- * corruption: reject it here instead of failing later with a TypeError.
+ * Fold the legacy per-device config stores into the central block, once per
+ * process. A failure is loud but non-fatal — config reads must keep working,
+ * and the next process retries the fold. Honors AGENTS_SKIP_MIGRATION=1, the
+ * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
+ * the developer's real ~/.agents as a side effect).
+ *
+ * Call this ONLY from a lifecycle entry point (daemon boot, `runMigration`).
+ * It must never hang off a config read or write: `~/.agents/agents.yaml` is a
+ * tracked file shared by every machine in the fleet, so a migration on the read
+ * path means an ordinary `agents config get` can dirty the shared file. That is
+ * what left yosemite-s0 unable to pull — 13 machines each rewriting one tracked
+ * path, on nearly every command.
  */
-function readDeviceDoc(device) {
-    const p = deviceDocPath(device);
-    let raw;
-    try {
-        raw = fs.readFileSync(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return null;
-        throw err;
-    }
-    const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
-    let parsed;
+export function ensureDeviceConfigMigrated() {
+    if (migrationDone || process.env.AGENTS_SKIP_MIGRATION === '1')
+        return;
     try {
-        parsed = yaml.parse(raw);
+        migrateDeviceConfigToCentral();
+        migrationDone = true;
     }
     catch (err) {
-        throw corrupted(err?.message ?? String(err));
-    }
-    if (parsed === null || parsed === undefined)
-        return {};
-    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw corrupted(`expected a YAML map, got ${Array.isArray(parsed) ? 'a list' : JSON.stringify(parsed)}`);
+        console.error(`device config migration failed (${err?.message ?? err}); a later run retries`);
     }
-    return parsed;
-}
-/** Write a device doc in place (atomic). Only ever holds device-local fields. */
-function writeDeviceDoc(device, doc) {
-    const p = deviceDocPath(device);
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    const body = Object.keys(doc).length > 0 ? doc : { agents: {} };
-    atomicWriteFileSync(p, META_HEADER + yaml.stringify(body));
 }
 // ─── Reads ────────────────────────────────────────────────────────────────────
-function entryFromMeta(spec, meta) {
-    if (spec.field === 'defaultBrowserProfile') {
-        const value = meta.defaultBrowserProfile;
-        return { spec, value, layer: value !== undefined ? 'device' : undefined };
-    }
-    if (spec.scope === 'user') {
-        const value = meta.config?.[spec.yamlKey];
-        return { spec, value, layer: value !== undefined ? 'user' : undefined };
-    }
-    const value = meta.deviceConfig?.[spec.yamlKey];
-    return { spec, value, layer: value !== undefined ? 'device' : undefined };
+/**
+ * The raw device-scope config block for `device` from the central
+ * `fleet.devices.<name>.config` map ({} when unset). This is the single read
+ * path post-migration — the profile resolver (`lib/devices/resolve-profile.ts`)
+ * goes through here. Deliberately does NOT auto-trigger the migration: it
+ * serves the hot dial/render paths, and the keys it resolves (ssh.*, platform)
+ * are new — they never existed in the legacy stores. Keys with legacy data are
+ * read through the public API below, which triggers the fold.
+ */
+export function readDeviceConfigValues(device) {
+    const devices = readMeta().fleet?.devices;
+    if (!devices || devices === 'all')
+        return {};
+    const config = devices[device]?.config;
+    return config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+}
+/** The device a targeted read/write applies to (default: this machine). */
+function targetDevice(opts) {
+    return opts?.device ?? machineId();
 }
-/** True when `device` names this machine (case-insensitive, mirroring
- * `isLocalDevice` in teams/scheduler.ts) — `configure ZION` on host zion must
- * take the self path (readMeta/updateMeta funnel), not the peer-doc path. */
-function isSelfDevice(device) {
-    return device.toLowerCase() === machineId();
+/**
+ * A machine-visibility key is only ever readable for THIS box, because it lives
+ * in this box's own gitignored doc. Asking for a peer's value is a mistake with a
+ * concrete fix, so say so rather than silently returning this machine's answer
+ * for another machine — that would make `agents devices config <peer>
+ * browser.remote-control` look like it reported the peer's consent state.
+ */
+function assertLocalTarget(spec, device) {
+    if (spec.scope !== 'device' || spec.visibility !== 'machine')
+        return;
+    if (device === machineId())
+        return;
+    throw new Error(`${spec.name} is machine-local, so it can only be read or set on the device itself.\n` +
+        `Run it on ${device}, e.g.: agents ssh ${device} 'agents config ${spec.name} <value>'`);
 }
 /** Get one config key's value and the layer that set it. */
 export function getConfigValue(name, opts) {
     const spec = configKeySpec(name);
-    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
-        const doc = readDeviceDoc(opts.device) ?? {};
-        return entryFromMeta(spec, { deviceConfig: doc.config, defaultBrowserProfile: doc.defaultBrowserProfile });
+    if (spec.scope === 'user') {
+        const value = readMeta().config?.[spec.yamlKey];
+        return { spec, value, layer: value !== undefined ? 'user' : undefined };
+    }
+    const device = targetDevice(opts);
+    assertLocalTarget(spec, device);
+    if (spec.visibility === 'machine') {
+        // This machine's own doc, never the synced file. Fall back to the central
+        // block so a value written by an older CLI is still honored until the
+        // operator prunes it (the migration is additive and leaves it in place).
+        const local = readMeta().deviceConfig?.[spec.yamlKey];
+        const value = local !== undefined ? local : readDeviceConfigValues(device)[spec.yamlKey];
+        return { spec, value, layer: value !== undefined ? 'device' : undefined };
     }
-    return entryFromMeta(spec, readMeta());
+    const value = readDeviceConfigValues(device)[spec.yamlKey];
+    return { spec, value, layer: value !== undefined ? 'device' : undefined };
 }
-/** List every known key with its value and the layer that set it. */
+/**
+ * List every known key with its value and the layer that set it.
+ *
+ * Listing a PEER omits its machine-local keys rather than throwing. Their values
+ * live in that box's own doc and are genuinely unknowable from here, but a bulk
+ * listing must not hard-fail because one key in the registry is unreadable —
+ * `agents devices config <peer>` should still show everything it CAN resolve.
+ * Asking for such a key by name still errors, with the `agents ssh` fix named.
+ */
 export function listConfig(opts) {
-    return CONFIG_KEYS.map((spec) => getConfigValue(spec.name, opts));
+    const isPeer = targetDevice(opts) !== machineId();
+    const visible = isPeer
+        ? CONFIG_KEYS.filter((spec) => spec.scope !== 'device' || spec.visibility !== 'machine')
+        : CONFIG_KEYS;
+    return visible.map((spec) => getConfigValue(spec.name, opts));
+}
+/** List user-scope config keys with their values. Used to show inherited settings
+ * in per-device views without implying those keys are device-local. */
+export function listUserConfig() {
+    return CONFIG_KEYS.filter((spec) => spec.scope === 'user').map((spec) => getConfigValue(spec.name));
+}
+/** Resolve the explicit usage host, falling back to the user's interactive host. */
+export function resolveUsagePrimaryHost() {
+    return getConfigValue('usage.primary-host').value
+        ?? getConfigValue('interactive.host').value
+        ?? null;
 }
 // ─── Writes ───────────────────────────────────────────────────────────────────
-function setInMeta(spec, value) {
+function setInCentralBlock(device, spec, value) {
     updateMeta((m) => {
-        if (spec.field === 'defaultBrowserProfile') {
-            return { ...m, defaultBrowserProfile: value };
-        }
-        if (spec.scope === 'user') {
-            return { ...m, config: { ...m.config, [spec.yamlKey]: value } };
-        }
-        return { ...m, deviceConfig: { ...m.deviceConfig, [spec.yamlKey]: value } };
+        const devices = fleetDevicesMapForWrite(m.fleet);
+        const prev = devices[device] ?? {};
+        devices[device] = { ...prev, config: { ...prev.config, [spec.yamlKey]: value } };
+        return { ...m, fleet: { ...m.fleet, devices } };
     });
 }
-function unsetInMeta(spec) {
+function unsetInCentralBlock(device, spec) {
     updateMeta((m) => {
-        if (spec.field === 'defaultBrowserProfile') {
-            const { defaultBrowserProfile, ...rest } = m;
-            void defaultBrowserProfile;
+        const stored = m.fleet?.devices;
+        if (!stored || stored === 'all')
+            return m; // nothing stored — unset is a no-op (never upgrade 'all' for one)
+        const prev = stored[device];
+        if (!prev?.config || !(spec.yamlKey in prev.config))
+            return m; // key not present — no write needed
+        const config = { ...prev.config };
+        delete config[spec.yamlKey];
+        const override = { ...prev };
+        if (Object.keys(config).length > 0)
+            override.config = config;
+        else
+            delete override.config;
+        const devices = { ...stored };
+        if (Object.keys(override).length > 0)
+            devices[device] = override;
+        else
+            delete devices[device];
+        const fleet = { ...m.fleet, devices };
+        // Drop the fleet block entirely when the unset emptied a block that holds
+        // nothing else — don't leave a vestigial `fleet: {devices: {}}` behind.
+        if (Object.keys(devices).length === 0 && !fleet.defaults && !fleet.secrets && !fleet.routines) {
+            const { fleet: _, ...rest } = m;
+            void _;
             return rest;
         }
-        const block = spec.scope === 'user' ? m.config : m.deviceConfig;
-        if (!block || !(spec.yamlKey in block))
-            return m;
-        const next = { ...block };
-        delete next[spec.yamlKey];
-        const cleaned = Object.keys(next).length > 0 ? next : undefined;
-        return spec.scope === 'user' ? { ...m, config: cleaned } : { ...m, deviceConfig: cleaned };
+        return { ...m, fleet };
     });
 }
-function setInDeviceDoc(device, spec, value) {
-    const doc = readDeviceDoc(device) ?? {};
-    if (spec.field === 'defaultBrowserProfile') {
-        doc.defaultBrowserProfile = value;
-    }
-    else {
-        doc.config = { ...doc.config, [spec.yamlKey]: value };
-    }
-    writeDeviceDoc(device, doc);
-}
-function unsetInDeviceDoc(device, spec) {
-    const doc = readDeviceDoc(device);
-    if (!doc)
-        return; // nothing stored — unset is a no-op
-    if (spec.field === 'defaultBrowserProfile') {
-        delete doc.defaultBrowserProfile;
-    }
-    else if (doc.config && spec.yamlKey in doc.config) {
-        delete doc.config[spec.yamlKey];
-        if (Object.keys(doc.config).length === 0)
-            delete doc.config;
-    }
-    else {
-        return; // key not present — no write needed
-    }
-    writeDeviceDoc(device, doc);
-}
 /** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
 export function setConfigValue(name, value, opts) {
     const spec = configKeySpec(name);
     assertValidValue(spec, value);
-    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
-        setInDeviceDoc(opts.device, spec, value);
+    if (spec.scope === 'user') {
+        updateMeta((m) => ({ ...m, config: { ...m.config, [spec.yamlKey]: value } }));
+        return;
+    }
+    const device = targetDevice(opts);
+    assertLocalTarget(spec, device);
+    if (spec.visibility === 'machine') {
+        updateMeta((m) => ({ ...m, deviceConfig: { ...m.deviceConfig, [spec.yamlKey]: value } }));
         return;
     }
-    setInMeta(spec, value);
+    setInCentralBlock(device, spec, value);
 }
 /** Unset a config key — restores default behavior. No-op when already unset. */
 export function unsetConfigValue(name, opts) {
     const spec = configKeySpec(name);
-    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
-        unsetInDeviceDoc(opts.device, spec);
+    if (spec.scope === 'user') {
+        updateMeta((m) => {
+            if (!m.config || !(spec.yamlKey in m.config))
+                return m;
+            const next = { ...m.config };
+            delete next[spec.yamlKey];
+            return { ...m, config: Object.keys(next).length > 0 ? next : undefined };
+        });
+        return;
+    }
+    const device = targetDevice(opts);
+    assertLocalTarget(spec, device);
+    if (spec.visibility === 'machine') {
+        updateMeta((m) => {
+            if (!m.deviceConfig || !(spec.yamlKey in m.deviceConfig))
+                return m;
+            const next = { ...m.deviceConfig };
+            delete next[spec.yamlKey];
+            return { ...m, deviceConfig: Object.keys(next).length > 0 ? next : undefined };
+        });
+        // Also clear any copy an older CLI left centrally, so the unset is not
+        // shadowed by the fallback read above.
+        unsetInCentralBlock(device, spec);
         return;
     }
-    unsetInMeta(spec);
+    unsetInCentralBlock(device, spec);
+}
+/** True if the device is enabled for auto-launch. Unset defaults to true. */
+export function isAutoLaunchEnabled(name) {
+    assertValidDeviceName(name);
+    return getConfigValue('auto-launch.enabled', { device: name }).value !== false;
+}
+/** Set whether a device is enabled for auto-launch. Setting the default
+ * (enabled) removes the key to keep the block minimal. */
+export function setAutoLaunchEnabled(name, enabled) {
+    assertValidDeviceName(name);
+    if (enabled)
+        unsetConfigValue('auto-launch.enabled', { device: name });
+    else
+        setConfigValue('auto-launch.enabled', false, { device: name });
+}
+/** True if the device is preferred for auto-launch ranking. */
+export function isAutoLaunchPreferred(name) {
+    assertValidDeviceName(name);
+    return getConfigValue('auto-launch.preferred', { device: name }).value === true;
+}
+/** Set whether a device is preferred for auto-launch. Setting the default
+ * (not preferred) removes the key to keep the block minimal. */
+export function setAutoLaunchPreferred(name, preferred) {
+    assertValidDeviceName(name);
+    if (preferred)
+        setConfigValue('auto-launch.preferred', true, { device: name });
+    else
+        unsetConfigValue('auto-launch.preferred', { device: name });
+}
+/** Every device's auto-launch flags, keyed by device name (set flags only) —
+ * the shape the ext's launch ranking consumes. */
+export function loadAutoLaunchPreferences() {
+    ensureDeviceConfigMigrated();
+    const devices = readMeta().fleet?.devices;
+    const out = {};
+    if (!devices || devices === 'all')
+        return out;
+    for (const [name, override] of Object.entries(devices)) {
+        const config = override?.config;
+        if (!config)
+            continue;
+        const pref = {};
+        if (config.autoLaunchEnabled === false)
+            pref.enabled = false;
+        if (config.autoLaunchPreferred === true)
+            pref.preferred = true;
+        if (pref.enabled !== undefined || pref.preferred !== undefined)
+            out[name] = pref;
+    }
+    return out;
 }
 // ─── Consumers' helpers ───────────────────────────────────────────────────────
-/** True unless this machine's device doc disables the routines scheduler. */
+/** True unless this machine's config disables the routines scheduler. */
 export function isSchedulerEnabled() {
     return getConfigValue('scheduler.enabled').value !== false;
 }
@@ -301,10 +506,10 @@ export function isSchedulerEnabled() {
 export function assertSchedulerEnabled() {
     if (isSchedulerEnabled())
         return;
-    throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
-        `Re-enable with: agents devices configure ${machineId()} --scheduler on`);
+    throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/agents.yaml fleet.devices.${machineId()}.config). ` +
+        `Re-enable with: agents devices config ${machineId()} scheduler.enabled on`);
 }
-/** True unless this machine's device doc disables the daemon outright (top-level kill switch). */
+/** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export function isDaemonEnabled() {
     return getConfigValue('daemon.enabled').value !== false;
 }
@@ -318,12 +523,12 @@ export function isDaemonEnabled() {
 export function assertDaemonEnabled() {
     if (isDaemonEnabled())
         return;
-    throw new Error(`The daemon is disabled on this device (daemon.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
+    throw new Error(`The daemon is disabled on this device (daemon.enabled=false in ~/.agents/agents.yaml fleet.devices.${machineId()}.config). ` +
         `Re-enable with: agents daemon enable`);
 }
 /**
- * Read the `agents.max-concurrent` cap for each named device from its synced
- * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * Read the `agents.max-concurrent` cap for each named device from the central
+ * config block (no SSH). Devices without a cap are omitted — uncapped is the
  * default. Used as an input to host ranking (teams placement, Factory
  * auto-launch), never as a remote probe.
  */