@phnx-labs/agents-cli 1.22.38 → 1.22.39

package/dist/lib/device-config.js

@@ -38,6 +38,10 @@ 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'];
+/** 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 +75,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 +136,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',
@@ -191,6 +220,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',
@@ -442,6 +485,48 @@ export function unsetConfigValue(name, opts) {
     }
     unsetInCentralBlock(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 an operator has marked, keyed by device name. Devices with no
+ * mark are absent — that absence is what makes the worker allowlist opt-in.
+ */
+export function listConfiguredDeviceRoles() {
+    ensureDeviceConfigMigrated();
+    const devices = readMeta().fleet?.devices;
+    const out = {};
+    if (!devices || devices === 'all')
+        return out;
+    for (const [name, override] of Object.entries(devices)) {
+        const role = override?.config?.role;
+        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) {
     assertValidDeviceName(name);
@@ -509,6 +594,17 @@ export function assertSchedulerEnabled() {
     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 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;

package/dist/lib/devices/pool.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The automatic-placement pool — which devices `--device auto` may pick from.
+ *
+ * One rule, in one place, so every automatic-placement path agrees: `agents run
+ * --device auto`, `agents teams add --device auto`, the generic host resolver,
+ * and the AGI EXT launch commands (which emit `--device auto` rather than
+ * scoring devices themselves) all draw from {@link filterAutoPool}.
+ *
+ * The pool is an ALLOWLIST the moment the operator marks a worker. Roles are
+ * stored in the fleet-shared `fleet.devices.<name>.config.role` block of
+ * `~/.agents/agents.yaml` (see `lib/device-config.ts`), which is the only
+ * device store that syncs — the device registry under `~/.agents/devices/` is
+ * gitignored and per-machine, so a role kept there could never be a fleet-wide
+ * statement.
+ *
+ * | Fleet state | `--device auto` picks from |
+ * |---|---|
+ * | no device marked | every online device (unchanged behavior) |
+ * | some marked `worker` | ONLY those workers |
+ * | marked `personal` | never, under either state |
+ *
+ * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
+ * machine the user sits at is marked precisely so agents stay off it.
+ *
+ * Paired cockpits (an iPhone/iPad, `role: control` in the device registry, set
+ * by `agents devices pair-ios`) are excluded by the CALLER that reads the
+ * registry — `listOnlineDeviceNames` in `lib/smart-launch.ts` — not here. That
+ * role is machine-local by nature and already has a home; duplicating it in the
+ * shared config would be a second store for one concept.
+ */
+import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
+export interface AutoPoolOptions {
+    /** Pool mode; defaults to the configured `auto.pool`. */
+    mode?: AutoPoolMode;
+    /** Configured roles by device name; defaults to the fleet-shared block. */
+    roles?: Record<string, ConfiguredDeviceRole>;
+}
+/**
+ * Narrow a candidate host list to the devices automatic placement may pick.
+ *
+ * Returns the input order, minus the excluded devices. An empty result is a
+ * real answer — "you marked workers and none of them is a candidate right now"
+ * — and callers surface it as their own no-healthy-device error rather than
+ * quietly widening back to the full fleet.
+ */
+export declare function filterAutoPool(pool: string[], opts?: AutoPoolOptions): string[];
+/** True when this host is one automatic placement may pick. */
+export declare function isAutoPoolMember(host: string, opts?: AutoPoolOptions): boolean;
+/** Device names explicitly marked `worker`, in registry order. */
+export declare function listWorkerDevices(opts?: Pick<AutoPoolOptions, 'roles'>): string[];
+/**
+ * One line naming why the pool is what it is, for the `--device auto` banner and
+ * the no-healthy-device error. Empty string when no role narrows anything, so
+ * callers can append it unconditionally.
+ */
+export declare function describeAutoPool(opts?: AutoPoolOptions): string;

package/dist/lib/devices/pool.js

@@ -0,0 +1,85 @@
+/**
+ * The automatic-placement pool — which devices `--device auto` may pick from.
+ *
+ * One rule, in one place, so every automatic-placement path agrees: `agents run
+ * --device auto`, `agents teams add --device auto`, the generic host resolver,
+ * and the AGI EXT launch commands (which emit `--device auto` rather than
+ * scoring devices themselves) all draw from {@link filterAutoPool}.
+ *
+ * The pool is an ALLOWLIST the moment the operator marks a worker. Roles are
+ * stored in the fleet-shared `fleet.devices.<name>.config.role` block of
+ * `~/.agents/agents.yaml` (see `lib/device-config.ts`), which is the only
+ * device store that syncs — the device registry under `~/.agents/devices/` is
+ * gitignored and per-machine, so a role kept there could never be a fleet-wide
+ * statement.
+ *
+ * | Fleet state | `--device auto` picks from |
+ * |---|---|
+ * | no device marked | every online device (unchanged behavior) |
+ * | some marked `worker` | ONLY those workers |
+ * | marked `personal` | never, under either state |
+ *
+ * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
+ * machine the user sits at is marked precisely so agents stay off it.
+ *
+ * Paired cockpits (an iPhone/iPad, `role: control` in the device registry, set
+ * by `agents devices pair-ios`) are excluded by the CALLER that reads the
+ * registry — `listOnlineDeviceNames` in `lib/smart-launch.ts` — not here. That
+ * role is machine-local by nature and already has a home; duplicating it in the
+ * shared config would be a second store for one concept.
+ */
+import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
+import { normalizeHost } from '../machine-id.js';
+/** Roles that automatic placement never picks, whatever the pool mode. */
+const NEVER_AUTO = new Set(['personal']);
+/**
+ * Narrow a candidate host list to the devices automatic placement may pick.
+ *
+ * Returns the input order, minus the excluded devices. An empty result is a
+ * real answer — "you marked workers and none of them is a candidate right now"
+ * — and callers surface it as their own no-healthy-device error rather than
+ * quietly widening back to the full fleet.
+ */
+export function filterAutoPool(pool, opts = {}) {
+    const roles = opts.roles ?? listConfiguredDeviceRoles();
+    const byHost = new Map(Object.entries(roles).map(([name, role]) => [normalizeHost(name), role]));
+    const roleOf = (host) => byHost.get(normalizeHost(host));
+    const eligible = pool.filter((host) => {
+        const role = roleOf(host);
+        return role === undefined || !NEVER_AUTO.has(role);
+    });
+    const mode = opts.mode ?? autoPoolMode();
+    if (mode === 'all')
+        return eligible;
+    const anyWorkerMarked = [...byHost.values()].some((role) => role === 'worker');
+    if (!anyWorkerMarked)
+        return eligible;
+    return eligible.filter((host) => roleOf(host) === 'worker');
+}
+/** True when this host is one automatic placement may pick. */
+export function isAutoPoolMember(host, opts = {}) {
+    return filterAutoPool([host], opts).length > 0;
+}
+/** Device names explicitly marked `worker`, in registry order. */
+export function listWorkerDevices(opts = {}) {
+    const roles = opts.roles ?? listConfiguredDeviceRoles();
+    return Object.entries(roles)
+        .filter(([, role]) => role === 'worker')
+        .map(([name]) => name);
+}
+/**
+ * One line naming why the pool is what it is, for the `--device auto` banner and
+ * the no-healthy-device error. Empty string when no role narrows anything, so
+ * callers can append it unconditionally.
+ */
+export function describeAutoPool(opts = {}) {
+    const roles = opts.roles ?? listConfiguredDeviceRoles();
+    const mode = opts.mode ?? autoPoolMode();
+    const workers = listWorkerDevices({ roles });
+    if (mode === 'all') {
+        return workers.length > 0 ? 'auto.pool=all (worker marks ignored)' : '';
+    }
+    if (workers.length === 0)
+        return '';
+    return `workers: ${workers.join(', ')}`;
+}

package/dist/lib/exec.d.ts

@@ -398,6 +398,8 @@ export interface TmuxWrapContext {
     raw: boolean;
     /** The AGENTS_NO_TMUX=1 escape hatch. */
     noTmuxEnv: boolean;
+    /** This device's `tmux.enabled` config — false turns the wrap off for every launch on this box. */
+    configEnabled: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
 }
@@ -410,12 +412,13 @@ export interface TmuxWrapContext {
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
  *
- * All five guards must pass:
+ * All seven guards must pass:
  *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
  *   - not Windows     — no tmux path on win32.
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
+ *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;

package/dist/lib/exec.js

@@ -29,6 +29,8 @@ import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
+import { isTmuxEnabled } from './device-config.js';
+import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
 import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
@@ -1327,12 +1329,13 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
  *
- * All five guards must pass:
+ * All seven guards must pass:
  *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
  *   - not Windows     — no tmux path on win32.
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
+ *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export function shouldWrapInTmux(ctx) {
@@ -1346,6 +1349,8 @@ export function shouldWrapInTmux(ctx) {
         return false;
     if (ctx.noTmuxEnv)
         return false;
+    if (!ctx.configEnabled)
+        return false;
     if (!ctx.tmuxAvailable)
         return false;
     return true;
@@ -1459,7 +1464,7 @@ async function runInTmux(options, executable, args) {
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
-    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.${OFF}\n\n`;
+    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.\n  If tmux is broken on this machine, turn the wrap off for good: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
     // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
@@ -1766,6 +1771,7 @@ async function spawnAgent(options) {
         inTmux: !!process.env.TMUX,
         raw: options.raw === true,
         noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
+        configEnabled: isTmuxEnabled(),
         tmuxAvailable: isTmuxInstalled(),
     })) {
         timer.mark('startup');

package/dist/lib/migrate.d.ts

@@ -58,6 +58,42 @@ export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): vo
  * can drive a fixture tree without touching the user's ~/.agents.
  */
 export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string, historyDir?: string): void;
+/**
+ * Move the auto-detected `default` browser profile OUT of the committed central
+ * agents.yaml and into this machine's per-device file.
+ *
+ * `browser` is a CENTRAL key because named profiles a user creates are real fleet
+ * config, but the ONE `default` entry inside it is machine-local: its `binary` is
+ * an OS-specific path and its endpoint is a locally-chosen free port.
+ * `createProfile`/`updateProfile` already route that entry to `deviceBrowser`
+ * (`isMachineLocalProfile`, browser/profiles.ts) — but nothing ever removed the
+ * copy older versions had already written into the shared file, and
+ * `serializeCentral` cannot: it deletes whole KEYS that are device-scoped, and
+ * `browser` is not one.
+ *
+ * So the entry sat in the committed file and every box rewrote it with its own
+ * browser. Measured 2026-08-13, all three boxes on 1.22.38 (which HAS the writer
+ * fix) with an empty `deviceBrowser` and a machine-specific `default` in central:
+ *
+ *   zion         browser: chrome    binary: /Applications/Google Chrome.app/...
+ *   yosemite-s1  browser: brave     binary: /opt/brave.com/brave/brave
+ *   mark-1       (same shape)
+ *
+ * `agents repos pull user` refuses when an incoming change touches a locally
+ * modified path, so agents.yaml being permanently dirty wedged the fleet config
+ * sync outright — those boxes sat 5, 8 and 79 commits behind. (RUSH-2161)
+ *
+ * Idempotent: no-op once central carries no `default` entry. The device file is
+ * written FIRST so a crash between the two writes can never lose the profile,
+ * and an entry already in the device file wins (this machine's live value is
+ * newer than the stale central copy by construction).
+ *
+ * Central is edited through a `yaml.Document` rather than re-stringified, so the
+ * hand-written comments in the committed agents.yaml survive — a plain
+ * `yaml.stringify` would drop every one of them and rewrite the whole file,
+ * which is the same churn this migration exists to stop (see `serializeCentral`).
+ */
+export declare function migrateMachineLocalBrowserProfileOutOfCentral(userDir?: string, machine?: string): void;
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in

package/dist/lib/migrate.js

@@ -21,6 +21,10 @@ import { setConfigValue } from './device-config.js';
 import { enabledRoutineNames, replaceEnabledRoutines } from './routine-activation.js';
 import { evaluateActivationReadiness } from './routine-readiness.js';
 import { migrateDeviceConfigToCentral } from './devices/config-migration.js';
+// Two constants only, never the read/write API — migrations still operate on raw
+// YAML so they never take the meta lock or prime the meta cache mid-migration.
+import { DEFAULT_BROWSER_PROFILE_NAME } from './browser/profiles.js';
+import { META_HEADER as DEVICE_META_HEADER } from './state.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -1688,6 +1692,103 @@ function migrateSplitDeviceLocalMeta() {
         console.error('Split agents.yaml: agents: -> devices/, versions: -> .history/version-resources.json');
     }
 }
+/**
+ * Move the auto-detected `default` browser profile OUT of the committed central
+ * agents.yaml and into this machine's per-device file.
+ *
+ * `browser` is a CENTRAL key because named profiles a user creates are real fleet
+ * config, but the ONE `default` entry inside it is machine-local: its `binary` is
+ * an OS-specific path and its endpoint is a locally-chosen free port.
+ * `createProfile`/`updateProfile` already route that entry to `deviceBrowser`
+ * (`isMachineLocalProfile`, browser/profiles.ts) — but nothing ever removed the
+ * copy older versions had already written into the shared file, and
+ * `serializeCentral` cannot: it deletes whole KEYS that are device-scoped, and
+ * `browser` is not one.
+ *
+ * So the entry sat in the committed file and every box rewrote it with its own
+ * browser. Measured 2026-08-13, all three boxes on 1.22.38 (which HAS the writer
+ * fix) with an empty `deviceBrowser` and a machine-specific `default` in central:
+ *
+ *   zion         browser: chrome    binary: /Applications/Google Chrome.app/...
+ *   yosemite-s1  browser: brave     binary: /opt/brave.com/brave/brave
+ *   mark-1       (same shape)
+ *
+ * `agents repos pull user` refuses when an incoming change touches a locally
+ * modified path, so agents.yaml being permanently dirty wedged the fleet config
+ * sync outright — those boxes sat 5, 8 and 79 commits behind. (RUSH-2161)
+ *
+ * Idempotent: no-op once central carries no `default` entry. The device file is
+ * written FIRST so a crash between the two writes can never lose the profile,
+ * and an entry already in the device file wins (this machine's live value is
+ * newer than the stale central copy by construction).
+ *
+ * Central is edited through a `yaml.Document` rather than re-stringified, so the
+ * hand-written comments in the committed agents.yaml survive — a plain
+ * `yaml.stringify` would drop every one of them and rewrite the whole file,
+ * which is the same churn this migration exists to stop (see `serializeCentral`).
+ */
+export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR, machine = machineId()) {
+    const metaFile = path.join(userDir, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let doc;
+    try {
+        doc = yaml.parseDocument(fs.readFileSync(metaFile, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    if (doc.errors.length > 0)
+        return;
+    const central = doc.toJSON() ?? {};
+    const browser = central.browser;
+    if (!browser || typeof browser !== 'object' || Array.isArray(browser))
+        return;
+    const entry = browser[DEFAULT_BROWSER_PROFILE_NAME];
+    if (entry === undefined)
+        return;
+    // Device file first — a crash before central is rewritten leaves a harmless
+    // duplicate, while the reverse order would drop the profile entirely.
+    const devicePath = path.join(userDir, 'devices', machine, 'agents.yaml');
+    let deviceDoc = {};
+    try {
+        deviceDoc = yaml.parse(fs.readFileSync(devicePath, 'utf-8')) || {};
+    }
+    catch { /* absent — first write */ }
+    const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
+        ? deviceDoc.browser
+        : {};
+    if (deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
+        deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] = entry;
+        deviceDoc.browser = deviceBrowser;
+        fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+        atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
+    }
+    // Then strip it from the synced file, dropping `browser:` entirely when the
+    // machine-local entry was its only member.
+    doc.deleteIn(['browser', DEFAULT_BROWSER_PROFILE_NAME]);
+    if (Object.keys(browser).length === 1) {
+        const itemsOf = () => (doc.contents?.items) ?? [];
+        const idx = itemsOf().findIndex((pair) => pair.key?.value === 'browser');
+        const orphaned = idx >= 0 ? itemsOf()[idx]?.key?.commentBefore ?? undefined : undefined;
+        doc.delete('browser');
+        if (orphaned) {
+            // Deleting shifted the following pair down into `idx`.
+            const next = itemsOf()[idx]?.key;
+            if (next)
+                next.commentBefore = next.commentBefore ? `${orphaned}\n${next.commentBefore}` : orphaned;
+            else
+                doc.commentBefore = orphaned;
+        }
+    }
+    // Everything cleared -> header only, never a bare `{}`. stringifyDoc emits a
+    // FLOW empty map for an empty root, and a later parseDocument inherits that
+    // flow and renders the whole rewritten file inline. serializeCentral guards
+    // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
+    const remaining = Object.keys(doc.toJSON() ?? {}).length;
+    atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
+    console.error(`Migrated agents.yaml: browser '${DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
+}
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in
@@ -2299,6 +2400,12 @@ export async function runMigration() {
     // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
     // in pattern form when it moves to the history file.
     migrateSplitDeviceLocalMeta();
+    // Same split, one level deeper: `browser` stays central (named profiles are
+    // fleet config) but its auto-detected `default` entry is machine-local and was
+    // left behind in the synced file, keeping every box dirty. After
+    // migrateSplitDeviceLocalMeta so the device file is already in its canonical
+    // location before this merges an entry into it.
+    migrateMachineLocalBrowserProfileOutOfCentral();
     // Fold per-device operator config (device-doc config:/defaultBrowserProfile
     // and .history/devices/auto-launch.json) into the central
     // fleet.devices.<name>.config block. After migrateSplitDeviceLocalMeta so the

package/dist/lib/smart-launch.d.ts

@@ -25,14 +25,32 @@ export declare function affinityWeights(rows: AffinityRow[], alpha?: number): We
  * Pure — inject `rng` for tests.
  */
 export declare function sampleWeighted(candidates: WeightedCandidate[], rng?: () => number): string | null;
-/** Online device names from the local registry (+ always include local). */
+/**
+ * Online device names from the local registry (+ local), narrowed to the
+ * automatic-placement pool.
+ *
+ * The pool rule lives in `devices/pool.ts` and is an allowlist once any device
+ * is marked `role=worker`: this is the single place both automatic-placement
+ * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
+ * marking workers moves every `--device auto` at once instead of one surface.
+ *
+ * Paired cockpits (`role: control` in the device registry) are dropped here,
+ * where the registry is already being read — they are control surfaces, not
+ * compute. It CAN return an empty list — a fleet where every marked worker is
+ * offline, or where this box is the only candidate and is marked `personal`. That is a
+ * real answer, and both callers fail loud on it rather than falling back to the
+ * local machine (which would be the exact box the operator marked personal to
+ * keep agents off).
+ */
 export declare function listOnlineDeviceNames(localName?: string): string[];
 export interface DeviceAffinityOptions {
     sinceDays?: number;
     alpha?: number;
     /**
-     * Eligible hosts (normalized). Defaults to online devices + local.
-     * Empty after filter → fall back to local.
+     * Eligible hosts (normalized). Defaults to the automatic-placement pool
+     * (online devices + local, narrowed by device roles). An explicitly empty
+     * list falls back to local — the caller supplied it; an empty DEFAULT pool
+     * throws, because roles emptied it on purpose.
      */
     eligibleHosts?: string[];
     localMachine?: string;
@@ -59,6 +77,12 @@ export interface DeviceAutoPlan {
     }>;
     pickedDeviceKey: string;
 }
+/**
+ * The error both automatic-placement resolvers raise when device roles leave no
+ * candidate at all. Fail loud: the alternative — quietly running on the local
+ * machine — puts the agent on the box the operator marked `personal`.
+ */
+export declare function formatEmptyAutoPoolError(): string;
 export declare function formatNoHealthyDeviceError(pool: string[], signals: Map<string, DevicePlacementSignal>, agent?: string): string;
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is
@@ -74,6 +98,12 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
 }): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
+ *
+ * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
+ * `agents ssh auto`, the generic `--host auto` passthrough, and `matchHost`'s
+ * `auto` sentinel honour device roles too. Throws when roles leave the pool
+ * empty — a `null` host here means "run locally", which for a box marked
+ * `personal` is the outcome the mark exists to prevent.
  */
 export declare function resolveDeviceAffinity(opts?: DeviceAffinityOptions): DeviceAffinityPlan;
 /** True when a host flag value means affinity pick. */