@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/device-config.js

@@ -1,43 +1,49 @@
 /**
- * Device/user config keys — typed read/write over the central agents.yaml store.
+ * Device/user config keys — typed read/write over the three-layer 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   → 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).
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → the per-device TRACKED doc
+ *                    `~/.agents/devices/<name>/agents.yaml` under `config:` —
+ *                    conflict-free by construction (each machine writes only
+ *                    its own folder, and the churny auto-written pins no longer
+ *                    share the file)
+ *   - fleet layer  → central `~/.agents/agents.yaml` under
+ *                    `fleet.defaults.config` — fleet-wide defaults written by
+ *                    `agents devices config --fleet <key> <value>`
  *
- * 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.
+ * Read order for a device-scope key: built-in default < fleet.defaults.config
+ * < per-device config:. Names and non-secret values only (a secrets-bundle
+ * NAME is fine; a credential never is).
  *
  * 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`.
  *
- * 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.
+ * Legacy stores (central `fleet.devices.<name>.config`, legacy auto-launch.json,
+ * doc-level defaultBrowserProfile, pins in tracked docs) are folded into this
+ * layout once by `lib/devices/config-migration.ts`, invoked on the first
+ * read/write in a process — after migration there is ONE read path per layer,
+ * no fallback branches.
  *
  * Unset always means today's behavior (the documented default).
  */
-import { readMeta, updateMeta } from './state.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { META_HEADER, getUserAgentsDir, readMeta, updateMeta, withMetaLock } from './state.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { assertValidDeviceName } from './devices/registry.js';
-import { fleetDevicesMapForWrite, migrateDeviceConfigToCentral } from './devices/config-migration.js';
+import { migrateDeviceConfigStores } from './devices/config-migration.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
+/** Roles a device can be marked with — see the `role` key below. */
+const DEVICE_ROLES = ['worker', 'personal'];
+/** Which devices automatic placement may pick — see the `auto.pool` key below. */
+const AUTO_POOL_MODES = ['workers', 'all'];
 export const CONFIG_KEYS = [
     {
         name: 'interactive.host',
@@ -71,6 +77,19 @@ export const CONFIG_KEYS = [
             }
         },
     },
+    {
+        name: 'auto.pool',
+        yamlKey: 'autoPool',
+        scope: 'user',
+        type: 'string',
+        description: "Which devices automatic placement (`--device auto`) may pick: 'workers' (default — only devices marked role=worker, " +
+            "once at least one is marked) or 'all' (every online device, ignoring worker marks). A device marked personal is " +
+            'never picked automatically under either mode.',
+        defaultValue: 'workers',
+        validate: (v) => AUTO_POOL_MODES.includes(v)
+            ? null
+            : `auto.pool must be one of ${AUTO_POOL_MODES.join(' | ')}.`,
+    },
     {
         name: 'browser.profile',
         yamlKey: 'defaultBrowserProfile',
@@ -119,6 +138,18 @@ export const CONFIG_KEYS = [
         defaultValue: false,
         description: 'Whether the daemon runs the watchdog pass on this device.',
     },
+    {
+        name: 'tmux.enabled',
+        yamlKey: 'tmuxEnabled',
+        scope: 'device',
+        visibility: 'machine',
+        type: 'bool',
+        defaultValue: true,
+        description: 'Whether an interactive `agents run` on this device is wrapped in the shared-socket tmux session. ' +
+            'On gives every agent an addressable pane (`agents sessions --active` tells co-located agents apart, ' +
+            '`agents focus` re-attaches without forking). Off spawns the agent directly on this box — the durable ' +
+            'form of `--no-tmux`, for a machine whose tmux is broken or unwanted.',
+    },
     {
         name: 'browser.remote-control',
         yamlKey: 'browserRemoteControl',
@@ -126,9 +157,22 @@ export const CONFIG_KEYS = [
         visibility: 'machine',
         type: 'bool',
         defaultValue: false,
-        description: "Whether other fleet machines may drive THIS device's browser over `browser --host <this-device>`. " +
+        description: "Whether other fleet machines may drive THIS device's browser over `browser --device <this-device>`. " +
             'Default off — a fleet-remote drive is refused until the owner runs `agents browser remote-control on`.',
     },
+    {
+        name: 'browser.task-idle-minutes',
+        yamlKey: 'browserTaskIdleMinutes',
+        scope: 'device',
+        visibility: 'machine',
+        type: 'int',
+        defaultValue: 30,
+        description: 'Minutes a browser task may sit with no IPC action (navigate, click, type, screenshot, …) before the daemon\'s ' +
+            'abandoned-task reaper closes its tabs and marks it done (RUSH-2622). 0 disables idle reaping — the reaper still ' +
+            "closes a task whose owning agent session has exited, whatever this is set to. Read only on THIS box's own " +
+            'reaper tick and `agents browser gc`, so it never applies to a peer.',
+        validate: (v) => v >= 0 ? null : 'browser.task-idle-minutes must be >= 0 (0 disables idle reaping).',
+    },
     {
         name: 'notes',
         yamlKey: 'notes',
@@ -191,6 +235,20 @@ export const CONFIG_KEYS = [
             ? null
             : `platform must be one of ${DEVICE_PLATFORMS.join(' | ')}.`,
     },
+    {
+        name: 'role',
+        yamlKey: 'role',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: "What this device is for, fleet-wide: 'worker' (a box agents run on) or 'personal' (a machine you sit at — never " +
+            'picked automatically). Marking ANY device worker turns automatic placement into an allowlist: `--device auto` then ' +
+            'picks only from the marked workers. (A paired iPhone/iPad cockpit is marked control by `agents devices pair-ios` ' +
+            'and is excluded from placement by that role, not this key.)',
+        validate: (v) => DEVICE_ROLES.includes(v)
+            ? null
+            : `role must be one of ${DEVICE_ROLES.join(' | ')}.`,
+    },
     {
         name: 'auto-launch.enabled',
         yamlKey: 'autoLaunchEnabled',
@@ -249,57 +307,106 @@ function assertValidValue(spec, value) {
 // ─── Migration hook ───────────────────────────────────────────────────────────
 let migrationDone = false;
 /**
- * Fold the legacy per-device config stores into the central block, once per
+ * Fold the legacy config/pins stores into the current layout, 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.
  */
 export function ensureDeviceConfigMigrated() {
     if (migrationDone || process.env.AGENTS_SKIP_MIGRATION === '1')
         return;
     try {
-        migrateDeviceConfigToCentral();
+        migrateDeviceConfigStores();
         migrationDone = true;
     }
     catch (err) {
         console.error(`device config migration failed (${err?.message ?? err}); a later run retries`);
     }
 }
-// ─── Reads ────────────────────────────────────────────────────────────────────
+// ─── Layer reads ──────────────────────────────────────────────────────────────
+/** Path to a device's tracked operator doc (`devices/<name>/agents.yaml`). */
+function deviceDocPath(device) {
+    return path.join(getUserAgentsDir(), 'devices', device, 'agents.yaml');
+}
 /**
- * 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.
+ * Read a device's doc. 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 routines/config (same contract as routine-activation's reader).
  */
-export function readDeviceConfigValues(device) {
-    const devices = readMeta().fleet?.devices;
-    if (!devices || devices === 'all')
+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;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch (err) {
+        throw corrupted(err?.message ?? String(err));
+    }
+    if (parsed === null || parsed === undefined)
         return {};
-    const config = devices[device]?.config;
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw corrupted(`expected a YAML map, got ${Array.isArray(parsed) ? 'a list' : JSON.stringify(parsed)}`);
+    }
+    const doc = parsed;
+    if (doc.config !== undefined && (typeof doc.config !== 'object' || doc.config === null || Array.isArray(doc.config))) {
+        throw corrupted('config: must be a mapping');
+    }
+    return doc;
+}
+/** Write a device doc (atomic), preserving keys this module does not own
+ * (`routines:`). A doc left empty is removed instead of leaving an empty
+ * tracked file behind. */
+function writeDeviceDoc(device, doc) {
+    const p = deviceDocPath(device);
+    if (Object.keys(doc).length === 0) {
+        try {
+            fs.rmSync(p, { force: true });
+            fs.rmdirSync(path.dirname(p));
+        }
+        catch { /* dir not empty, or the file was already gone */ }
+        return;
+    }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    atomicWriteFileSync(p, META_HEADER + yaml.stringify(doc));
+}
+/** The fleet-defaults config layer (central `fleet.defaults.config`; {} when unset). */
+export function readFleetConfigDefaults() {
+    const config = readMeta().fleet?.defaults?.config;
     return config && typeof config === 'object' && !Array.isArray(config) ? config : {};
 }
+/** The device layer only: the doc's `config:` block ({} when unset). */
+function readDeviceDocConfig(device) {
+    return readDeviceDoc(device)?.config ?? {};
+}
+/**
+ * The effective device-scope config block for `device`: fleet.defaults.config
+ * overlaid with the per-device doc's config:. 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. Sync and cheap (small local files).
+ */
+export function readDeviceConfigValues(device) {
+    return { ...readFleetConfigDefaults(), ...readDeviceDocConfig(device) };
+}
 /** The device a targeted read/write applies to (default: this machine). */
 function targetDevice(opts) {
     return opts?.device ?? 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.
+ * A machine-visibility key is only ever readable for THIS box. 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.
  */
 function assertLocalTarget(spec, device) {
     if (spec.scope !== 'device' || spec.visibility !== 'machine')
@@ -307,39 +414,39 @@ function assertLocalTarget(spec, device) {
     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>'`);
+        `Run it on ${device}, e.g.: agents ssh ${device} 'agents devices config ${device} ${spec.name} <value>'`);
 }
-/** Get one config key's value and the layer that set it. */
+/** Get one config key's effective value and the layer that set it. */
 export function getConfigValue(name, opts) {
+    ensureDeviceConfigMigrated();
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
         const value = readMeta().config?.[spec.yamlKey];
-        return { spec, value, layer: value !== undefined ? 'user' : undefined };
+        return { spec, value, source: value !== undefined ? 'user' : 'default' };
+    }
+    if (opts?.fleet) {
+        const value = readFleetConfigDefaults()[spec.yamlKey];
+        return { spec, value, source: value !== undefined ? 'fleet' : 'default' };
     }
     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 };
-    }
-    const value = readDeviceConfigValues(device)[spec.yamlKey];
-    return { spec, value, layer: value !== undefined ? 'device' : undefined };
+    const docConfig = readDeviceDocConfig(device);
+    if (spec.yamlKey in docConfig)
+        return { spec, value: docConfig[spec.yamlKey], source: 'device' };
+    const fleetConfig = readFleetConfigDefaults();
+    if (spec.yamlKey in fleetConfig)
+        return { spec, value: fleetConfig[spec.yamlKey], source: 'fleet' };
+    return { spec, value: undefined, source: 'default' };
 }
 /**
- * List every known key with its value and the layer that set it.
+ * List every known key with its effective 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.
+ * Listing a PEER omits its machine-local keys rather than throwing — those
+ * values live on that box and are unknowable from here, but a bulk listing
+ * must not hard-fail. Asking for such a key by name still errors.
  */
 export function listConfig(opts) {
-    const isPeer = targetDevice(opts) !== machineId();
+    const isPeer = !opts?.fleet && targetDevice(opts) !== machineId();
     const visible = isPeer
         ? CONFIG_KEYS.filter((spec) => spec.scope !== 'device' || spec.visibility !== 'machine')
         : CONFIG_KEYS;
@@ -357,38 +464,42 @@ export function resolveUsagePrimaryHost() {
         ?? null;
 }
 // ─── Writes ───────────────────────────────────────────────────────────────────
-function setInCentralBlock(device, spec, value) {
+/** The fleet manifest for a defaults write: `devices` materializes as an
+ * explicit empty map (NOT 'all') so `agents apply` targets nothing until the
+ * operator declares a roster. */
+function fleetForDefaultsWrite(fleet) {
+    return { ...fleet, devices: fleet && fleet.devices !== undefined ? fleet.devices : {} };
+}
+function setInFleetDefaults(spec, value) {
     updateMeta((m) => {
-        const devices = fleetDevicesMapForWrite(m.fleet);
-        const prev = devices[device] ?? {};
-        devices[device] = { ...prev, config: { ...prev.config, [spec.yamlKey]: value } };
-        return { ...m, fleet: { ...m.fleet, devices } };
+        const fleet = fleetForDefaultsWrite(m.fleet);
+        const defaults = { ...fleet.defaults, config: { ...fleet.defaults?.config, [spec.yamlKey]: value } };
+        return { ...m, fleet: { ...fleet, defaults } };
     });
 }
-function unsetInCentralBlock(device, spec) {
+function unsetInFleetDefaults(spec) {
     updateMeta((m) => {
-        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 };
+        const stored = m.fleet?.defaults?.config;
+        if (!stored || !(spec.yamlKey in stored))
+            return m; // nothing stored — no-op
+        const config = { ...stored };
         delete config[spec.yamlKey];
-        const override = { ...prev };
+        const defaults = { ...m.fleet.defaults };
         if (Object.keys(config).length > 0)
-            override.config = config;
+            defaults.config = config;
         else
-            delete override.config;
-        const devices = { ...stored };
-        if (Object.keys(override).length > 0)
-            devices[device] = override;
+            delete defaults.config;
+        const fleet = { ...m.fleet, devices: m.fleet.devices };
+        if (Object.keys(defaults).length > 0)
+            fleet.defaults = defaults;
         else
-            delete devices[device];
-        const fleet = { ...m.fleet, devices };
+            delete fleet.defaults;
         // 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 devicesEmpty = fleet.devices == null || fleet.devices === 'all'
+            ? false
+            : Object.keys(fleet.devices).length === 0;
+        if (devicesEmpty && !fleet.defaults && !fleet.secrets && !fleet.routines) {
             const { fleet: _, ...rest } = m;
             void _;
             return rest;
@@ -396,26 +507,65 @@ function unsetInCentralBlock(device, spec) {
         return { ...m, fleet };
     });
 }
-/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+function setInDeviceDoc(device, spec, value) {
+    // The doc is shared with writeMetaUnlocked (which owns routines:) — the
+    // read-modify-write runs under the meta lock so the two writers can't lose
+    // each other's update across processes.
+    withMetaLock(() => {
+        const doc = readDeviceDoc(device) ?? {};
+        doc.config = { ...doc.config, [spec.yamlKey]: value };
+        writeDeviceDoc(device, doc);
+    });
+}
+function unsetInDeviceDoc(device, spec) {
+    withMetaLock(() => {
+        const doc = readDeviceDoc(device);
+        if (!doc)
+            return; // nothing stored — unset is a no-op
+        const config = doc.config;
+        if (!config || !(spec.yamlKey in config))
+            return; // key not present — no write needed
+        delete config[spec.yamlKey];
+        if (Object.keys(config).length > 0)
+            doc.config = config;
+        else
+            delete doc.config;
+        writeDeviceDoc(device, doc);
+    });
+}
+/**
+ * Set a config key (validated). Device-scope keys target this machine unless
+ * `opts.device` names a peer; `opts.fleet` writes the fleet-wide defaults layer
+ * instead. User-scope keys reject `fleet` (they are already fleet-wide).
+ */
 export function setConfigValue(name, value, opts) {
+    ensureDeviceConfigMigrated();
     const spec = configKeySpec(name);
     assertValidValue(spec, value);
     if (spec.scope === 'user') {
+        if (opts?.fleet) {
+            throw new Error(`Config key '${spec.name}' is user-scope (already fleet-wide) — --fleet does not apply.`);
+        }
         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 } }));
+    if (opts?.fleet) {
+        setInFleetDefaults(spec, value);
         return;
     }
-    setInCentralBlock(device, spec, value);
+    const device = targetDevice(opts);
+    assertLocalTarget(spec, device);
+    setInDeviceDoc(device, spec, value);
 }
-/** Unset a config key — restores default behavior. No-op when already unset. */
+/** Unset a config key — restores the next layer down (fleet default, then the
+ * built-in default). No-op when already unset at that layer. */
 export function unsetConfigValue(name, opts) {
+    ensureDeviceConfigMigrated();
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
+        if (opts?.fleet) {
+            throw new Error(`Config key '${spec.name}' is user-scope (already fleet-wide) — --fleet does not apply.`);
+        }
         updateMeta((m) => {
             if (!m.config || !(spec.yamlKey in m.config))
                 return m;
@@ -425,22 +575,69 @@ export function unsetConfigValue(name, opts) {
         });
         return;
     }
+    if (opts?.fleet) {
+        unsetInFleetDefaults(spec);
+        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;
+    unsetInDeviceDoc(device, spec);
+}
+/**
+ * The role marked on one device, or undefined when the operator never marked it.
+ *
+ * Undefined is meaningful and is NOT the same as `worker`: an unmarked device is
+ * eligible for automatic placement only while no device anywhere carries an
+ * explicit `worker` mark (see {@link listConfiguredDeviceRoles}).
+ */
+export function configuredDeviceRole(name) {
+    assertValidDeviceName(name);
+    return getConfigValue('role', { device: name }).value;
+}
+/** Mark a device's role fleet-wide; `undefined` clears the mark. */
+export function setConfiguredDeviceRole(name, role) {
+    assertValidDeviceName(name);
+    if (role === undefined)
+        unsetConfigValue('role', { device: name });
+    else
+        setConfigValue('role', role, { device: name });
+}
+/**
+ * Every device with an effective role, keyed by device name. Layers like every
+ * other device-scope key: the fleet default (central fleet.defaults.config)
+ * applies fleet-wide and the per-device doc wins on conflict. `roster` (the
+ * registered device names) lets a fleet default reach devices that have no doc
+ * of their own; without it only devices with docs are considered — so a
+ * fleet-wide `role` default would silently miss a doc-less device and drop it
+ * from the worker allowlist. Mirrors {@link loadAutoLaunchPreferences}.
+ */
+export function listConfiguredDeviceRoles(roster) {
+    ensureDeviceConfigMigrated();
+    const out = {};
+    const fleetRole = readFleetConfigDefaults().role;
+    const names = new Set(roster ?? []);
+    if (!roster) {
+        const devicesRoot = path.join(getUserAgentsDir(), 'devices');
+        try {
+            for (const entry of fs.readdirSync(devicesRoot, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    names.add(entry.name);
+            }
+        }
+        catch { /* no devices/ tree — roster stays empty */ }
     }
-    unsetInCentralBlock(device, spec);
+    for (const name of names) {
+        const role = readDeviceDocConfig(name).role ?? fleetRole;
+        if (typeof role === 'string' && DEVICE_ROLES.includes(role)) {
+            out[name] = role;
+        }
+    }
+    return out;
+}
+/** The configured automatic-placement pool mode. Unset means `workers`. */
+export function autoPoolMode() {
+    const value = getConfigValue('auto.pool').value;
+    return value === 'all' ? 'all' : 'workers';
 }
 /** True if the device is enabled for auto-launch. Unset defaults to true. */
 export function isAutoLaunchEnabled(name) {
@@ -448,7 +645,7 @@ export function isAutoLaunchEnabled(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. */
+ * (enabled) removes the key to keep the doc minimal. */
 export function setAutoLaunchEnabled(name, enabled) {
     assertValidDeviceName(name);
     if (enabled)
@@ -462,7 +659,7 @@ export function isAutoLaunchPreferred(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. */
+ * (not preferred) removes the key to keep the doc minimal. */
 export function setAutoLaunchPreferred(name, preferred) {
     assertValidDeviceName(name);
     if (preferred)
@@ -470,22 +667,37 @@ export function setAutoLaunchPreferred(name, preferred) {
     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() {
+/**
+ * Every device's effective auto-launch flags, keyed by device name — the shape
+ * the menu-bar snapshot consumes. Layers like every other device-scope key: the
+ * fleet default (central fleet.defaults.config) applies fleet-wide and the
+ * per-device doc wins on conflict. `roster` (the registered device names) lets
+ * a fleet default reach devices that have no doc of their own; without it only
+ * devices with docs are listed.
+ */
+export function loadAutoLaunchPreferences(roster) {
     ensureDeviceConfigMigrated();
-    const devices = readMeta().fleet?.devices;
+    const fleet = readFleetConfigDefaults();
+    const names = new Set(roster ?? []);
+    if (!roster) {
+        const devicesRoot = path.join(getUserAgentsDir(), 'devices');
+        try {
+            for (const entry of fs.readdirSync(devicesRoot, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    names.add(entry.name);
+            }
+        }
+        catch { /* no devices/ tree — roster stays empty */ }
+    }
     const out = {};
-    if (!devices || devices === 'all')
-        return out;
-    for (const [name, override] of Object.entries(devices)) {
-        const config = override?.config;
-        if (!config)
-            continue;
+    for (const name of names) {
+        const doc = readDeviceDocConfig(name);
+        const enabled = (doc.autoLaunchEnabled ?? fleet.autoLaunchEnabled);
+        const preferred = (doc.autoLaunchPreferred ?? fleet.autoLaunchPreferred);
         const pref = {};
-        if (config.autoLaunchEnabled === false)
+        if (enabled === false)
             pref.enabled = false;
-        if (config.autoLaunchPreferred === true)
+        if (preferred === true)
             pref.preferred = true;
         if (pref.enabled !== undefined || pref.preferred !== undefined)
             out[name] = pref;
@@ -506,9 +718,20 @@ 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/agents.yaml fleet.devices.${machineId()}.config). ` +
+    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 config ${machineId()} scheduler.enabled on`);
 }
+/**
+ * True unless this machine's config turns off the managed tmux wrap for
+ * interactive `agents run` launches (`tmux.enabled=false`).
+ *
+ * Read as one of the guards in `shouldWrapInTmux` (lib/exec.ts) — the durable,
+ * per-machine form of `--no-tmux` / `AGENTS_NO_TMUX=1`, for a box whose tmux is
+ * broken or unwanted. Unset means today's behavior: wrap.
+ */
+export function isTmuxEnabled() {
+    return getConfigValue('tmux.enabled').value !== false;
+}
 /** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export function isDaemonEnabled() {
     return getConfigValue('daemon.enabled').value !== false;
@@ -523,14 +746,25 @@ export function isDaemonEnabled() {
 export function assertDaemonEnabled() {
     if (isDaemonEnabled())
         return;
-    throw new Error(`The daemon is disabled on this device (daemon.enabled=false in ~/.agents/agents.yaml fleet.devices.${machineId()}.config). ` +
+    throw new Error(`The daemon is disabled on this device (daemon.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
         `Re-enable with: agents daemon enable`);
 }
 /**
- * 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.
+ * Idle window (ms) the browser-task reaper (`browser/hygiene.ts`) uses on THIS
+ * machine, or `null` when idle reaping is off (`browser.task-idle-minutes=0`)
+ * — session-dead reaping is unaffected either way. Unset means the default 30
+ * minutes. Read by the daemon's periodic tick and, as the fallback when a
+ * caller omits `--idle-minutes`, by the `gc` IPC action.
+ */
+export function resolveBrowserTaskIdleMs() {
+    const minutes = getConfigValue('browser.task-idle-minutes').value ?? 30;
+    return minutes === 0 ? null : minutes * 60_000;
+}
+/**
+ * Read the effective `agents.max-concurrent` cap for each named device (fleet
+ * defaults layered under the per-device doc; no SSH). Devices without a cap
+ * are omitted — uncapped is the default. Used as an input to host ranking
+ * (teams placement, AGI EXT auto-launch), never as a remote probe.
  */
 export function readMaxConcurrentCaps(devices) {
     const caps = {};