@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/device-config.js

@@ -1,35 +1,3 @@
-/**
- * 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 → 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>`
- *
- * 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 (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 * as fs from 'fs';
 import * as fsp from 'fs/promises';
 import * as path from 'path';
@@ -43,17 +11,10 @@ import { parseAddress } from './address.js';
 import { isAgentId } from './types.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', 'desktop'];
-/** Which devices automatic placement may pick — see the `auto.pool` key below. */
 const AUTO_POOL_MODES = ['workers', 'all'];
-/**
- * A device's physical form factor (`formFactor` key) — a factual hardware fact
- * the menu bar shows as an icon. Set explicitly per device (no inference from
- * platform, no hardcoded device names). `unknown` is the effective default.
- */
 const DEVICE_FORM_FACTORS = ['laptop', 'desktop', 'server', 'unknown'];
-/** A validate() that accepts only one of `allowed` — the enum-string keys reuse it. */
+export const MENUBAR_TABS = ['home', 'sessions', 'inbox', 'projects'];
 function oneOf(name, allowed) {
     return (v) => (allowed.includes(v) ? null : `${name} must be one of ${allowed.join(' | ')}.`);
 }
@@ -169,12 +130,6 @@ export const CONFIG_KEYS = [
     {
         name: 'browser.device',
         yamlKey: 'defaultBrowserDevice',
-        // user scope, so a SINGLE value in the central agents.yaml syncs to every box:
-        // the fleet's browser hub. A worker with this set forwards its browser drives
-        // to the hub (as if `--device <hub>` was passed) with no per-command flag, so
-        // every agent shares the hub's one logged-in browser. The hub names itself, so
-        // there it resolves to a self-host and runs locally — which is why one synced
-        // value is safe. Unset = drive this box's own browser (today's behavior).
         scope: 'user',
         type: 'string',
         description: 'Fleet browser hub: the device whose browser `agents browser` drive verbs target by default, with no --device. ' +
@@ -389,12 +344,6 @@ export const CONFIG_KEYS = [
             'explicitly — never inferred from the OS platform. Unset reads as `unknown`.',
         validate: oneOf('formFactor', DEVICE_FORM_FACTORS),
     },
-    // ─── AGI Menu preferences (PHNX-3999) ──────────────────────────────────────
-    // User-scope so one value syncs fleet-wide via `agents repo push/pull` and the
-    // native menu reads it from `agents config list --json`. Names mirror the Swift
-    // MenuPreferences local-cache keys. `config list` OMITS an unset key, so the
-    // native app falls back to its own known defaults — the defaults documented
-    // here match those, they are not substituted on read.
     {
         name: 'menubar.menu.defaultProject',
         yamlKey: 'menubarMenuDefaultProject',
@@ -566,14 +515,86 @@ export const CONFIG_KEYS = [
             }
         },
     },
+    {
+        name: 'menubar.menu.pinnedProjects',
+        yamlKey: 'menubarMenuPinnedProjects',
+        scope: 'user',
+        type: 'string-list',
+        defaultValue: [],
+        description: 'AGI Menu: project names pinned to the top of the Projects tab, in pin order. Set the whole list ' +
+            'each time (`a,b` or a JSON array); unset = nothing pinned.',
+        validate: (v) => {
+            const names = v;
+            if (names.some((n) => n.trim() === '' || n !== n.trim())) {
+                return 'menubar.menu.pinnedProjects names must be non-empty with no surrounding spaces.';
+            }
+            const dup = names.find((n, i) => names.indexOf(n) !== i);
+            return dup === undefined ? null : `menubar.menu.pinnedProjects lists "${dup}" twice.`;
+        },
+    },
+    {
+        name: 'menubar.menu.tabOrder',
+        yamlKey: 'menubarMenuTabOrder',
+        scope: 'user',
+        type: 'string-list',
+        defaultValue: [...MENUBAR_TABS],
+        description: `AGI Menu: the order of the tab bar — every one of ${MENUBAR_TABS.join(', ')} exactly once. ` +
+            'Settings is always last and is not listed. Hiding a tab is menubar.menu.hiddenTabs, not this key.',
+        validate: (v) => {
+            const tabs = v;
+            const ok = tabs.length === MENUBAR_TABS.length && MENUBAR_TABS.every((t) => tabs.includes(t));
+            return ok ? null : `menubar.menu.tabOrder must list each of ${MENUBAR_TABS.join(', ')} exactly once.`;
+        },
+    },
+    {
+        name: 'menubar.menu.hiddenTabs',
+        yamlKey: 'menubarMenuHiddenTabs',
+        scope: 'user',
+        type: 'string-list',
+        defaultValue: [],
+        description: `AGI Menu: tabs hidden from the tab bar — any of ${MENUBAR_TABS.join(', ')}, but not all of them. ` +
+            'Settings cannot be hidden. Hiding Inbox loses nothing: its requests still show on Home.',
+        validate: (v) => {
+            const tabs = v;
+            const bad = tabs.find((t) => !MENUBAR_TABS.includes(t));
+            if (bad !== undefined)
+                return `menubar.menu.hiddenTabs: "${bad}" is not one of ${MENUBAR_TABS.join(', ')}.`;
+            if (new Set(tabs).size !== tabs.length)
+                return 'menubar.menu.hiddenTabs lists a tab twice.';
+            if (tabs.length === MENUBAR_TABS.length)
+                return 'menubar.menu.hiddenTabs cannot hide every tab.';
+            return null;
+        },
+    },
+    {
+        name: 'menubar.menu.groupTicketsByMilestone',
+        yamlKey: 'menubarMenuGroupTicketsByMilestone',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: false,
+        description: 'AGI Menu: group a project\'s tickets under milestone headers. Off = one flat list ordered by ticketSort.',
+    },
+    {
+        name: 'menubar.menu.prGroupOpen',
+        yamlKey: 'menubarMenuPrGroupOpen',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'none',
+        description: 'AGI Menu: how a project\'s open pull requests are grouped (the All, Ready, Drafts and Mine filters) — ' +
+            'none, type (the conventional-commit type in the title), or day.',
+        validate: oneOf('menubar.menu.prGroupOpen', ['none', 'type', 'day']),
+    },
+    {
+        name: 'menubar.menu.prGroupMerged',
+        yamlKey: 'menubarMenuPrGroupMerged',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'day',
+        description: 'AGI Menu: how a project\'s recently merged pull requests are grouped — none, type (the ' +
+            'conventional-commit type in the title), or day (Today, Yesterday, Earlier this week).',
+        validate: oneOf('menubar.menu.prGroupMerged', ['none', 'type', 'day']),
+    },
 ];
-/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
-/**
- * Per-harness override of `updates.auto` (PHNX-3940) — `updates.<agent>.auto`,
- * one boolean key per registered agent id. Use the lightweight canonical ID
- * catalog: importing the installation/runtime registry here creates a cycle
- * through the harness adapters and makes ordinary config readers load it all.
- */
 function dynamicAgentAutoUpdateSpec(name) {
     const match = name.match(/^updates\.(.+)\.auto$/);
     if (!match)
@@ -598,7 +619,6 @@ export function configKeySpec(name) {
     }
     return spec;
 }
-/** Throw when `value` does not match the key's declared type or validation. */
 export function assertValidValue(spec, value) {
     switch (spec.type) {
         case 'string':
@@ -626,15 +646,7 @@ export function assertValidValue(spec, value) {
     if (err)
         throw new Error(`Invalid value for '${spec.name}': ${err}`);
 }
-// ─── Migration hook ───────────────────────────────────────────────────────────
 let migrationDone = false;
-/**
- * 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).
- */
 function ensureDeviceConfigMigrated() {
     if (migrationDone || process.env.AGENTS_SKIP_MIGRATION === '1')
         return;
@@ -646,17 +658,9 @@ function ensureDeviceConfigMigrated() {
         console.error(`device config migration failed (${err?.message ?? err}); a later run retries`);
     }
 }
-// ─── 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');
 }
-/**
- * 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).
- */
-/** Parse + validate a device doc's raw YAML. Shared by the sync and async readers. */
 function parseDeviceDoc(raw, p) {
     const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
     let parsed;
@@ -690,7 +694,6 @@ function readDeviceDoc(device) {
     }
     return parseDeviceDoc(raw, p);
 }
-/** Async twin of {@link readDeviceDoc} for the daemon's tick paths (PHNX-3695) — the device-doc read must not block the shared event loop. */
 async function readDeviceDocAsync(device) {
     const p = deviceDocPath(device);
     let raw;
@@ -704,9 +707,6 @@ async function readDeviceDocAsync(device) {
     }
     return parseDeviceDoc(raw, p);
 }
-/** 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) {
@@ -714,40 +714,25 @@ function writeDeviceDoc(device, doc) {
             fs.rmSync(p, { force: true });
             fs.rmdirSync(path.dirname(p));
         }
-        catch { /* dir not empty, or the file was already gone */ }
+        catch { }
         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). */
 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. 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')
         return;
@@ -756,17 +741,9 @@ function assertLocalTarget(spec, device) {
     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 devices config ${device} ${spec.name} <value>'`);
 }
-/** Get one config key's effective value and the layer that set it. */
 export function getConfigValue(name, opts) {
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
-        // A user-scope key reads purely from central `agents.yaml` (readMeta) and
-        // is untouched by the device-config fold, which only relocates DEVICE-scope
-        // legacy stores (config-migration.ts) — none of them a user key. So a
-        // user-scope read stays a PURE read and MUST NOT trigger the migration
-        // write: a read-only `agents update --check` reads the `updates.auto` /
-        // `updates.<agent>.auto` policy through here, and migrating disk on that
-        // read is exactly the unsolicited startup write --check must not do.
         const value = readMeta({ migrate: false }).config?.[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'user' : 'default' };
     }
@@ -785,20 +762,9 @@ export function getConfigValue(name, opts) {
         return { spec, value: fleetConfig[spec.yamlKey], source: 'fleet' };
     return { spec, value: undefined, source: 'default' };
 }
-/**
- * Async, non-blocking twin of {@link getConfigValue} for the daemon's tick paths
- * (PHNX-3695) — e.g. the watchdog tick reading `watchdog.enabled` every ~3min.
- * Same layer precedence (device doc → fleet defaults → default), but the
- * per-device doc READ is async. The user/fleet layers go through `readMeta`,
- * which serves from an mtime-stamped in-memory cache (≈ 2 stat syscalls on the
- * hot path, no file read), and `ensureDeviceConfigMigrated` is a one-shot no-op
- * after the first process-wide fold — neither blocks the loop meaningfully.
- */
 export async function getConfigValueAsync(name, opts) {
     const spec = configKeySpec(name);
     if (spec.scope === 'user') {
-        // Pure user-scope read — same reasoning as the sync twin: no device-config
-        // fold, so a user read never migrates disk.
         const value = readMeta({ migrate: false }).config?.[spec.yamlKey];
         return { spec, value, source: value !== undefined ? 'user' : 'default' };
     }
@@ -817,13 +783,6 @@ export async function getConfigValueAsync(name, opts) {
         return { spec, value: fleetConfig[spec.yamlKey], source: 'fleet' };
     return { spec, value: undefined, source: 'default' };
 }
-/**
- * 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 — 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 = !opts?.fleet && targetDevice(opts) !== machineId();
     const visible = isPeer
@@ -831,10 +790,6 @@ export function listConfig(opts) {
         : CONFIG_KEYS;
     return visible.map((spec) => getConfigValue(spec.name, opts));
 }
-// ─── Writes ───────────────────────────────────────────────────────────────────
-/** 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 : {} };
 }
@@ -849,7 +804,7 @@ function unsetInFleetDefaults(spec) {
     updateMeta((m) => {
         const stored = m.fleet?.defaults?.config;
         if (!stored || !(spec.yamlKey in stored))
-            return m; // nothing stored — no-op
+            return m;
         const config = { ...stored };
         delete config[spec.yamlKey];
         const defaults = { ...m.fleet.defaults };
@@ -862,8 +817,6 @@ function unsetInFleetDefaults(spec) {
             fleet.defaults = defaults;
         else
             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.
         const devicesEmpty = fleet.devices == null || fleet.devices === 'all'
             ? false
             : Object.keys(fleet.devices).length === 0;
@@ -876,9 +829,6 @@ function unsetInFleetDefaults(spec) {
     });
 }
 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 };
@@ -889,10 +839,10 @@ function unsetInDeviceDoc(device, spec) {
     withMetaLock(() => {
         const doc = readDeviceDoc(device);
         if (!doc)
-            return; // nothing stored — unset is a no-op
+            return;
         const config = doc.config;
         if (!config || !(spec.yamlKey in config))
-            return; // key not present — no write needed
+            return;
         delete config[spec.yamlKey];
         if (Object.keys(config).length > 0)
             doc.config = config;
@@ -901,11 +851,6 @@ function unsetInDeviceDoc(device, spec) {
         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);
@@ -925,8 +870,6 @@ export function setConfigValue(name, value, opts) {
     assertLocalTarget(spec, device);
     setInDeviceDoc(device, spec, value);
 }
-/** 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);
@@ -951,45 +894,16 @@ export function unsetConfigValue(name, opts) {
     assertLocalTarget(spec, device);
     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;
 }
-/**
- * The role marked on THIS machine — the one running the CLI — or undefined when
- * it was never marked. Keyed off {@link machineId} (overridable via
- * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
- *
- * The auth strategy reads this: a headed device (`personal` or `desktop`, see
- * {@link isHeadedDeviceRole}) holds a real per-version login and MUST
- * authenticate from it for EVERY run, interactive or headless; only a `worker`
- * uses the file-based setup-token (RUSH-2395). `undefined` is treated as
- * non-headed (worker-equivalent) by that gate — an unmarked box has no login to
- * defer to.
- */
 export function selfConfiguredDeviceRole() {
     return configuredDeviceRole(machineId());
 }
-/**
- * A "headed" device — one with an interactive desktop login, so it authenticates
- * from its own per-version Claude login (which carries the `user:profile` scope
- * the usage endpoint needs) rather than the headless file setup-token. Both
- * `personal` (the box you sit at) and `desktop` (a headed always-on box like a
- * Mac mini) qualify; a `worker` and an unmarked box do NOT. This is the single
- * predicate the auth-bucket sites read, so `personal` and `desktop` never drift
- * apart (claude adapter, routine spawn env, `agents view` usage login).
- */
 export function isHeadedDeviceRole(role) {
     return role === 'personal' || role === 'desktop';
 }
-/** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export function setConfiguredDeviceRole(name, role) {
     assertValidDeviceName(name);
     if (role === undefined)
@@ -997,20 +911,8 @@ export function setConfiguredDeviceRole(name, role) {
     else
         setConfigValue('role', role, { device: name });
 }
-/**
- * Devices whose OWN config pins one of the browser profile keys to `profile`.
- *
- * Used by `profiles rename` to warn rather than silently leave a peer pointing at
- * a name that no longer exists. Deliberately read-only: rewriting another
- * machine's device doc from here would be a cross-machine mutation nobody asked
- * for, and the pin may well be correct there (a local profile of the same name).
- */
 export function devicesPinningBrowserProfile(profile) {
     ensureDeviceConfigMigrated();
-    // Reports WHICH key each device used, not just that it matched. A caller
-    // telling the user to fix `browser.profile` on a device that actually pinned
-    // `browser.viewer` leaves the real pin broken and sets a second key nobody
-    // asked for.
     const hits = [];
     const devicesRoot = path.join(getUserAgentsDir(), 'devices');
     let names = [];
@@ -1025,7 +927,6 @@ export function devicesPinningBrowserProfile(profile) {
     }
     for (const name of names.sort()) {
         const cfg = readDeviceDocConfig(name);
-        // A device can pin BOTH; each needs its own fix line.
         if (cfg.defaultBrowserProfile === profile)
             hits.push({ device: name, key: 'browser.profile' });
         if (cfg.browserViewer === profile)
@@ -1033,15 +934,6 @@ export function devicesPinningBrowserProfile(profile) {
     }
     return hits;
 }
-/**
- * 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 = {};
@@ -1055,7 +947,7 @@ export function listConfiguredDeviceRoles(roster) {
                     names.add(entry.name);
             }
         }
-        catch { /* no devices/ tree — roster stays empty */ }
+        catch { }
     }
     for (const name of names) {
         const role = readDeviceDocConfig(name).role ?? fleetRole;
@@ -1065,18 +957,14 @@ export function listConfiguredDeviceRoles(roster) {
     }
     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) {
     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 doc minimal. */
 export function setAutoLaunchEnabled(name, enabled) {
     assertValidDeviceName(name);
     if (enabled)
@@ -1084,13 +972,10 @@ export function setAutoLaunchEnabled(name, enabled) {
     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 doc minimal. */
 export function setAutoLaunchPreferred(name, preferred) {
     assertValidDeviceName(name);
     if (preferred)
@@ -1098,14 +983,6 @@ export function setAutoLaunchPreferred(name, preferred) {
     else
         unsetConfigValue('auto-launch.preferred', { device: name });
 }
-/**
- * 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 fleet = readFleetConfigDefaults();
@@ -1118,7 +995,7 @@ export function loadAutoLaunchPreferences(roster) {
                     names.add(entry.name);
             }
         }
-        catch { /* no devices/ tree — roster stays empty */ }
+        catch { }
     }
     const out = {};
     for (const name of names) {
@@ -1135,62 +1012,31 @@ export function loadAutoLaunchPreferences(roster) {
     }
     return out;
 }
-// ─── Consumers' helpers ───────────────────────────────────────────────────────
-/** True unless this machine's config disables the routines scheduler. */
 export function isSchedulerEnabled() {
     return getConfigValue('scheduler.enabled').value !== false;
 }
-/**
- * Throw when the routines scheduler is disabled on this machine, naming the
- * setting and the fix. The single message every scheduler-start surface
- * (auto-start on `routines add`, manual `routines start`, the daemon's own
- * scheduler init) refuses with.
- */
 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 config ${machineId()} scheduler.enabled on`);
 }
-/** True only when this machine explicitly enables the managed tmux wrap. */
 export function isTmuxEnabled() {
     return getConfigValue('tmux.enabled').value === true;
 }
-/** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export function isDaemonEnabled() {
     return getConfigValue('daemon.enabled').value !== false;
 }
-/**
- * Throw when the daemon is disabled on this machine, naming the setting and
- * the fix. Every AUTO-start surface (routines add/start/catchup/webhook,
- * monitors add, `ensureDaemonStarted`) refuses with this before calling
- * `startDaemon()`. `agents daemon start` is the deliberate override and does
- * NOT call this — disable only blocks auto-start, mirroring `systemctl disable`.
- */
 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). ` +
         `Re-enable with: agents daemon enable`);
 }
-/**
- * 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.
- */
-/** Async so the daemon's browser-task-reap tick reads the config off the shared event loop (PHNX-3695). */
 export async function resolveBrowserTaskIdleMs() {
     const minutes = (await getConfigValueAsync('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 = {};
     for (const device of devices) {

package/dist/lib/devices/config-migration.d.ts

@@ -1,44 +1 @@
-/**
- * One-time migration to the current device-config + pins layout:
- *
- *   (a) central `fleet.devices.<name>.config` (the short-lived #2458 store)
- *       folds into each per-device doc's `config:` block — central wins
- *       (newest intent) — and is stripped from central;
- *   (b) legacy `.history/devices/auto-launch.json` flags fold into the doc
- *       `config:` too (oldest store — only fills keys not already set);
- *   (c) a top-level `defaultBrowserProfile:` in a device doc folds into that
- *       doc's `config:`;
- *   (d) agent pins (`agents:` / `isolatedAgents:`) leave the TRACKED
- *       per-device docs: THIS machine's pins move to the untracked
- *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
- *       is the destination); peers' pins are simply dropped from the tracked
- *       file (each peer owns/rewrites its own pins locally).
- *   (e) legacy `.history/devices/ignored.json` (per-machine, UNTRACKED — a
- *       dismissal never reached the rest of the fleet) folds into the central
- *       TRACKED `fleet.ignored` list (RUSH-3062). Entries keep the legacy
- *       file's `updatedAt` as `ignoredAt` and take THIS machine's id as
- *       `ignoredOn` — the legacy store recorded neither, so the folding box
- *       is the only attribution available. The legacy file is removed only
- *       AFTER the central write lands.
- *
- * What stays put: a device doc's existing `config:` (already the right home)
- * and its `routines:` list (operator-owned, read cross-device by
- * routine-activation.ts).
- *
- * Order is crash-safe: destination writes (pins file, device doc) land BEFORE
- * the source strip (central), so a crash mid-fold re-folds on the next run and
- * the destination-wins merges make that a no-op. Idempotent — after a
- * successful run none of the legacy locations hold data, so re-running is a
- * cheap existence check. A doc that fails to parse is LOUDLY skipped (left
- * untouched) so the next run retries — never silently emptied, same corruption
- * contract the device registry keeps.
- *
- * Invoked from three places so every install converges regardless of entry
- * point: `runMigration()` (fresh / sentinel-less installs), daemon boot, and
- * the first `lib/device-config.ts` read/write in a process.
- */
-/**
- * Fold every legacy device-config/pins location into the current layout. Safe
- * to call on every boot / config access: cheap no-op once folded.
- */
 export declare function migrateDeviceConfigStores(): void;