@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/dist/commands/projects.js

@@ -10,12 +10,14 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
+import * as path from 'path';
 import { execFileSync, spawnSync } from 'child_process';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { setHelpSections } from '../lib/help.js';
 import { getMainRepoRoot } from '../lib/git.js';
 import { parseOwnerRepoFromRemote } from '../lib/registry.js';
-import { toHomeRelative } from '../lib/project-root.js';
+import { truncate } from '../lib/format.js';
+import { expandLocalHome, getProjectRoot, toHomeRelative } from '../lib/project-root.js';
 import { machineId } from '../lib/machine-id.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
@@ -26,6 +28,7 @@ import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, pro
 import { rollupSessionsByProject, planPct, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
+import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
 /** Max peers named in the skipped note before the rest collapse to `+N`. */
@@ -63,6 +66,135 @@ function originSlug(cwd) {
         return undefined;
     }
 }
+/**
+ * Read the Factory registry off disk and plan its import. Every read failure is
+ * fatal and named — an unreadable or malformed registry must not read as "0
+ * projects to import".
+ */
+function runFactoryImport(existing, opts) {
+    const src = factoryProjectsPath();
+    let rawText;
+    try {
+        rawText = fs.readFileSync(src, 'utf8');
+    }
+    catch {
+        console.error(chalk.red(`No Factory registry at ${src}`));
+        process.exit(1);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch {
+        console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+        process.exit(1);
+    }
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : Array.isArray(parsed?.projects)
+            ? parsed.projects
+            : [];
+    return buildFactoryImportCandidates(rows, existing, opts);
+}
+/**
+ * List the workspace's Linear projects and plan their import, binding each to a
+ * local checkout under the configured projects root when the names match
+ * exactly. A missing / logged-out `linear` CLI is loud (this is an explicit user
+ * command), and nothing is written before the whole plan is built.
+ */
+function runLinearImport(existing, opts) {
+    let list;
+    try {
+        list = listLinearProjects();
+    }
+    catch (e) {
+        console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+        process.exit(1);
+    }
+    // No projects root configured (or unreadable) → no local matching; every def
+    // still imports, carrying its Linear link and nothing it can't prove.
+    const rootAbs = getProjectRoot() ? expandLocalHome(getProjectRoot()) : undefined;
+    let localDirs = [];
+    if (rootAbs) {
+        try {
+            localDirs = fs
+                .readdirSync(rootAbs, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+                .map((d) => d.name);
+        }
+        catch {
+            localDirs = [];
+        }
+    }
+    return buildLinearImportCandidates(list, existing, {
+        localDirs,
+        resolveRoot: (dir) => (rootAbs ? toHomeRelative(path.join(rootAbs, dir)) : undefined),
+        resolveOrigin: (dir) => (rootAbs ? originSlug(path.join(rootAbs, dir)) : undefined),
+    }, opts);
+}
+/** Longest path a `list` row shows before it truncates. */
+const LIST_PATH_MAX = 48;
+/**
+ * Column widths for `projects list`, sized to the rows actually being printed.
+ * Fixed padding was the bug: home-relative roots run past 50 characters, so a
+ * hardcoded 32 pushed the repo column off its gridline on every long path.
+ * Paths longer than {@link LIST_PATH_MAX} truncate rather than widen the table.
+ */
+export function computeProjectListWidths(rows) {
+    const widest = (pick, cap) => Math.min(cap, rows.reduce((w, r) => Math.max(w, pick(r).length), 0));
+    return {
+        name: widest((r) => r.name, 64),
+        path: widest((r) => r.path, LIST_PATH_MAX),
+        repo: widest((r) => r.repo, 64),
+    };
+}
+/**
+ * A milestone's target date as a person would say it — "due tomorrow",
+ * "overdue by 3 days", "due Aug 21" — never a raw `2026-08-21` or a duration in
+ * hours. Linear stores a calendar date with no timezone, so both sides are
+ * compared at LOCAL midnight; parsing `YYYY-MM-DD` with `new Date(str)` would
+ * read it as UTC and shift the answer by a day for anyone west of Greenwich.
+ */
+export function formatMilestoneDue(targetDate, nowMs) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(targetDate.trim());
+    if (!m)
+        return undefined;
+    const due = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    if (Number.isNaN(due.getTime()))
+        return undefined;
+    const now = new Date(nowMs);
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const days = Math.round((due.getTime() - today.getTime()) / 86_400_000);
+    if (days === 0)
+        return 'due today';
+    if (days === 1)
+        return 'due tomorrow';
+    if (days === -1)
+        return 'overdue by a day';
+    if (days < 0)
+        return `overdue by ${-days} days`;
+    if (days <= 14)
+        return `due in ${days} days`;
+    const sameYear = due.getFullYear() === today.getFullYear();
+    const label = due.toLocaleDateString('en-US', {
+        month: 'short',
+        day: 'numeric',
+        ...(sameYear ? {} : { year: 'numeric' }),
+    });
+    return `due ${label}`;
+}
+/** The `next` card line: what this project is due to hit, and how far along it is. */
+export function formatNextMilestone(ms, nowMs) {
+    const parts = [chalk.bold(ms.name)];
+    // A milestone with nothing filed under it yet has no progress to report —
+    // `0/0` is noise, not information.
+    if (ms.total > 0)
+        parts.push(`${ms.done}/${ms.total}`);
+    const due = ms.targetDate ? formatMilestoneDue(ms.targetDate, nowMs) : undefined;
+    if (due)
+        parts.push(due.startsWith('overdue') ? chalk.yellow(due) : chalk.dim(due));
+    return parts.join(chalk.dim('  ·  '));
+}
 function statusBar(r) {
     const parts = [];
     const push = (n, label, color) => {
@@ -80,7 +212,7 @@ function statusBar(r) {
         parts.push(chalk.gray(`+${r.agents - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
-function renderCard(def, r, remote, fleet, linear) {
+function renderCard(def, r, remote, fleet, linear, nowMs = Date.now()) {
     const agents = r?.agents ?? 0;
     const pct = r ? planPct(r.plan) : undefined;
     const planStr = pct === undefined ? '' : `  ·  ${chalk.cyan(`${pct}% plan`)}`;
@@ -104,6 +236,9 @@ function renderCard(def, r, remote, fleet, linear) {
     if (linear) {
         console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done · ${linear.inProgress} in progress`);
     }
+    if (linear?.nextMilestone) {
+        console.log(`  ${chalk.dim('next')}     ${formatNextMilestone(linear.nextMilestone, nowMs)}`);
+    }
     if (r && r.tickets.length) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
     }
@@ -138,6 +273,7 @@ export function registerProjectsCommands(program) {
         .description('Named multi-repo projects with a progress rollup.');
     setHelpSections(projects, {
         examples: `
+      agents projects import --from-linear  # the projects you actually track
       agents projects add rush --repo phnx-labs/rush --path apps/web
       agents projects list
       agents projects status              # progress card for every project
@@ -149,6 +285,11 @@ export function registerProjectsCommands(program) {
         notes: `
       Definitions are hand-editable YAML in ~/.agents/projects/ and sync across
       machines with 'agents push/pull'. Enable with: agents beta enable projects.
+
+      'import --from-factory' reads Factory's auto-detected registry, which
+      guesses from checkouts on disk — it imports only 'high' confidence rows by
+      default. Widen with --min-confidence medium or --all, and drop a bad guess
+      with 'agents projects rm <name>'.
     `,
     });
     projects.hook('preAction', (_thisCommand, actionCommand) => {
@@ -180,10 +321,16 @@ export function registerProjectsCommands(program) {
             return;
         }
         const roll = rollupSessionsByProject(defs, await getActiveSessions());
-        for (const d of defs) {
+        const rows = defs.map((d) => ({
+            name: d.name,
+            path: truncate(d.root ?? d.defaultPath ?? '', LIST_PATH_MAX),
+            repo: d.repo ?? d.repos?.[0]?.slug ?? '',
+        }));
+        const w = computeProjectListWidths(rows);
+        for (const [i, d] of defs.entries()) {
             const agents = roll.get(d.name)?.agents ?? 0;
-            const repo = d.repo ?? d.repos?.[0]?.slug ?? '';
-            console.log(`  ${chalk.bold(d.name.padEnd(16))} ${chalk.dim((d.root ?? d.defaultPath ?? '').padEnd(32))} ${chalk.cyan(repo.padEnd(24))} ${agents} agents`);
+            const row = rows[i];
+            console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))} ${agents} agents`);
         }
     });
     // ---- add ----
@@ -384,7 +531,7 @@ export function registerProjectsCommands(program) {
             return;
         }
         for (const d of defs) {
-            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name));
+            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs);
         }
         if (fleetSkipped.length > 0)
             process.stdout.write(formatFleetSkippedNote(fleetSkipped));
@@ -402,54 +549,33 @@ export function registerProjectsCommands(program) {
     // ---- import ----
     projects
         .command('import')
-        .description('Absorb the Factory project registry (~/.agents/factory/projects.json) into YAML definitions.')
-        .requiredOption('--from-factory', 'Import from the Factory projects.json registry')
+        .description('Import project definitions from Linear (preferred) or the Factory auto-detection registry.')
+        .option('--from-linear', 'Import the workspace\'s Linear projects (via the `linear` CLI)')
+        .option('--from-factory', 'Import the Factory registry (~/.agents/factory/projects.json)')
+        .option('--min-confidence <level>', '--from-factory only: lowest detection confidence to import — low|medium|high (default: high)')
+        .option('--all', '--from-factory only: import every row regardless of confidence')
         .option('--force', 'Overwrite existing definitions')
-        .action((opts) => {
-        const src = factoryProjectsPath();
-        let rawText;
-        try {
-            rawText = fs.readFileSync(src, 'utf8');
-        }
-        catch {
-            console.error(chalk.red(`No Factory registry at ${src}`));
-            process.exit(1);
-        }
-        let rows;
+        .action((raw) => {
+        let opts;
         try {
-            rows = JSON.parse(rawText);
+            opts = validateImportOpts(raw);
         }
-        catch {
-            console.error(chalk.red(`Factory registry at ${src} is not valid JSON`));
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
             process.exit(1);
         }
-        const list = Array.isArray(rows) ? rows : Array.isArray(rows.projects) ? rows.projects : [];
-        let created = 0;
-        let skipped = 0;
-        for (const raw of list) {
-            if (!raw || typeof raw !== 'object')
-                continue;
-            const o = raw;
-            const name = typeof o.name === 'string' ? o.name : undefined;
-            if (!name || !isSafeProjectName(name)) {
-                skipped++;
-                continue;
-            }
-            if (loadProjectDef(name) && !opts.force) {
-                skipped++;
-                continue;
-            }
-            const def = { name };
-            if (typeof o.path === 'string')
-                def.root = toHomeRelative(o.path);
-            if (typeof o.repoSlug === 'string')
-                def.repo = o.repoSlug;
-            if (typeof o.linearProjectId === 'string')
-                def.linear = { projectId: o.linearProjectId };
+        const existing = new Map(listProjectDefs().map((d) => [d.name, d]));
+        const result = opts.source === 'linear' ? runLinearImport(existing, opts) : runFactoryImport(existing, opts);
+        for (const def of result.defs)
             writeProjectDef(def);
-            created++;
+        const n = result.defs.length;
+        const s = result.skipped.length;
+        console.log(chalk.green(`Imported ${n} project${n === 1 ? '' : 's'}${s ? chalk.gray(` (${s} skipped)`) : ''}`));
+        for (const skip of result.skipped)
+            console.log(chalk.gray(`  skip ${skip.name}: ${skip.reason}`));
+        if (opts.source === 'factory' && s > 0 && opts.minConfidence === 'high') {
+            console.log(chalk.gray('  (widen with --min-confidence medium or --all)'));
         }
-        console.log(chalk.green(`Imported ${created} project${created === 1 ? '' : 's'}${skipped ? chalk.gray(` (${skipped} skipped)`) : ''}`));
     });
     // ---- link ----
     projects

package/dist/commands/routines.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
+import { assertSchedulerEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
@@ -295,9 +296,21 @@ function parseRoutineTrigger(options) {
 /**
  * Start or reload the background scheduler so newly-added jobs fire on time.
  * `quiet` suppresses human status lines for JSON callers.
+ *
+ * When this device has `scheduler.enabled=false` the auto-start is skipped with
+ * the stated reason (the add itself already succeeded — the job is config and
+ * stays valid fleet-wide); the refusal message names the setting and the fix.
  */
 function ensureSchedulerRunning(opts = {}) {
     const log = opts.stderr ? console.error : console.log;
+    try {
+        assertSchedulerEnabled();
+    }
+    catch (err) {
+        // Loud stated skip, on stderr so --json stdout stays clean.
+        console.error(chalk.yellow(err.message));
+        return;
+    }
     if (isDaemonRunning()) {
         signalDaemonReload();
         if (!opts.quiet)
@@ -1480,9 +1493,22 @@ export function registerRoutinesCommands(program) {
         .command('start')
         .description('Start the background scheduler. Usually unnecessary — it auto-starts when you add your first routine.')
         .action(() => {
+        try {
+            // A manual start on a scheduler-disabled device refuses with the same
+            // message the auto-start surfaces give.
+            assertSchedulerEnabled();
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
         const result = startDaemon();
         if (result.method === 'already-running') {
-            console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid})`));
+            // Signal a reload even here: if the daemon booted while this device had
+            // scheduler.enabled=false, the reload re-evaluates the gate and boots
+            // the scheduler — a manual start heals a scheduler-less daemon.
+            signalDaemonReload();
+            console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid}) — reloaded`));
         }
         else if (result.pid) {
             console.log(chalk.green(`Scheduler started (PID: ${result.pid})`));

package/dist/commands/rules.js

@@ -512,6 +512,12 @@ Examples:
         .addHelpText('after', `
 Targets are <agent>@<version>. Use 'default' for the alias of the global default version.
 
+This re-syncs the version home immediately, AND the choice sticks: every later
+'agents run' for this agent+version re-applies the active preset before launch
+(skip-fast when nothing changed), so a preset set here never goes stale even if
+something changes it again without running 'switch' — you don't need to re-run
+'switch' or 'sync' by hand before the next launch.
+
 Examples:
   # Persist the cautious preset for claude 2.1.111
   agents rules switch claude@2.1.111 --preset cautious

package/dist/commands/sessions.d.ts

@@ -315,6 +315,13 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/** 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. */
+export declare function renderSessionPreview(query: string, scope: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+}): Promise<void>;
 /**
  * The one-line live status banner shown above a session preview: the glyph, the
  * status word, and — when the session needs a human or has LOST one — a plain
@@ -351,6 +358,16 @@ export declare function teamBadge(session: SessionMeta): {
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
 export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, favorite?: boolean): string;
+/**
+ * Live-session index for enriching the default listing, or undefined when
+ * enrichment is off (`--no-live`) or irrelevant (`--json`, which serializes
+ * SessionMeta). Full detection (incl. the headless `ps` scan) is deliberate:
+ * bare-CLI and tmux agents are the common case here, and skipping them would
+ * leave the glyph almost never showing. The listing is a one-shot user action,
+ * 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.
+ */
+export declare function maybeLiveIndex(options: SessionsOptions): Promise<Map<string, ActiveSession> | undefined>;
 /**
  * Group key for the overview: resolve the cwd through the same canonical
  * resolver the `agents activity` timeline groups by — a defined project's name

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