@phnx-labs/agents-cli 1.22.38 → 1.22.39

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.22.39
+
+- **The auto-detected `default` browser profile no longer sits in the fleet-shared `agents.yaml`, which was wedging `agents repos pull user` fleet-wide (RUSH-2161).** `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` have routed that entry to the per-device file since 1.22.38 (`isMachineLocalProfile`), but nothing removed the copy older versions had already written into the shared file, and `serializeCentral` could not — it deletes whole device-scoped KEYS, and `browser` is not one. So the stale entry stayed committed and every box rewrote it with its own browser. Measured across three boxes all running 1.22.38: zion `chrome` + `/Applications/Google Chrome.app/...`, yosemite-s1 `brave` + `/opt/brave.com/brave/brave`, mark-1 the same shape, each with an empty `deviceBrowser`. Because the pull refuses when an incoming change touches a locally modified path, a permanently dirty `agents.yaml` blocked fleet config sync outright — those boxes sat 5, 8 and 79 commits behind, so merged config (a `notify.owner` block, device roles) reached zero machines. A new migration moves the entry into `devices/<machine>/agents.yaml` and deletes it from central, writing the device file first so a crash cannot lose the profile and keeping an existing device entry when one is already there. Central is edited through a YAML `Document`, so the hand-written comments in the committed file survive rather than being flattened by a re-stringify — which would have re-created the same churn. Named profiles are untouched. Source: `apps/cli/src/lib/migrate.ts`, `apps/cli/src/bootstrap.ts`.
+
+- **`agents config set devices.<name>.tmux off` turns the interactive tmux wrap off for one machine (RUSH-2620).** Interactive `agents run` wraps the harness in the shared-socket tmux session so every agent gets an addressable `%pane` — that is what lets `agents sessions --active` tell co-located agents apart and `agents focus` re-attach without forking. Until now the only ways out were per-run (`--raw` / `--no-tmux` / `--disable-tmux`) or the `AGENTS_NO_TMUX=1` env var, so a box whose tmux is broken needed the flag retyped on every launch. The new key is machine-local by design (a broken tmux is a property of one machine): it never enters the fleet-shared `agents.yaml` and is refused for a peer. Unset still means wrap. `agents devices config <name> tmux.enabled off` sets the same key. Source: `apps/cli/src/lib/device-config.ts` (`isTmuxEnabled`), `apps/cli/src/lib/exec.ts` (`shouldWrapInTmux`).
+
+- **`agents devices role <name> worker` marks which boxes agents run on, and `--device auto` follows it.** Roles are fleet-wide (`worker` / `personal`), stored in the shared `fleet.devices.<name>.config.role` block of `~/.agents/agents.yaml`, so a mark set on any box travels with `agents repo push/pull` — the per-device files under `~/.agents/devices/` are written only by the machine they name, so they could never carry a fleet-wide statement about a different box. Marking ANY device `worker` turns automatic placement into an allowlist: `agents run --device auto`, `agents teams add --device auto`, and the AGI EXT launch commands then pick only from the marked workers. A device marked `personal` (a machine you sit at) is never picked automatically, under any mode, and a paired cockpit stays excluded through its existing registry `control` role. When roles leave the pool empty, `--device auto` fails loud naming the fix instead of quietly running on the local machine — through `agents ssh auto` and the `--host auto` passthrough too, not just `agents run`. Nothing marked = today's behavior, every online device. Widen it back with `agents config set auto.pool all`. `agents devices role` with no arguments prints who is marked what and exactly which devices `--device auto` would consider; `agents devices list` tags marked rows and `--json` carries `role` plus an `autoPool` boolean per device. Source: `apps/cli/src/lib/devices/pool.ts`, `apps/cli/src/lib/device-config.ts`, `apps/cli/src/lib/smart-launch.ts`.
+
 ## 1.22.38
 
 - Webhook `stateTo` triggers and handlers now fire only on the delivery that actually moved a Linear issue INTO that state, not on every later update while it still sits there. Previously a `stateTo: Plan` handler re-matched on any subsequent `Issue/update` — a label edit, an assignee change, a description touch — because it checked the issue's *current* state instead of the transition, which accumulated 11 duplicate plan comments on one issue. It now additionally requires the delivery's `updatedFrom` to record a state change. (RUSH-2539)

package/dist/bootstrap.js

@@ -1095,7 +1095,7 @@ const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help', 'uninstall']);
 //
 // Skipped for --help/--version (RUSH-2454): pure documentation paths must not
 // load any migration graph. Loaded from migrate-fold.js (leaf: fs + createLink),
-// not migrate.js, so a real command pays only the fold hop unless the v19
+// not migrate.js, so a real command pays only the fold hop unless the v20
 // sentinel is missing and runMigration() is required below.
 if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !helpOrVersionRequested) {
     try {
@@ -1130,7 +1130,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !helpOrVersionRequested) {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v19';
+        const sentinelValue = 'v20';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/commands/config.js

@@ -41,12 +41,17 @@ function parseValue(key, parsed, raw) {
             return raw.trim();
         case 'usage':
             return raw.trim();
+        case 'auto':
+            return raw.trim();
         case 'browser':
             return raw.trim();
         case 'project':
             return raw.trim();
         case 'device': {
-            switch (parsed.property) {
+            const property = parsed.property;
+            switch (property) {
+                case 'role':
+                    return raw.trim();
                 case 'max-agents':
                     if (!/^\d+$/.test(raw.trim())) {
                         throw new Error(`Config key '${key}' expects an integer, got '${raw}'.`);
@@ -55,6 +60,7 @@ function parseValue(key, parsed, raw) {
                 case 'scheduler':
                 case 'daemon':
                 case 'watchdog':
+                case 'tmux':
                 case 'browser.remote-control':
                     return parseBool(raw, key);
                 case 'notes':
@@ -62,6 +68,13 @@ function parseValue(key, parsed, raw) {
                 case 'browser.profile':
                     return raw.trim();
             }
+            // A device property with no arm above used to fall out of the switch and
+            // return `undefined`, so the write failed downstream with "expects a
+            // boolean, got undefined" instead of naming the real gap. The `never`
+            // binding makes adding a DeviceConfigProperty without a parse rule a
+            // compile error rather than a runtime mystery.
+            const unhandled = property;
+            throw new Error(`Config key '${key}' has no parse rule for device property '${String(unhandled)}'.`);
         }
     }
 }
@@ -93,6 +106,10 @@ function setConfig(parsed, value) {
             setConfigValue('usage.primary-host', value);
             return;
         }
+        case 'auto': {
+            setConfigValue('auto.pool', value);
+            return;
+        }
         case 'browser': {
             // Device-local default lives in the central fleet.devices.<name>.config
             // block (same store `agents devices config` / getConfigValue use). Bare
@@ -137,6 +154,11 @@ function unsetConfig(parsed) {
             unsetConfigValue('usage.primary-host');
             return had;
         }
+        case 'auto': {
+            const had = getConfigValue('auto.pool').value !== undefined;
+            unsetConfigValue('auto.pool');
+            return had;
+        }
         case 'browser': {
             const target = parsed.device ? { device: parsed.device } : undefined;
             const had = getConfigValue('browser.profile', target).value !== undefined;
@@ -173,6 +195,8 @@ function getConfig(parsed) {
             return getConfigValue('interactive.host').value;
         case 'usage':
             return getConfigValue('usage.primary-host').value;
+        case 'auto':
+            return getConfigValue('auto.pool').value;
         case 'browser': {
             return getConfigValue('browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
         }
@@ -231,6 +255,9 @@ function* listCentralConfigEntries() {
     if (meta.config?.usagePrimaryHost !== undefined) {
         yield { key: 'usage.primary-host', value: meta.config.usagePrimaryHost, hint: 'config.usagePrimaryHost' };
     }
+    if (meta.config?.autoPool !== undefined) {
+        yield { key: 'auto.pool', value: meta.config.autoPool, hint: 'config.autoPool' };
+    }
     if (meta.projectRoot !== undefined) {
         yield { key: 'project.root', value: meta.projectRoot, hint: 'devices.<self>.projectRoot' };
     }
@@ -262,6 +289,9 @@ function* listDeviceConfigEntries(device) {
             case 'watchdog.enabled':
                 key = `${prefix}watchdog`;
                 break;
+            case 'tmux.enabled':
+                key = `${prefix}tmux`;
+                break;
             case 'browser.remote-control':
                 key = `${prefix}browser.remote-control`;
                 break;

package/dist/commands/exec.js

@@ -557,7 +557,7 @@ export function registerRunCommand(program) {
         .option('--terminal [backend]', "Open this run in a real terminal tab instead of here. Without a value the terminal is detected from your live sessions (`agents sessions --active` host), so it lands where you already work — Ghostty for a Ghostty user, iTerm for an iTerm user. Name one to force it: iterm | ghostty | terminal | tmux | vscodium-agent. This is how the menu bar's New Session opens.")
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
-        .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing.')
+        .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing; to turn the wrap off for every run on this machine, set `agents config set devices.<name>.tmux off`.')
         .option('--disable-tmux', 'Alias for --no-tmux.')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,antigravity). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')

package/dist/commands/ssh.js

@@ -56,7 +56,8 @@ import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js'
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort, registerLeaseCommand } from './lease.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
 import { runFleetLogin } from '../lib/fleet/remote-login.js';
-import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec } from '../lib/device-config.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec, autoPoolMode, configuredDeviceRole, listConfiguredDeviceRoles, setConfiguredDeviceRole, } from '../lib/device-config.js';
+import { filterAutoPool, listWorkerDevices } from '../lib/devices/pool.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet.
@@ -77,7 +78,20 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
     const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
-    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}`;
+    const role = roleTag(d.name, listConfiguredDeviceRoles());
+    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
+}
+/** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
+ * an unmarked device is the common case and must not add a column of noise. */
+function roleTag(name, roles) {
+    const role = roles[name];
+    if (!role)
+        return '';
+    if (role === 'worker')
+        return chalk.green('  worker');
+    if (role === 'personal')
+        return chalk.yellow('  personal');
+    return chalk.gray('  control');
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -107,6 +121,7 @@ function pctCell(v, width) {
 function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
     if (!statsMap)
         return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost));
+    const deviceRoles = listConfiguredDeviceRoles();
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
@@ -149,7 +164,7 @@ function renderDeviceTable(reg, names, self, statsMap, full = false, interactive
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
         const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
-        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}`);
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}${roleTag(name, deviceRoles)}`);
     }
     // Fleet capacity summary — total cores + how much RAM is free right now.
     const cap = fleetCapacity(statsMap.values());
@@ -1161,6 +1176,84 @@ function registerDevicesCommands(program) {
         }
         await runDevicesConfigMenu(name);
     };
+    /**
+     * The `devices role` engine — read or write the fleet-wide role mark, and say
+     * what it does to automatic placement.
+     *
+     * A role written here lands in the SHARED block (`fleet.devices.<name>.config.role`)
+     * because every box has to agree on it. The vocabulary is deliberately
+     * `worker | personal` only: a paired cockpit's `control` role lives in the
+     * per-machine device registry, is written by `agents devices pair-ios`, and is
+     * what the existing dial-exclusion filters (`isControlDevice`) read. Accepting
+     * `control` here too would promise a fleet-wide dial exclusion this key cannot
+     * deliver — those filters read each box's own registry, so the mark would only
+     * hold on the machine that ran the command.
+     */
+    const runDevicesRole = async (name, role, opts) => {
+        if (!name) {
+            if (role)
+                throw new Error('Name a device: agents devices role <name> <worker|personal>');
+            const roles = listConfiguredDeviceRoles();
+            const mode = autoPoolMode();
+            const reg = await loadDevices();
+            const online = Object.entries(reg)
+                .filter(([, d]) => d?.tailscale?.online !== false)
+                .map(([n]) => n);
+            const pool = filterAutoPool(online, { mode, roles });
+            if (opts.json) {
+                writeJson({ mode, roles, autoPool: pool });
+                return;
+            }
+            const marked = Object.entries(roles);
+            if (marked.length === 0) {
+                console.log(chalk.gray('No device is marked. `--device auto` considers every online device.'));
+            }
+            else {
+                for (const [device, r] of marked) {
+                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : chalk.gray;
+                    console.log(`  ${device.padEnd(20)} ${tint(r)}`);
+                }
+            }
+            console.log();
+            console.log(chalk.bold('--device auto picks from: ') + (pool.length > 0 ? pool.join(', ') : chalk.red('nothing — no eligible device')));
+            if (mode === 'all')
+                console.log(chalk.gray('auto.pool=all — worker marks are ignored (a personal device is still excluded).'));
+            return;
+        }
+        await mustGetDevice(name);
+        if (opts.clear || role === 'none') {
+            setConfiguredDeviceRole(name, undefined);
+            if (opts.json)
+                writeJson({ device: name, role: null });
+            else
+                console.log(chalk.green(`Cleared the role on '${name}'.`));
+            return;
+        }
+        if (!role) {
+            const current = configuredDeviceRole(name);
+            if (opts.json)
+                writeJson({ device: name, role: current ?? null });
+            else
+                console.log(`  ${name.padEnd(20)} ${current ? chalk.cyan(current) : chalk.gray('— (unmarked)')}`);
+            return;
+        }
+        // configuredDeviceRole's key spec validates the value; a bad one throws with
+        // the accepted list, which the command's catch turns into exit 1.
+        setConfiguredDeviceRole(name, role);
+        if (opts.json) {
+            writeJson({ device: name, role, autoPoolWorkers: listWorkerDevices() });
+            return;
+        }
+        console.log(chalk.green(`Marked '${name}' role=${role}.`));
+        const workers = listWorkerDevices();
+        if (workers.length > 0) {
+            console.log(chalk.gray(`\`--device auto\` now picks only from: ${workers.join(', ')}`));
+        }
+        else {
+            console.log(chalk.gray('No device is marked worker, so `--device auto` still considers every online device.'));
+        }
+        console.log(chalk.gray('Sync it to the fleet with `agents repo push`.'));
+    };
     /** The interactive settings menu: pick a key, edit it, repeat. TTY-only. */
     const runDevicesConfigMenu = async (name) => {
         const { select, input, confirm } = await import('@inquirer/prompts');
@@ -1250,22 +1343,27 @@ function registerDevicesCommands(program) {
       agents devices config win-mini ssh.auth password          # password auth…
       agents devices config win-mini ssh.bundle muqsit          # …from this secrets bundle
       agents devices config worker ssh.identity-file ~/.ssh/worker_ed25519
+      agents devices config mac-mini role worker                 # same as \`agents devices role mac-mini worker\`
       agents devices config mac-mini auto-launch.enabled off    # exclude from AGI EXT auto-launch
       agents devices config mac-mini auto-launch.preferred on   # boost in auto-launch ranking
       agents devices config zion interactive.host zion          # user scope: where agents show YOU artifacts
       agents devices config mac-mini --json                     # machine-readable
     `,
         notes: `
-      Keys: agents.max-concurrent, scheduler.enabled, daemon.enabled,
-      watchdog.enabled, browser.remote-control, browser.profile, notes,
-      ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
+      Keys: role (worker|personal), see 'agents devices role',
+      agents.max-concurrent, scheduler.enabled, daemon.enabled,
+      watchdog.enabled, tmux.enabled, browser.remote-control, browser.profile,
+      notes, ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
       ssh.identity-file, platform (windows|linux|macos|unknown),
       auto-launch.enabled, auto-launch.preferred — plus the user-scope
       interactive.host (stored centrally; the device name is syntax only).
 
       Booleans take on/off (or true/false). 'notes' appends one entry per
-      invocation. Values land in ~/.agents/agents.yaml under
-      fleet.devices.<name>.config and sync with 'agents repo push/pull'.
+      invocation. Values a PEER reads land in ~/.agents/agents.yaml under
+      fleet.devices.<name>.config and sync with 'agents repo push/pull'. The
+      keys only the owning box reads — scheduler.enabled, daemon.enabled,
+      tmux.enabled, browser.remote-control, browser.profile — stay in that
+      machine's own doc, never sync, and can only be set on the device itself.
       ssh.* / platform / user overlay the discovered registry profile at dial
       time. scheduler.enabled / daemon.enabled take effect when the daemon
       reloads or restarts on that device.
@@ -1274,6 +1372,49 @@ function registerDevicesCommands(program) {
       set, set-interactive, enable, disable, prefer, unprefer.
     `,
     });
+    const roleCmd = devicesCmd
+        .command('role [name] [role]')
+        .description('Show or set what a device is for: worker (agents run here) or personal (you sit here — never picked automatically). ' +
+        'Marking any device worker makes `--device auto` an allowlist over the marked workers.')
+        .option('--clear', 'remove the mark, returning the device to unmarked')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, role, opts) => {
+        try {
+            await runDevicesRole(name, role, opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(roleCmd, {
+        examples: `
+      agents devices role                          # who is marked what, and what --device auto would pick
+      agents devices role yosemite-s0 worker       # agents spin up here
+      agents devices role yosemite-s1 worker       # …and here; auto now rotates over these two only
+      agents devices role zion personal            # your laptop — keep automatic placement off it
+      agents devices role yosemite-s0 --clear      # unmark
+      agents devices role --json                   # machine-readable
+    `,
+        notes: `
+      Roles are stored fleet-wide in ~/.agents/agents.yaml under
+      fleet.devices.<name>.config.role and travel with 'agents repo push/pull',
+      so a mark set on one box is the whole fleet's answer.
+
+      Effect on '--device auto' (agents run, teams, agents ssh auto, and the AGI
+      EXT launch commands, which all resolve placement through the CLI):
+        no device marked  -> every online device, as before
+        any worker marked -> ONLY the marked workers
+        personal          -> never picked, under either state
+
+      Turn the allowlist off with 'agents config set auto.pool all'; a personal
+      box stays excluded, since that is what the mark is for.
+
+      A paired iPhone/iPad cockpit is a separate role: 'agents devices pair-ios'
+      marks it control in that box's device registry, and the fleet never dials
+      it — including for placement. This command does not set that role.
+    `,
+    });
     /** Deprecation notice for a retired subcommand — STDERR only, so a --json consumer's stdout stays parseable. */
     const configTombstoneNotice = (retired, replacement) => {
         console.error(chalk.yellow(`Deprecated: "agents devices ${retired}" is now "agents devices ${replacement}". Running that for you.\n`));
@@ -1493,12 +1634,19 @@ function registerDevicesCommands(program) {
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         if (opts.json) {
+            const jsonRoles = listConfiguredDeviceRoles();
+            const autoPool = new Set(filterAutoPool(names, { roles: jsonRoles }));
             process.stdout.write(JSON.stringify(names.map((name) => {
                 const config = deviceConfigJson(name);
                 const health = statsMap?.get(name);
                 return {
                     ...resolveDeviceProfile(reg[name]),
                     interactive: name === interactiveHost,
+                    // Roles as machine-readable fields: `role` is what the operator
+                    // marked (absent when unmarked), `autoPool` is the answer that
+                    // matters to a caller — may `--device auto` pick this box.
+                    ...(jsonRoles[name] ? { role: jsonRoles[name] } : {}),
+                    autoPool: autoPool.has(name),
                     ...(config ? { config } : {}),
                     ...(health ? { health: { ...health, headroom: headroom(health) } } : {}),
                 };

package/dist/lib/config-keys.d.ts

@@ -9,7 +9,7 @@
 import type { AgentId } from './types.js';
 import { type ModelTier } from './model-tiers.js';
 /** The top-level scope of a unified config key. */
-export type ConfigScope = 'run' | 'interactive' | 'usage' | 'browser' | 'project' | 'device';
+export type ConfigScope = 'run' | 'interactive' | 'usage' | 'auto' | 'browser' | 'project' | 'device';
 /** A run-time default key: model, mode, effort, or tier override. */
 export interface ParsedRunConfigKey {
     scope: 'run';
@@ -28,6 +28,11 @@ export interface ParsedUsageConfigKey {
     scope: 'usage';
     property: 'primary-host';
 }
+/** Which devices automatic placement (`--device auto`) may pick. */
+export interface ParsedAutoConfigKey {
+    scope: 'auto';
+    property: 'pool';
+}
 /** The default browser profile (device-scope, self or peer). */
 export interface ParsedBrowserConfigKey {
     scope: 'browser';
@@ -44,8 +49,8 @@ export interface ParsedDeviceConfigKey {
     device: string;
     property: DeviceConfigProperty;
 }
-export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedUsageConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey;
-export type DeviceConfigProperty = 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'browser.remote-control' | 'notes' | 'browser.profile';
+export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedUsageConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey;
+export type DeviceConfigProperty = 'role' | 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'tmux' | 'browser.remote-control' | 'notes' | 'browser.profile';
 /** Normalize agent@version to use `@` consistently. */
 export declare function formatAgentVersion(agent: AgentId, version: string): string;
 /**
@@ -58,12 +63,15 @@ export declare function formatAgentVersion(agent: AgentId, version: string): str
  *   run.<agent@version>.tier.<cheap|default|best|ultra>
  *   interactive.host
  *   usage.primary-host
+ *   auto.pool
  *   browser.profile
  *   project.root
+ *   devices.<name>.role
  *   devices.<name>.max-agents
  *   devices.<name>.scheduler
  *   devices.<name>.daemon
  *   devices.<name>.watchdog
+ *   devices.<name>.tmux
  *   devices.<name>.browser.remote-control
  *   devices.<name>.notes
  *   devices.<name>.browser.profile

package/dist/lib/config-keys.js

@@ -10,10 +10,12 @@ import { AGENTS } from './agents.js';
 import { MODEL_TIERS } from './model-tiers.js';
 import { VERSION_RE } from './run-defaults.js';
 const DEVICE_CONFIG_PROPERTIES = [
+    'role',
     'max-agents',
     'scheduler',
     'daemon',
     'watchdog',
+    'tmux',
     'browser.remote-control',
     'notes',
     'browser.profile',
@@ -45,12 +47,15 @@ export function formatAgentVersion(agent, version) {
  *   run.<agent@version>.tier.<cheap|default|best|ultra>
  *   interactive.host
  *   usage.primary-host
+ *   auto.pool
  *   browser.profile
  *   project.root
+ *   devices.<name>.role
  *   devices.<name>.max-agents
  *   devices.<name>.scheduler
  *   devices.<name>.daemon
  *   devices.<name>.watchdog
+ *   devices.<name>.tmux
  *   devices.<name>.browser.remote-control
  *   devices.<name>.notes
  *   devices.<name>.browser.profile
@@ -75,13 +80,16 @@ export function parseConfigKey(key) {
     if (raw === 'usage.primary-host') {
         return { scope: 'usage', property: 'primary-host' };
     }
+    if (raw === 'auto.pool') {
+        return { scope: 'auto', property: 'pool' };
+    }
     if (raw === 'browser.profile') {
         return { scope: 'browser', property: 'profile' };
     }
     if (raw === 'project.root') {
         return { scope: 'project', property: 'root' };
     }
-    const deviceMatch = raw.match(/^devices\.(.+)\.(max-agents|scheduler|daemon|watchdog|notes|browser\.remote-control|browser\.profile)$/);
+    const deviceMatch = raw.match(/^devices\.(.+)\.(role|max-agents|scheduler|daemon|watchdog|tmux|notes|browser\.remote-control|browser\.profile)$/);
     if (deviceMatch) {
         return {
             scope: 'device',
@@ -99,6 +107,9 @@ export function parseConfigKey(key) {
     if (raw.startsWith('usage.')) {
         throw new Error(`Invalid usage config key '${key}'. Use usage.primary-host.`);
     }
+    if (raw.startsWith('auto.')) {
+        throw new Error(`Invalid auto config key '${key}'. Use auto.pool.`);
+    }
     if (raw.startsWith('browser.')) {
         throw new Error(`Invalid browser config key '${key}'. Use browser.profile.`);
     }
@@ -108,7 +119,7 @@ export function parseConfigKey(key) {
     if (raw.startsWith('devices.')) {
         throw new Error(`Invalid device config key '${key}'. Expected devices.<name>.<${DEVICE_CONFIG_PROPERTIES.join('|')}>.`);
     }
-    throw new Error(`Unknown config scope in '${key}'. Use one of: run, interactive, usage, browser, project, devices.`);
+    throw new Error(`Unknown config scope in '${key}'. Use one of: run, interactive, usage, auto, browser, project, devices.`);
 }
 /** Render a parsed key back to its canonical dotted string. */
 export function formatConfigKey(parsed) {
@@ -122,6 +133,8 @@ export function formatConfigKey(parsed) {
             return 'interactive.host';
         case 'usage':
             return 'usage.primary-host';
+        case 'auto':
+            return 'auto.pool';
         case 'browser':
             return parsed.device ? `devices.${parsed.device}.browser.profile` : 'browser.profile';
         case 'project':
@@ -137,7 +150,7 @@ export function listKnownConfigKeys() {
     for (const tier of MODEL_TIERS) {
         keys.push(`run.<agent@version>.tier.${tier}`);
     }
-    keys.push('interactive.host', 'usage.primary-host', 'browser.profile', 'project.root');
+    keys.push('interactive.host', 'usage.primary-host', 'auto.pool', 'browser.profile', 'project.root');
     for (const prop of DEVICE_CONFIG_PROPERTIES) {
         keys.push(`devices.<name>.${prop}`);
     }
@@ -150,6 +163,8 @@ export function listKnownConfigKeys() {
  */
 export function devicePropertyToConfigName(property) {
     switch (property) {
+        case 'role':
+            return 'role';
         case 'max-agents':
             return 'agents.max-concurrent';
         case 'scheduler':
@@ -158,6 +173,8 @@ export function devicePropertyToConfigName(property) {
             return 'daemon.enabled';
         case 'watchdog':
             return 'watchdog.enabled';
+        case 'tmux':
+            return 'tmux.enabled';
         case 'browser.remote-control':
             return 'browser.remote-control';
         case 'notes':
@@ -181,6 +198,8 @@ export function configKeyStorageHint(parsed) {
             return 'config.interactiveHost';
         case 'usage':
             return 'config.usagePrimaryHost';
+        case 'auto':
+            return 'config.autoPool';
         case 'browser':
             return parsed.device
                 ? `fleet.devices.${parsed.device}.config.defaultBrowserProfile`

package/dist/lib/config-machine-keys.js

@@ -14,4 +14,5 @@ export const MACHINE_LOCAL_YAML_KEYS = new Set([
     'browserRemoteControl', // browser.remote-control — a consent flag; syncing it is a leak
     'schedulerEnabled', // scheduler.enabled
     'daemonEnabled', // daemon.enabled
+    'tmuxEnabled', // tmux.enabled — whether an interactive run is tmux-wrapped on THIS box
 ]);

package/dist/lib/device-config.d.ts

@@ -91,6 +91,10 @@ export interface ConfigEntry {
 export interface ConfigTarget {
     device?: string;
 }
+/** Roles a device can be marked with — see the `role` key below. */
+declare const DEVICE_ROLES: readonly ["worker", "personal"];
+/** Which devices automatic placement may pick — see the `auto.pool` key below. */
+declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 export declare function configKeySpec(name: string): ConfigKeySpec;
@@ -140,6 +144,27 @@ export declare function resolveUsagePrimaryHost(): string | null;
 export declare function setConfigValue(name: string, value: unknown, opts?: ConfigTarget): void;
 /** Unset a config key — restores default behavior. No-op when already unset. */
 export declare function unsetConfigValue(name: string, opts?: ConfigTarget): void;
+/** A role an operator marked a device with (`agents devices role <name> <role>`). */
+export type ConfiguredDeviceRole = (typeof DEVICE_ROLES)[number];
+/** Which devices automatic placement may pick (`auto.pool`). */
+export type AutoPoolMode = (typeof AUTO_POOL_MODES)[number];
+/**
+ * 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 declare function configuredDeviceRole(name: string): ConfiguredDeviceRole | undefined;
+/** Mark a device's role fleet-wide; `undefined` clears the mark. */
+export declare function setConfiguredDeviceRole(name: string, role: ConfiguredDeviceRole | undefined): void;
+/**
+ * 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 declare function listConfiguredDeviceRoles(): Record<string, ConfiguredDeviceRole>;
+/** The configured automatic-placement pool mode. Unset means `workers`. */
+export declare function autoPoolMode(): AutoPoolMode;
 /** A device's auto-launch flags, as read by the ext's launch ranking. */
 export interface AutoLaunchPreference {
     enabled?: boolean;
@@ -167,6 +192,15 @@ export declare function isSchedulerEnabled(): boolean;
  * scheduler init) refuses with.
  */
 export declare function assertSchedulerEnabled(): void;
+/**
+ * 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 declare function isTmuxEnabled(): boolean;
 /** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export declare function isDaemonEnabled(): boolean;
 /**