@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/commands/sessions.js

@@ -46,7 +46,6 @@ import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
-import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerSessionsFavoriteCommand } from './sessions-favorite.js';
 import { isFavorite, listFavorites } from '../lib/session/favorites.js';
@@ -1044,7 +1043,11 @@ export async function gatherActiveSessions(opts = {}) {
     const self = machineId();
     // An explicit --host/--device list scopes the view: seed local sessions only
     // when no hosts are named, or when this machine is one of the named targets.
-    const local = shouldIncludeLocal(opts.hosts, self) ? await getActiveSessions() : [];
+    // `localOnly: opts.local` (RUSH-2118) keeps a `--local` query from dialing a
+    // remote-host teammate over ssh even for this machine's OWN local gather —
+    // "this machine only" must mean zero ssh, not just "skip the cross-machine
+    // device fan-out below".
+    const local = shouldIncludeLocal(opts.hosts, self) ? await getActiveSessions({ localOnly: opts.local }) : [];
     for (const s of local)
         if (!s.machine)
             s.machine = self;
@@ -1218,7 +1221,7 @@ function canonicalSessionsCommand(query, options) {
 }
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
-async function renderSessionPreview(query, scope) {
+export async function renderSessionPreview(query, scope) {
     const discovered = await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 });
     const pool = applyScopeFilters(discovered, scope);
     const { matches, completeId } = resolveSessionQuery(pool, query);
@@ -1234,9 +1237,11 @@ async function renderSessionPreview(query, scope) {
     }
     // Lead with the live status when the session is still running, so the preview
     // says working / waiting / idle up front — not just the historical transcript.
+    // `--local --preview` is freely combinable with `--local` (RUSH-2118): thread
+    // it through so this probe never dials a remote-host teammate either.
     let live;
     try {
-        live = indexActiveBySessionId(await getActiveSessions()).get(session.id);
+        live = indexActiveBySessionId(await getActiveSessions({ localOnly: scope.local === true })).get(session.id);
     }
     catch { /* plain preview on any probe failure */ }
     const headline = formatLiveStatusHeadline(live, isFavorite(session.id));
@@ -1390,7 +1395,7 @@ limitSource) {
             console.error(chalk.red('--preview requires a session id or query.'));
             process.exit(1);
         }
-        await renderSessionPreview(query, { agent: options.agent, project: options.project });
+        await renderSessionPreview(query, { agent: options.agent, project: options.project, local: options.local });
         return;
     }
     if (options.active) {
@@ -1907,11 +1912,15 @@ function treeSessionRow(session, live) {
  * not a hot loop, so the `ps`/`lsof` cost is acceptable; `--no-live` is the
  * escape hatch. Never throws — a probe failure just yields a plain listing.
  */
-async function maybeLiveIndex(options) {
+export async function maybeLiveIndex(options) {
     if (options.live === false || options.json)
         return undefined;
     try {
-        return indexActiveBySessionId(await getActiveSessions());
+        // `--local` promises "this machine only" for the default listing too (see
+        // the `--local` help text), so it must gate the live-enrichment probe the
+        // same way `--active --local` does — never dial a remote-host teammate
+        // over ssh here either (RUSH-2118).
+        return indexActiveBySessionId(await getActiveSessions({ localOnly: options.local === true }));
     }
     catch {
         return undefined;
@@ -3387,7 +3396,6 @@ export function registerSessionsCommands(program) {
         await sessionsAction(query, options, command.getOptionValueSource('limit'));
     });
     registerSessionsTailCommand(sessionsCmd);
-    registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerSessionsFavoriteCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);

package/dist/commands/setup-browser.js

@@ -13,6 +13,7 @@ import { findFirstInstalledBrowser, listInstalledBrowsers } from '../lib/browser
 import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, getProfile, } from '../lib/browser/profiles.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { defaultBrowserChoice } from './setup-preferences.js';
 const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, or Comet, then re-run `agents setup browser`.\n' +
     '(Safari and Firefox are not supported — agents browser drives over the Chrome DevTools Protocol.)';
 /**
@@ -58,11 +59,14 @@ export async function runBrowserWizard() {
         const { deleteProfile } = await import('../lib/browser/profiles.js');
         await deleteProfile(existing.name);
     }
-    // Pick which installed browser to pin (auto-select if only one).
+    // Pick which installed browser to pin (auto-select if only one). The picker
+    // highlights the same browser auto-detect would win — choosing is an
+    // override of the default, never a guess.
     let chosen = installed[0];
     if (installed.length > 1) {
         const value = await select({
             message: 'Which browser should the default profile use?',
+            default: defaultBrowserChoice(installed) ?? undefined,
             choices: installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
         });
         chosen = installed.find((b) => b.browserType === value) ?? installed[0];

package/dist/commands/setup-fleet.js

@@ -12,6 +12,7 @@ import { loadDevices } from '../lib/devices/registry.js';
 import { runDeviceSync } from '../lib/devices/sync.js';
 import { tailscaleStatusJson } from '../lib/devices/tailscale.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { maybePickInteractiveHost } from './setup-preferences.js';
 function parseAuth(raw) {
     const value = (raw ?? 'key').toLowerCase();
     if (value === 'key' || value === 'password')
@@ -171,6 +172,10 @@ export async function runFleetSetupWizard(opts = {}) {
     if (choices.fleetUpdate)
         runAgentsSubcommand(['fleet', 'update']);
     printOnboardingSummary(names, choices.auth);
+    // With a fleet registered, the next wrong-machine trap is artifacts opening on
+    // some other box — offer to pin the interactive host (TTY-only, skippable,
+    // silent non-TTY and when already set).
+    await maybePickInteractiveHost();
     return true;
 }
 /** Register `agents setup fleet` under the parent `setup` command. */

package/dist/commands/setup-preferences.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Preferences onboarding — the guided path over the same device-config keys the
+ * `agents devices …` commands write (lib/device-config.ts). Two questions, each
+ * TTY-only, skippable, and absent non-interactively:
+ *
+ *   1. "Which machine do you sit at?"   → `interactive.host` (central config:)
+ *   2. "Which browser should agents drive on THIS machine?"
+ *                                       → `browser.profile` (device-local default)
+ *
+ * Shared by the bare `agents setup` flow (a short step after the capability
+ * hub) and by `agents setup fleet` (interactive host after a successful sync).
+ * Unset always keeps today's behavior — skipping is a real choice, not a
+ * partial state.
+ */
+import { type DeviceRegistry } from '../lib/devices/registry.js';
+/** Registered macOS device names, sorted — the interactive-host candidates. */
+export declare function macDeviceNames(reg: DeviceRegistry): string[];
+/**
+ * The interactive-host picker's highlighted default: this machine when it is a
+ * candidate (the common case — you run setup on the box you sit at), else the
+ * first candidate. null when there are no candidates.
+ */
+export declare function defaultInteractiveHostChoice(candidates: string[], self?: string): string | null;
+/**
+ * The browser picker's highlighted default — the same browser auto-detect
+ * would win, since `listInstalledBrowsers` returns platform priority order
+ * (macOS: chrome first). null when nothing is installed.
+ */
+export declare function defaultBrowserChoice<T extends {
+    browserType: string;
+}>(installed: T[]): T['browserType'] | null;
+/**
+ * Offer to set the interactive host when none is configured and the registry
+ * has more than one macOS device. Returns true when a host was set. Silent
+ * no-op non-TTY, when already set, or with fewer than two candidates (the
+ * answer is obvious or absent).
+ */
+export declare function maybePickInteractiveHost(): Promise<boolean>;
+/**
+ * Offer to pin this machine's default browser profile to a chosen browser.
+ * Only asked when there is nothing to preserve: no configured device default
+ * AND no existing `default` profile (an existing profile is the user's earlier
+ * choice — never re-pinned behind their back). Returns true when a profile was
+ * created and set as the device default. Silent no-op non-TTY.
+ */
+export declare function maybePickBrowserProfile(): Promise<boolean>;
+/**
+ * The bare-`agents setup` preferences step: interactive host, then browser.
+ * Runs AFTER the capability hub so it never delays the bootstrap. Never
+ * throws — a prompt cancel or a failed pick ends the step quietly and lets
+ * setup complete (the same semantics as the capability hub).
+ */
+export declare function runPreferencesStep(): Promise<void>;

package/dist/commands/setup-preferences.js

@@ -0,0 +1,142 @@
+/**
+ * Preferences onboarding — the guided path over the same device-config keys the
+ * `agents devices …` commands write (lib/device-config.ts). Two questions, each
+ * TTY-only, skippable, and absent non-interactively:
+ *
+ *   1. "Which machine do you sit at?"   → `interactive.host` (central config:)
+ *   2. "Which browser should agents drive on THIS machine?"
+ *                                       → `browser.profile` (device-local default)
+ *
+ * Shared by the bare `agents setup` flow (a short step after the capability
+ * hub) and by `agents setup fleet` (interactive host after a successful sync).
+ * Unset always keeps today's behavior — skipping is a real choice, not a
+ * partial state.
+ */
+import chalk from 'chalk';
+import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, getProfile, } from '../lib/browser/profiles.js';
+import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { getConfigValue, setConfigValue } from '../lib/device-config.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { machineId } from '../lib/machine-id.js';
+import { isInteractiveTerminal } from './utils.js';
+const SKIP = '__skip__';
+/** Registered macOS device names, sorted — the interactive-host candidates. */
+export function macDeviceNames(reg) {
+    return Object.values(reg)
+        .filter((d) => d.platform === 'macos')
+        .map((d) => d.name)
+        .sort();
+}
+/**
+ * The interactive-host picker's highlighted default: this machine when it is a
+ * candidate (the common case — you run setup on the box you sit at), else the
+ * first candidate. null when there are no candidates.
+ */
+export function defaultInteractiveHostChoice(candidates, self = machineId()) {
+    if (candidates.length === 0)
+        return null;
+    return candidates.includes(self) ? self : candidates[0];
+}
+/**
+ * The browser picker's highlighted default — the same browser auto-detect
+ * would win, since `listInstalledBrowsers` returns platform priority order
+ * (macOS: chrome first). null when nothing is installed.
+ */
+export function defaultBrowserChoice(installed) {
+    return installed.length > 0 ? installed[0].browserType : null;
+}
+/**
+ * Offer to set the interactive host when none is configured and the registry
+ * has more than one macOS device. Returns true when a host was set. Silent
+ * no-op non-TTY, when already set, or with fewer than two candidates (the
+ * answer is obvious or absent).
+ */
+export async function maybePickInteractiveHost() {
+    if (!isInteractiveTerminal())
+        return false;
+    if (getConfigValue('interactive.host').value !== undefined)
+        return false;
+    const macs = macDeviceNames(await loadDevices());
+    if (macs.length < 2)
+        return false;
+    const { select } = await import('@inquirer/prompts');
+    const self = machineId();
+    const picked = await select({
+        message: 'Which machine do you sit at? (agents open browser windows and artifacts there)',
+        default: defaultInteractiveHostChoice(macs, self) ?? SKIP,
+        choices: [
+            ...macs.map((n) => ({ name: n === self ? `${n}  ${chalk.dim('(this machine)')}` : n, value: n })),
+            { name: `Skip ${chalk.dim('— decide later: agents devices set-interactive <name>')}`, value: SKIP },
+        ],
+    });
+    if (picked === SKIP)
+        return false;
+    setConfigValue('interactive.host', picked);
+    console.log(chalk.green(`Interactive host: '${picked}'`) + chalk.dim(' — marked ★ interactive in `agents devices list`.'));
+    return true;
+}
+/**
+ * Offer to pin this machine's default browser profile to a chosen browser.
+ * Only asked when there is nothing to preserve: no configured device default
+ * AND no existing `default` profile (an existing profile is the user's earlier
+ * choice — never re-pinned behind their back). Returns true when a profile was
+ * created and set as the device default. Silent no-op non-TTY.
+ */
+export async function maybePickBrowserProfile() {
+    if (!isInteractiveTerminal())
+        return false;
+    if (getConfiguredDefaultProfileName())
+        return false;
+    if (await getProfile(DEFAULT_BROWSER_PROFILE_NAME))
+        return false;
+    const installed = listInstalledBrowsers();
+    if (installed.length === 0)
+        return false;
+    const { select } = await import('@inquirer/prompts');
+    const picked = await select({
+        message: 'Which browser should agents drive on THIS machine?',
+        default: defaultBrowserChoice(installed) ?? SKIP,
+        choices: [
+            ...installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
+            { name: `Skip ${chalk.dim('— auto-detect on first use (priority order)')}`, value: SKIP },
+        ],
+    });
+    if (picked === SKIP)
+        return false;
+    const chosen = installed.find((b) => b.browserType === picked) ?? installed[0];
+    const freePort = await findFreeProfilePort();
+    const profile = {
+        name: DEFAULT_BROWSER_PROFILE_NAME,
+        description: `${chosen.browserType} profile (chosen during setup)`,
+        browser: chosen.browserType,
+        binary: chosen.binary,
+        endpoints: [`cdp://127.0.0.1:${freePort}`],
+        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+    };
+    await createProfile(profile);
+    // The same key `agents browser profiles set-default` writes (device-local).
+    setConfigValue('browser.profile', profile.name);
+    console.log(chalk.green(`Browser: '${chosen.browserType}'`) +
+        chalk.dim(` — profile "${profile.name}" is this machine's default (agents browser profiles set-default to change).`));
+    return true;
+}
+/**
+ * The bare-`agents setup` preferences step: interactive host, then browser.
+ * Runs AFTER the capability hub so it never delays the bootstrap. Never
+ * throws — a prompt cancel or a failed pick ends the step quietly and lets
+ * setup complete (the same semantics as the capability hub).
+ */
+export async function runPreferencesStep() {
+    if (!isInteractiveTerminal())
+        return;
+    try {
+        const pickedHost = await maybePickInteractiveHost();
+        const pickedBrowser = await maybePickBrowserProfile();
+        if (pickedHost || pickedBrowser)
+            console.log();
+    }
+    catch {
+        // Cancel (ctrl-c) or a picker failure — the step is optional; end it.
+    }
+}

package/dist/commands/setup.js

@@ -24,6 +24,7 @@ import { registerSetupShareCommand, runShareWizard } from './setup-share.js';
 import { registerSetupMineCommand } from './setup-mine.js';
 import { registerSetupSecretsCommand } from './setup-secrets.js';
 import { registerSetupFleetCommand } from './setup-fleet.js';
+import { runPreferencesStep } from './setup-preferences.js';
 const HOME = os.homedir();
 /**
  * Import an existing unmanaged agent installation into agents-cli.
@@ -130,15 +131,6 @@ export async function runSetup(program, options = {}) {
     if (dev.ok && dev.synced > 0) {
         console.log(chalk.gray(`Discovered ${dev.synced} device${dev.synced === 1 ? '' : 's'} on your tailnet (agents devices list).`));
     }
-    // Offer guided cross-machine session-sync provisioning (interactive, opt-in,
-    // and never blocking — any failure/decline falls through to the rest of setup).
-    try {
-        const { promptAndProvisionSessionSync } = await import('./sync-provision.js');
-        await promptAndProvisionSessionSync({ explicit: false });
-    }
-    catch (err) {
-        console.log(chalk.yellow(`Session-sync setup skipped: ${err.message}`));
-    }
     // Offer to import existing unmanaged installations
     if (unmanaged.length > 0 && isInteractiveTerminal()) {
         console.log(chalk.bold('\nFound existing installations:\n'));
@@ -201,6 +193,10 @@ export async function runSetup(program, options = {}) {
     // own guided flow. TTY-only and fully opt-in — a non-interactive `agents setup`
     // stops at the system-repo bootstrap above, unchanged.
     await runSetupHub();
+    // Preferences step: the two questions that keep agents off the wrong machine —
+    // which box you sit at (interactive host) and which browser agents drive here.
+    // TTY-only, skippable, and writes the same keys as `agents devices …`.
+    await runPreferencesStep();
     console.log(chalk.bold('\nSetup complete. Try:'));
     console.log(chalk.cyan('  agents view                 ') + chalk.gray(' # see what\'s installed'));
     console.log(chalk.cyan('  agents run <agent> "hello"  ') + chalk.gray(' # run an agent'));
@@ -307,6 +303,9 @@ export function registerSetupCommand(program) {
         1. Clones the system repo into ~/.agents/.system/
         2. Imports any unmanaged agent installations it finds
         3. On a TTY, offers to set up optional capabilities (browser/computer/share/secrets/fleet)
+        4. On a TTY, asks preferences: which machine you sit at (interactive host)
+           and which browser agents drive here — both skippable, both the same
+           keys 'agents devices set-interactive' / 'browser profiles set-default' write
 
       Capability setup can also be run any time on its own:
         agents setup browser    # detect a browser + create the default profile

package/dist/commands/ssh.js

@@ -47,9 +47,12 @@ import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js'
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort } from './lease.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
 import { runFleetLogin } from '../lib/fleet/remote-login.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from '../lib/device-config.js';
+import { 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. */
-function deviceSummary(d, isSelf = false, stats) {
+ * command is running on so it stands out from the rest of the tailnet.
+ * `isInteractive` marks the configured interactive host (`devices set-interactive`). */
+function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
     const addr = hostNameFor(d) ?? chalk.gray('no address');
     // Prefer a fresh live verdict (this run's probe, else the written-back
     // reachability) over the stale tailscale.online snapshot (RUSH-1965).
@@ -63,7 +66,8 @@ function deviceSummary(d, isSelf = false, stats) {
     const marker = isSelf ? chalk.cyan('▸ ') : '  ';
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
-    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}`;
+    const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
+    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}`;
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -90,9 +94,9 @@ function pctCell(v, width) {
  * 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) {
+function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
     if (!statsMap)
-        return names.map((n) => deviceSummary(reg[n], n === self));
+        return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost));
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
@@ -132,7 +136,8 @@ function renderDeviceTable(reg, names, self, statsMap, full = false) {
             : '';
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
-        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}`);
+        const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}`);
     }
     // Fleet capacity summary — total cores + how much RAM is free right now.
     const cap = fleetCapacity(statsMap.values());
@@ -685,10 +690,13 @@ function registerDevicesCommands(program) {
 Typical workflow:
   agents devices sync            # curate: pick which tailscale nodes to keep (TTY)
   agents devices sync --yes      # non-interactive: register all non-ignored nodes
-  agents devices list            # see what's registered
+  agents devices list            # see what's registered (★ = interactive host)
   agents devices ignore ipad165  # dismiss a node so it's never re-suggested
   agents devices disable zion    # exclude a device from Factory auto-launch
   agents devices prefer mac-mini # boost a device in Factory auto-launch ranking
+  agents devices set-interactive zion        # where agents show YOU artifacts
+  agents devices configure mac-mini --max-agents 4 --scheduler off
+  agents devices note mac-mini "runs the releases — don't reboot"
   agents devices set win-mini --auth password --bundle muqsit
   agents devices render --write  # write ~/.ssh/config.d/agents include
   agents fleet update            # roll out latest agents-cli to every online device
@@ -824,12 +832,214 @@ Typical workflow:
             process.exit(1);
         }
     });
+    const setInteractiveCmd = devicesCmd
+        .command('set-interactive [name]')
+        .description('Get or set the interactive host — the one device that shows YOU artifacts (browser opens, dashboards, rendered plans). Stored fleet-wide as config.interactiveHost in central agents.yaml.')
+        .option('--unset', 'clear the interactive host')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, opts) => {
+        try {
+            if (opts.unset) {
+                unsetConfigValue('interactive.host');
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ interactiveHost: null }, null, 2) + '\n');
+                else
+                    console.log(chalk.green('Cleared the interactive host.'));
+                return;
+            }
+            if (name) {
+                await mustGetDevice(name);
+                setConfigValue('interactive.host', name);
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ interactiveHost: name }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Interactive host: '${name}'`) + chalk.gray(' — agents show you artifacts there. Clear with --unset.'));
+                return;
+            }
+            const current = getConfigValue('interactive.host').value;
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ interactiveHost: current ?? null }, null, 2) + '\n');
+            }
+            else if (current) {
+                console.log(`${chalk.bold('Interactive host:')} ${chalk.cyan(current)}`);
+            }
+            else {
+                console.log(chalk.gray("No interactive host set. Set one with 'agents devices set-interactive <name>'."));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(setInteractiveCmd, {
+        examples: `
+      agents devices set-interactive zion      # zion is where artifacts open for you
+      agents devices set-interactive           # print the current interactive host
+      agents devices set-interactive --unset   # back to no interactive host
+      agents devices set-interactive --json    # machine-readable (for skills)
+    `,
+        notes: `
+      The interactive host answers "which online macOS device do I show this on?"
+      so skills stop guessing. It is marked ★ interactive in 'agents devices list'.
+      The value syncs fleet-wide (central agents.yaml, config.interactiveHost);
+      per-device settings live under 'agents devices configure' instead.
+    `,
+    });
+    const configureCmd = devicesCmd
+        .command('configure <name>')
+        .description('Get or set per-device config: --max-agents, --scheduler. Written to ~/.agents/devices/<name>/agents.yaml (works for any device — the devices/ tree syncs). Unset = default behavior.')
+        .option('--max-agents <n>', 'cap concurrent agents (Factory auto-launch counts device-wide; teams placement counts the team’s roster on the device)')
+        .option('--scheduler <on|off>', 'allow the routines scheduler (daemon) to fire on this device (takes effect on daemon reload/restart)')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, opts) => {
+        try {
+            await mustGetDevice(name);
+            const parseOnOff = (flag, raw) => {
+                if (raw === 'on')
+                    return true;
+                if (raw === 'off')
+                    return false;
+                throw new Error(`--${flag} expects 'on' or 'off', got '${raw}'.`);
+            };
+            const writes = [];
+            if (opts.maxAgents !== undefined) {
+                const n = Number(opts.maxAgents);
+                if (!Number.isInteger(n))
+                    throw new Error(`--max-agents expects an integer, got '${opts.maxAgents}'.`);
+                writes.push(['agents.max-concurrent', n]);
+            }
+            if (opts.scheduler !== undefined)
+                writes.push(['scheduler.enabled', parseOnOff('scheduler', opts.scheduler)]);
+            if (writes.length > 0) {
+                for (const [key, value] of writes)
+                    setConfigValue(key, value, { device: name });
+                if (!opts.json) {
+                    for (const [key, value] of writes) {
+                        console.log(chalk.green(`Set ${key} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
+                    }
+                }
+            }
+            if (opts.json || writes.length === 0) {
+                const entries = listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
+                if (opts.json) {
+                    const config = {};
+                    for (const e of entries)
+                        if (e.value !== undefined)
+                            config[e.spec.name] = e.value;
+                    process.stdout.write(JSON.stringify({ device: name, config }, null, 2) + '\n');
+                }
+                else {
+                    console.log(chalk.bold(`Config for '${name}'`));
+                    for (const e of entries) {
+                        const value = e.value === undefined ? chalk.gray('— (default)') : chalk.cyan(JSON.stringify(e.value));
+                        console.log(`  ${e.spec.name.padEnd(24)} ${value}${chalk.gray(`  ${e.spec.description}`)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(configureCmd, {
+        examples: `
+      agents devices configure mac-mini --max-agents 4      # cap concurrent agents
+      agents devices configure mac-mini --scheduler off     # no routines firing there
+      agents devices configure mac-mini                     # print its current config
+      agents devices configure mac-mini --json              # machine-readable
+    `,
+        notes: `
+      Run it on any machine for any device: the value lands in
+      ~/.agents/devices/<name>/agents.yaml locally and reaches the device on the
+      next 'agents repo push/pull'. Unset keys keep today's behavior.
+      --scheduler takes effect when the daemon reloads or restarts on that
+      device ('agents routines start' / the reload a 'routines add' sends).
+      For the default browser profile use 'agents browser profiles set-default
+      <name>'; for free-form text use 'agents devices note'.
+    `,
+    });
+    const noteCmd = devicesCmd
+        .command('note <name> [text...]')
+        .description('Append a free-form note to a device (repeat to append more). No text prints the notes; --clear empties them.')
+        .option('--clear', 'remove all notes from the device')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, text, opts) => {
+        try {
+            await mustGetDevice(name);
+            if (opts.clear) {
+                unsetConfigValue('notes', { device: name });
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ device: name, notes: [] }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Cleared notes on '${name}'.`));
+                return;
+            }
+            if (text.length > 0) {
+                const existing = getConfigValue('notes', { device: name }).value ?? [];
+                const notes = [...existing, text.join(' ')];
+                setConfigValue('notes', notes, { device: name });
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Noted on '${name}':`) + ` ${text.join(' ')}`);
+                return;
+            }
+            const notes = getConfigValue('notes', { device: name }).value ?? [];
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+            }
+            else if (notes.length > 0) {
+                console.log(chalk.bold(`Notes for '${name}'`));
+                for (const n of notes)
+                    console.log(`  ${chalk.gray('•')} ${n}`);
+            }
+            else {
+                console.log(chalk.gray(`No notes on '${name}'. Add one with 'agents devices note ${name} "..."'.`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(noteCmd, {
+        examples: `
+      agents devices note mac-mini "runs the releases — don't reboot"
+      agents devices note mac-mini "4 displays attached"   # appends a second note
+      agents devices note mac-mini                         # print its notes
+      agents devices note mac-mini --clear                 # drop them all
+    `,
+        notes: `
+      Notes are operator memory for a box (why it exists, what to never do to
+      it). They sync like every other device doc; 'agents devices list --json'
+      carries them under config.notes.
+    `,
+    });
+    /** Device-scope config block for `list --json`, keyed by yamlKey (set keys only). */
+    const deviceConfigJson = (name) => {
+        const config = {};
+        for (const entry of listConfig({ device: name })) {
+            if (entry.spec.scope !== 'device' || entry.value === undefined)
+                continue;
+            config[entry.spec.yamlKey] = entry.value;
+        }
+        return Object.keys(config).length > 0 ? config : undefined;
+    };
     const runList = async (opts = {}) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
+        const interactiveHost = getConfigValue('interactive.host').value;
         if (opts.json) {
-            // Registry-only, always fast — the Factory extension polls this path.
-            process.stdout.write(JSON.stringify(names.map((n) => reg[n]), null, 2) + '\n');
+            // Registry + local device docs, always fast — the Factory extension polls
+            // this path. Each row carries its device-scope `config` (maxAgents,
+            // schedulerEnabled, notes, defaultBrowserProfile — set keys
+            // only) and an `interactive` flag for the configured interactive host.
+            process.stdout.write(JSON.stringify(names.map((n) => {
+                const config = deviceConfigJson(n);
+                return { ...reg[n], interactive: n === interactiveHost, ...(config ? { config } : {}) };
+            }), null, 2) + '\n');
             return;
         }
         if (names.length === 0) {
@@ -867,7 +1077,7 @@ Typical workflow:
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         console.log(chalk.bold(`Devices (${names.length})`));
-        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full))
+        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost))
             console.log(line);
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));