@phnx-labs/agents-cli 1.22.37 → 1.22.39

package/dist/lib/browser/types.d.ts

@@ -77,6 +77,20 @@ export interface Task {
     tabs: Record<string, string>;
     currentTabId?: string;
     createdAt: number;
+    /**
+     * When this task last did anything. Stamped at creation (equal to
+     * `createdAt`) and refreshed by every task-scoped action, because every one
+     * of them resolves the task through `BrowserService.findTask`.
+     *
+     * Read by the idle half of the abandoned-task reaper (`hygiene.ts`): a task
+     * nobody has driven for `idleMs` is stopped so its tabs stop piling up in the
+     * profile window (RUSH-2622).
+     *
+     * Persisted in tasks.json. Tasks written before RUSH-2622 carry none;
+     * `loadTaskState` normalizes those to `createdAt` on read, so every task in
+     * memory has one and the reaper never has to guess.
+     */
+    lastActionAt: number;
     pid: number;
     /**
      * Resolved actor id (`resolveActor().id`) stamped at task start — WHO launched
@@ -151,7 +165,24 @@ export interface HistoricalTask {
     /** Actor id who launched the task (RUSH-2020); absent for pre-RUSH-2020 history. */
     owner?: string;
 }
-export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+/**
+ * Why the reaper stopped a task. `session-dead` — the agent session (or run)
+ * that started it is provably gone; `idle` — nothing has driven it for the
+ * idle window. See `hygiene.ts`.
+ */
+export type ReapReason = 'session-dead' | 'idle';
+/** One task the reaper stopped (or, under `dryRun`, would have stopped). */
+export interface ReapedTask {
+    task: string;
+    profile: string;
+    reason: ReapReason;
+}
+export interface ReapResult {
+    closed: ReapedTask[];
+    /** Tasks left alone this pass: still live, still inside the idle window, or recording. */
+    skipped: number;
+}
+export type IPCAction = 'start' | 'gc' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -201,6 +232,16 @@ export interface IPCRequest {
     until?: string;
     appLevel?: string;
     skipDomainSkill?: boolean;
+    /**
+     * Browser start: always open a new tab. Without it, `start --url` reclaims a
+     * tab that an ABANDONED task is still holding on this exact URL rather than
+     * opening a duplicate (RUSH-2622). A tab held by a live task, or one nobody's
+     * task owns (the user's own), is never taken either way — set this when the
+     * caller wants its own tab regardless.
+     */
+    fresh?: boolean;
+    idleMinutes?: number;
+    dryRun?: boolean;
     actor?: string;
     launchId?: string;
     /**
@@ -236,6 +277,8 @@ export interface IPCResponse {
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
     history?: HistoricalTask[];
+    /** `gc`: what the abandoned-task reaper closed (or would close under dryRun). */
+    reaped?: ReapResult;
     result?: unknown;
     path?: string;
     bytes?: number;

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;
 /**

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/git.d.ts

@@ -123,7 +123,7 @@ export declare function _resetSnapshotShaCacheForTest(): void;
  */
 export declare function getGitHubUsername(): Promise<string | null>;
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed

package/dist/lib/git.js

@@ -437,7 +437,7 @@ function readGitConfigUser() {
     }
 }
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed