@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/commands/ssh.js

@@ -18,10 +18,12 @@ import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { assertRegistrableDeviceName } from '../lib/devices/registry.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../lib/devices/interactive-host.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { registerFleetApplyAlias } from './apply.js';
-import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
+import { addIgnored, getDevice, loadDevices, loadIgnored, loadIgnoredEntries, removeDevice, removeIgnored, upsertDevice, writeReachability, } from '../lib/devices/registry.js';
 import { resolveDeviceProfile } from '../lib/devices/resolve-profile.js';
 import { collectReachabilityWriteBacks, deviceOnlineState } from '../lib/devices/reachability.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
@@ -47,7 +49,7 @@ import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { listTasks, resolveTaskRef } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { stopDispatchedTask } from '../lib/hosts/dispatch.js';
-import { terminalWidth, truncateToWidth } from '../lib/session/width.js';
+import { stringWidth, stripAnsi, terminalWidth, truncateToWidth } from '../lib/session/width.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { collectLocalHarnessInventory, groupByAccount, renderAccountsMatrix, renderHarnessMatrix, } from '../lib/devices/harness-inventory.js';
@@ -113,30 +115,106 @@ function pctCell(v, width) {
         return chalk.yellow(s);
     return chalk.red(s);
 }
+/** Floor for the `spec` column; the real width is measured from the rows.
+ *
+ * A fixed width cannot work here: `fmtBytes` emits an optional decimal, so a
+ * spec string runs from `8c 16G 256G` (11) to `10c 23.5G 460G` (14) depending
+ * purely on the hardware behind it. Anything narrower than the widest row
+ * pushes load/mem/disk/headroom out of alignment row-to-row AND against the
+ * header — which defeats the scannability this column exists for. */
+const SPEC_WIDTH_MIN = 12;
+/** The static hardware as one compact cell — `12c 64G 1T`: cores, total RAM,
+ * total root disk via fmtBytes. `—` only when no probe has ever seen the box.
+ *
+ * Deliberately NOT gated on `reachable`: hardware does not change while a
+ * machine is down, so an offline device keeps rendering the spec from its last
+ * successful probe (`retainHardwareFacts`, RUSH-3096) rather than blanking a
+ * fact that is still true. The volatile columns beside it — load, mem, disk
+ * used — stay `—`, and `fleetCapacity` still counts only reachable boxes, so
+ * a down machine never contributes to usable capacity.
+ *
+ * Unpadded; {@link renderDeviceTable} pads to the measured column width. */
+function specText(stats) {
+    if (!stats?.ncpu)
+        return '—';
+    return `${stats.ncpu}c ${fmtBytes(stats.memTotalBytes)} ${fmtBytes(stats.diskTotalBytes)}`;
+}
+/** The widest spec string across the rows actually being rendered, floored at
+ * SPEC_WIDTH_MIN so a short fleet still lines up with the header. */
+function specColumnWidth(names, statsMap) {
+    return Math.max(SPEC_WIDTH_MIN, ...names.map((n) => stringWidth(specText(statsMap.get(n)))));
+}
+/** Colour + pad one spec cell to the measured column width. */
+function specCell(stats, width) {
+    const text = specText(stats);
+    return (text === '—' ? chalk.gray : chalk.greenBright)(text.padEnd(width));
+}
+/** The one-line `description` config value per device (absent when unset). */
+function listDeviceDescriptions(names) {
+    const out = {};
+    for (const n of names) {
+        const v = getConfigValue('description', { device: n }).value;
+        if (typeof v === 'string' && v.length > 0)
+            out[n] = v;
+    }
+    return out;
+}
+/**
+ * Fit a device row to the terminal width. The description is the FIRST thing
+ * to truncate, then the role tag; the fixed columns (device, platform, spec,
+ * load/mem/disk numbers, headroom, and the ▸/★/←/relay markers) never
+ * truncate. `role` and `desc` arrive fully rendered (ansi + leading gap).
+ */
+function fitDeviceRow(fixed, role, desc, width) {
+    const w = (s) => stringWidth(stripAnsi(s));
+    let over = w(fixed) + w(role) + w(desc) - width;
+    if (over > 0 && desc) {
+        // `desc` is '  ' + gray(text) — truncate the text, keep the gap.
+        const text = stripAnsi(desc).slice(2);
+        const budget = w(text) - over;
+        desc = budget > 0 ? '  ' + chalk.gray(truncateToWidth(text, budget)) : '';
+        over = w(fixed) + w(role) + w(desc) - width;
+    }
+    // A partial role word ("work…") reads as a bug — when it can't fit whole,
+    // it drops entirely. The numbers are never touched.
+    if (over > 0 && role)
+        role = '';
+    return fixed + role + desc;
+}
 /**
  * Render the device list. When `statsMap` is provided, resource columns are
- * appended — normalized load, memory, a headroom badge, and (in `full` mode)
- * core count and free/total memory — so it's obvious which boxes have room.
+ * appended — a `spec` cell (cores / total RAM / total disk), normalized load,
+ * memory and disk-used percentages, a headroom badge, and (in `full` mode)
+ * free/total memory — with the per-device role and `description` riding the
+ * tail, so it's obvious which boxes have room and what each box is for.
  * Without it (probe skipped) the classic reachability line is used. A fleet
  * capacity summary is appended whenever stats were gathered.
  */
-function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
+export function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost, opts = {}) {
     if (!statsMap) {
         const roles = listConfiguredDeviceRoles(names);
         return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost, roles));
     }
     const deviceRoles = listConfiguredDeviceRoles(names);
+    const specWidth = specColumnWidth(names, statsMap);
+    const descriptions = listDeviceDescriptions(names);
+    const width = opts.width ?? terminalWidth();
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
         chalk.gray('platform'.padEnd(8)) +
         ' ' +
-        (full ? chalk.gray('cores'.padStart(6)) : '') +
+        chalk.gray('spec'.padEnd(specWidth)) +
         chalk.gray('load'.padStart(5)) +
         chalk.gray('mem'.padStart(6)) +
+        chalk.gray('disk'.padStart(5)) +
         (full ? '  ' + chalk.gray('free/total'.padEnd(12)) : '') +
         '  ' +
-        chalk.gray('headroom');
+        chalk.gray('headroom') +
+        '  ' +
+        chalk.gray('role') +
+        '  ' +
+        chalk.gray('description');
     lines.push(head);
     for (const name of names) {
         // Effective profile: the operator's central config (ssh.*/platform/user)
@@ -147,18 +225,30 @@ function renderDeviceTable(reg, names, self, statsMap, full = false, interactive
         const label = isSelf ? chalk.bold.cyan(name.padEnd(16)) : chalk.bold(name.padEnd(16));
         const plat = String(d.platform).padEnd(8);
         const stats = statsMap.get(name);
+        const role = roleTag(name, deviceRoles);
+        const desc = descriptions[name] ? '  ' + chalk.gray(descriptions[name]) : '';
         // Prefer this run's live probe, then the written-back verdict, over the
         // stale tailscale.online snapshot — so a reachable box never renders
         // "offline" while its live load/mem sit one column over (RUSH-1965).
         const offline = deviceOnlineState(d, stats) === 'offline';
         if (offline) {
-            lines.push(`${marker}${label}${plat} ${chalk.gray('offline')}`);
+            // The spec cell rides the offline row: hardware is what the box IS, not
+            // what it is doing, so it stays legible while the machine is down
+            // (RUSH-3096). The live columns are omitted rather than dashed — there is
+            // no current load/mem/disk to report for a box that did not answer.
+            //
+            // The explicit gap is load-bearing: `specCell` pads to the MEASURED
+            // column width, so the widest spec on the fleet pads to nothing and the
+            // marker would collide with it ("455Goffline"). An online row gets its
+            // separation for free from `pctCell`'s right-alignment; this one has no
+            // numeric cell to lean on.
+            lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}  ${chalk.gray('offline')}`, role, desc, width));
             continue;
         }
         const relay = !isSelf && d.tailscale?.online && !d.tailscale.direct ? chalk.yellow(' relay') : '';
-        const cores = full ? chalk.gray(String(stats?.ncpu ?? '—').padStart(6)) : '';
         const load = pctCell(stats?.loadPercent, 5);
         const mem = pctCell(stats?.memPercent, 6);
+        const disk = pctCell(stats?.diskUsedPercent, 5);
         const freeTotal = full
             ? '  ' +
                 (stats?.reachable && stats.memTotalBytes
@@ -168,13 +258,21 @@ 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}${roleTag(name, deviceRoles)}`);
+        lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}${load}${mem}${disk}${freeTotal}  ${badge}${relay}${here}${interactive}`, role, desc, width));
     }
-    // Fleet capacity summary — total cores + how much RAM is free right now.
+    // Fleet capacity summary — total cores, how much RAM is free right now, and
+    // total free root disk across the reachable fleet.
     const cap = fleetCapacity(statsMap.values());
     if (cap.reachable > 0) {
         const freePct = cap.memTotalBytes > 0 ? Math.round((cap.memFreeBytes / cap.memTotalBytes) * 100) : 0;
-        lines.push(chalk.gray(`  Fleet capacity: ${cap.cores} cores · ${fmtBytes(cap.memFreeBytes)} free / ${fmtBytes(cap.memTotalBytes)} RAM (${freePct}% free) across ${cap.reachable} reachable device${cap.reachable === 1 ? '' : 's'}`));
+        let diskFreeBytes = 0;
+        for (const s of statsMap.values())
+            if (s.reachable)
+                diskFreeBytes += s.diskFreeBytes ?? 0;
+        lines.push(chalk.gray(`  Fleet capacity: ${cap.cores} cores · ${fmtBytes(cap.memFreeBytes)} free / ${fmtBytes(cap.memTotalBytes)} RAM (${freePct}% free) · ${fmtBytes(diskFreeBytes)} disk free across ${cap.reachable} reachable device${cap.reachable === 1 ? '' : 's'}`));
+    }
+    if (opts.ignoredCount) {
+        lines.push(chalk.gray(`  ${opts.ignoredCount} ignored node${opts.ignoredCount === 1 ? '' : 's'} not listed — 'agents devices ignored'`));
     }
     return lines;
 }
@@ -975,6 +1073,7 @@ function registerDevicesCommands(program) {
         agents devices sync            # pick which tailscale nodes to keep (TTY)
         agents devices sync --yes      # register all non-ignored nodes
         agents devices ignore ipad165  # dismiss a node so it's never re-suggested
+        agents devices ignored         # list dismissed nodes (when / which machine)
 
       Inspect:
         agents devices list            # what's registered (★ = interactive host)
@@ -990,6 +1089,7 @@ function registerDevicesCommands(program) {
         agents devices config win-mini ssh.auth password
         agents devices config worker ssh.identity-file ~/.ssh/worker_ed25519
         agents devices config mac-mini auto-launch.enabled off
+        agents devices describe mark-1 "gpu box — cuda 12.4"  # one-line purpose, shown in the list
         agents devices config mac-mini interactive.host zion # where agents show YOU artifacts
         agents devices render --write  # write ~/.ssh/config.d/agents include
 
@@ -1002,10 +1102,10 @@ function registerDevicesCommands(program) {
     registerLeaseCommand(devicesCmd);
     registerSnapshotCommand(devicesCmd);
     registerCommandGroups(devicesCmd, [
-        { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'rm'] },
+        { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'ignored', 'remove'] },
         { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts', 'snapshot'] },
         { title: 'Disposable devices', names: ['lease'] },
-        { title: 'Configure a device', names: ['config', 'render'] },
+        { title: 'Configure a device', names: ['config', 'describe', 'render'] },
         { title: 'Fleet operations', names: ['update', 'run', 'login', 'capture', 'apply'] },
     ]);
     devicesCmd
@@ -1085,6 +1185,47 @@ function registerDevicesCommands(program) {
         setDeviceDiscoveryStatus(name, undefined);
         console.log(chalk.green(`No longer ignoring '${name}'`) + chalk.gray(' — run `agents devices sync` to register it.'));
     });
+    const ignoredCmd = devicesCmd
+        .command('ignored')
+        .description('List dismissed tailscale nodes — what was dismissed, when, and on which machine.')
+        .option('--json', 'output machine-readable JSON')
+        .action((opts) => {
+        try {
+            const entries = loadIgnoredEntries();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+                return;
+            }
+            if (entries.length === 0) {
+                console.log(chalk.gray("No ignored nodes. 'agents devices ignore <name>' dismisses one — it won't be re-suggested."));
+                return;
+            }
+            console.log(chalk.bold(`Ignored nodes (${entries.length})`));
+            for (const e of entries) {
+                const age = formatCheckedAge(Date.parse(e.ignoredAt));
+                console.log(`  ${chalk.bold(e.name.padEnd(24))} ${chalk.gray(`${age} · dismissed on ${e.ignoredOn}`)}`);
+            }
+            console.log(chalk.gray("Undo one with 'agents devices unignore <name>'."));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(ignoredCmd, {
+        examples: `
+      agents devices ignored          # what was dismissed, when, and on which machine
+      agents devices ignored --json   # machine-readable [{ name, ignoredAt, ignoredOn }]
+      agents devices unignore old-laptop   # undo a dismissal
+    `,
+        notes: `
+      Dismissals live in the tracked central agents.yaml (fleet.ignored) and
+      sync with 'agents repo push/pull', so a node dismissed on one box stays
+      dismissed everywhere. An ignored node is not a device — it never enters
+      the registry, so 'agents devices list' never shows it; this command is
+      where dismissals are visible.
+    `,
+    });
     // ─── devices config (unified settings surface) ────────────────────────────
     //
     // ONE command for every per-device setting: `agents devices config <name>
@@ -1461,6 +1602,8 @@ function registerDevicesCommands(program) {
     `,
         notes: `
       Keys: role (worker|personal), see 'agents devices role',
+      description (one line saying what the box is for — see
+      'agents devices describe'; renders in the devices list tail),
       agents.max-concurrent, scheduler.enabled, daemon.enabled,
       watchdog.enabled, tmux.enabled, browser.remote-control,
       browser.task-idle-minutes, browser.profile,
@@ -1529,6 +1672,40 @@ function registerDevicesCommands(program) {
       box stays excluded, since that is what the mark is for.
     `,
     });
+    const describeCmd = devicesCmd
+        .command('describe <name> [text...]')
+        .description('Show or set the one-line description of what a device is FOR ("gpu box — cuda 12.4"). ' +
+        'Rendered as the tail column of `agents devices list` and synced fleet-wide. ' +
+        'Same key as `agents devices config <name> description` — one store, two names.')
+        .option('--unset', 'remove the description (the device falls back to the fleet default / unset)')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, textParts, opts) => {
+        try {
+            // Thin sugar over the 'description' config key — the same engine that
+            // backs `agents devices config <name> description`, not a second path.
+            await runDevicesConfig(name, 'description', textParts ?? [], opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(describeCmd, {
+        examples: `
+      agents devices describe mark-1 "gpu box — cuda 12.4"  # set it (80 chars, one line)
+      agents devices describe mark-1                        # read it back
+      agents devices describe mark-1 --unset                # remove it
+      agents devices describe mark-1 --json                 # machine-readable
+      agents devices config mark-1 description "gpu box"    # equivalent — same store
+    `,
+        notes: `
+      The description is the device-scope 'description' config key: stored in
+      the tracked per-device doc (devices/<name>/agents.yaml config: block),
+      synced fleet-wide with 'agents repo push/pull', and rendered as the tail
+      column of 'agents devices list'. It replaces on each set — for appended
+      long-form scratch use 'agents devices config <name> notes "…"'.
+    `,
+    });
     /** 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`));
@@ -1753,6 +1930,7 @@ function registerDevicesCommands(program) {
             process.stdout.write(JSON.stringify(names.map((name) => {
                 const config = deviceConfigJson(name);
                 const health = statsMap?.get(name);
+                const description = getConfigValue('description', { device: name }).value;
                 return {
                     ...resolveDeviceProfile(reg[name]),
                     interactive: name === interactiveHost,
@@ -1760,6 +1938,7 @@ function registerDevicesCommands(program) {
                     // marked (absent when unmarked), `autoPool` is the answer that
                     // matters to a caller — may `--device auto` pick this box.
                     ...(jsonRoles[name] ? { role: jsonRoles[name] } : {}),
+                    ...(typeof description === 'string' && description ? { description } : {}),
                     autoPool: autoPool.has(name),
                     ...(config ? { config } : {}),
                     ...(health ? { health: { ...health, headroom: headroom(health) } } : {}),
@@ -1768,7 +1947,10 @@ function registerDevicesCommands(program) {
             return;
         }
         console.log(chalk.bold(`Devices (${names.length})`));
-        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost))
+        // Dismissed nodes are not devices (never in the registry) — surface their
+        // count under the table so a "missing" node is explainable from the list.
+        const ignoredCount = loadIgnoredEntries().length;
+        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost, { ignoredCount }))
             console.log(line);
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));
@@ -1789,7 +1971,7 @@ function registerDevicesCommands(program) {
     devicesCmd
         .command('list')
         .alias('ls')
-        .description('List registered devices with platform, address, reachability, and live resource headroom.')
+        .description('List registered devices with platform, spec (cores/RAM/disk), live load/mem/disk headroom, role, and description.')
         .option('--json', 'output effective device profiles, config, and health as a JSON array')
         .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
         .option('--refresh', 'force a live probe of every device, bypassing the cache')
@@ -1832,6 +2014,36 @@ function registerDevicesCommands(program) {
         await runFleetPing({ ...opts, verbose });
     });
     const csvList = (s) => s ? s.split(',').map((x) => x.trim()).filter(Boolean) : undefined;
+    devicesCmd
+        .command('pick')
+        .description('Print the device automatic placement would choose for offloaded machine work (the suite, a build) — least-loaded, reachable, POSIX, never the box you are sitting at. Writes just the name to stdout so scripts can consume it.')
+        .option('--json', 'output the pick plus every candidate and exclusion reason')
+        .option('--platform <list>', 'comma-separated platforms to allow (default: linux,macos)')
+        .action(async (opts) => {
+        const { resolveWorkerDevice } = await import('../lib/devices/worker-pick.js');
+        let plan;
+        try {
+            plan = await resolveWorkerDevice({ platforms: csvList(opts.platform) });
+        }
+        catch (err) {
+            // Fail loud with the resolver's own message. Never print a device name
+            // we did not actually pick: a caller reading stdout would ship a tree to it.
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(plan, null, 2));
+            return;
+        }
+        // stdout is the name alone (`box="$(agents devices pick)"`); the human
+        // detail goes to stderr so it never pollutes that capture.
+        const detail = plan.candidates
+            .map((c) => `${c.device}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
+            .join(' ');
+        console.error(chalk.gray(`[agents] worker=${plan.device}${plan.isLocal ? ' (this machine)' : ''}  candidates: ${detail}`));
+        console.log(plan.device);
+    });
     const harnessInvOpts = (opts) => ({
         agents: csvList(opts.agents),
         devices: csvList(opts.device ?? opts.devices),
@@ -1924,6 +2136,10 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         .option('--platform <platform>', 'windows | linux | macos')
         .action(async (name, target, opts) => {
         try {
+            // The one place a device name is CHOSEN rather than observed, so the one
+            // place the reserved-sentinel policy belongs. upsertDevice itself stays
+            // shape-only — `devices sync` feeds it tailnet node names in a loop.
+            assertRegistrableDeviceName(name);
             const { host, user } = splitUserHost(target);
             const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
             const d = await upsertDevice(name, {
@@ -1987,8 +2203,8 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         }
     });
     devicesCmd
-        .command('rm <name>')
-        .alias('remove')
+        .command('remove <name>')
+        .alias('rm')
         .description('Remove a device from the registry.')
         .action(async (name) => {
         const ok = await removeDevice(name);
@@ -2190,6 +2406,15 @@ the target when it exists, else the remote home. Same portable-cwd rule as
         // nothing to resolve "self" to, and mis-report the pick as "Unknown
         // device").
         let target = name;
+        if (isDeviceInteractive(name)) {
+            const pinned = resolveInteractiveDevice();
+            if (!pinned) {
+                console.error(chalk.red(interactiveUnsetError()));
+                process.exit(1);
+            }
+            process.stderr.write(chalk.gray(`[agents] device=interactive → ${pinned}\n`));
+            target = pinned;
+        }
         if (isDeviceAuto(name)) {
             const plan = resolveDeviceAffinity({});
             if (!plan.host) {

package/dist/commands/teams.js

@@ -18,6 +18,7 @@ import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } f
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, commitsBehindDefault, isGitRepo, hasUncommittedChanges, removeWorktree, worktreeCheckoutExists, worktreeExists, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../lib/devices/interactive-host.js';
 import { isDeviceAuto, resolveDeviceAuto } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { ensureHostReady } from '../lib/hosts/ready.js';
@@ -1369,7 +1370,22 @@ export function registerTeamsCommands(program) {
             // trim, drop blanks, dedupe (preserving first-seen order).
             const rawPool = [opts.devices, opts.hosts].filter(Boolean).join(',');
             const devices = [];
-            for (const d of rawPool.split(',').map((s) => s.trim()).filter(Boolean)) {
+            for (const raw of rawPool.split(',').map((s) => s.trim()).filter(Boolean)) {
+                // Resolve `interactive` to the concrete device HERE, the same way the
+                // single `--device` pin does. A pool is a set of specific machines the
+                // scheduler picks between, so persisting the sentinel would let the
+                // pool's membership change silently the next time `interactive.host`
+                // is re-pinned — and every later friction message would quote
+                // "interactive" instead of a box the user can act on.
+                let d = raw;
+                if (isDeviceInteractive(d)) {
+                    const pinned = resolveInteractiveDevice();
+                    if (!pinned) {
+                        dieFriction('teams', 'pool-device-interactive-unset', interactiveUnsetError());
+                    }
+                    process.stderr.write(chalk.gray(`[teams] pool device=interactive → ${pinned}\n`));
+                    d = pinned;
+                }
                 if (!devices.includes(d))
                     devices.push(d);
             }
@@ -1444,7 +1460,7 @@ export function registerTeamsCommands(program) {
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
-        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip. Teammates run headless: plan works headless on claude/codex/cursor/droid/opencode; kimi/grok/antigravity have no headless plan mode and auto-downgrade a plan request to auto.`, 'edit')
+        .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (more autonomous than edit, mechanism per-harness — see 'agents modes <agent>') | skip (bypass all permission prompts). 'full' accepted as alias for skip. Teammates run headless: plan works headless on claude/codex/cursor/droid/opencode; kimi/grok/antigravity have no headless plan mode and auto-downgrade a plan request to auto.`, 'edit')
         .option('-e, --effort <effort>', `Reasoning intensity: ${VALID_EFFORTS.join('|')}`, 'medium')
         .option('--model <model>', 'Cost tier (cheap|default|best|ultra) or a concrete id (e.g. claude-opus-4-8); tiers resolve per harness+version to a supported model')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
@@ -1507,6 +1523,22 @@ export function registerTeamsCommands(program) {
             process.stderr.write(chalk.gray(`[teams] device=auto → ${picked === machineId() ? 'local' : picked}\n`));
             explicitDevice = picked;
         }
+        // `interactive` needs the same up-front resolution, and for a sharper
+        // reason: `teams add`/`create` bail out of the fleet passthrough
+        // (passthrough.ts, the teams subcommand guard), so the sentinel block
+        // there never runs and this is the only resolver. Left literal, the
+        // local-machine check below compares 'interactive' against the machine id,
+        // takes the remote branch on the pinned box itself, and pins the teammate
+        // to an SSH hop into this same machine — skipping three local preflights
+        // on the way.
+        if (explicitDevice && isDeviceInteractive(explicitDevice)) {
+            const pinned = resolveInteractiveDevice();
+            if (!pinned) {
+                dieFriction('teams', 'device-interactive-unset', interactiveUnsetError());
+            }
+            process.stderr.write(chalk.gray(`[teams] device=interactive → ${pinned === machineId() ? 'local' : pinned}\n`));
+            explicitDevice = pinned;
+        }
         // Distributed teams: --device <name> PINS this teammate to a machine over
         // SSH. Resolve + validate the placement here so a bad target fails at `add`
         // time, not silently at launch. Persisted (hostName/hostTarget/repoPath) so

package/dist/commands/traces.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerTracesCommands(program: Command): void;