@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/browser/ipc.js

@@ -3,8 +3,53 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { IS_WINDOWS, ipcEndpoint } from '../platform/index.js';
 import { getHelpersDir } from '../state.js';
-import { startDaemon, stopDaemon } from '../daemon.js';
+import { resolveBrowserTaskIdleMs } from '../device-config.js';
+import { startDaemon, stopDaemon } from '../daemon/daemon.js';
 import { getCliVersion } from '../version.js';
+import { compareVersions } from '../agent-spec/primitives.js';
+import { getDaemonLogPath } from '../daemon/daemon.js';
+import { resolveCallerIdentity } from './caller-identity.js';
+import { actionable } from './service.js';
+/**
+ * Verbs that imply a page and may CREATE a task when none resolves.
+ * Observation-only verbs (console/logs/…) resolve but never create — an
+ * empty `agents browser logs` must not open a browser just to return [].
+ */
+const PAGE_CREATE_VERBS = new Set([
+    'navigate',
+    'tab-add',
+    'evaluate',
+    'screenshot',
+    'pdf',
+    'refs',
+    'click',
+    'type',
+    'press',
+    'hover',
+    'scroll',
+    'set-viewport',
+    'set-device',
+    'wait',
+    'set-download-path',
+    'wait-download',
+    'upload',
+    'record-start',
+]);
+/** Task-scoped verbs that resolve identity but never create. */
+const PAGE_RESOLVE_VERBS = new Set([
+    ...PAGE_CREATE_VERBS,
+    'tab-focus',
+    'tab-close',
+    'tab-list',
+    'console',
+    'errors',
+    'requests',
+    'response-body',
+    'getAppLogs',
+    'record-stop',
+]);
+/** Close verbs never create a task. */
+const CLOSE_VERBS = new Set(['done', 'stop']);
 const SOCKET_NAME = 'browser.sock';
 /**
  * Backstop for {@link BrowserIPCServer.stop} — how long to wait for the socket
@@ -102,7 +147,8 @@ export class BrowserIPCConnection {
         });
     }
     request(request) {
-        const result = this.tail.then(() => this.requestOnce(request));
+        const stamped = stampCallerIdentity(request);
+        const result = this.tail.then(() => this.requestOnce(stamped));
         this.tail = result.then(() => undefined, () => undefined);
         return result;
     }
@@ -318,6 +364,44 @@ export class BrowserIPCServer {
             this.connections.clear();
         });
     }
+    /**
+     * Resolve `request.task` from caller identity when omitted. Page verbs may
+     * create; done/stop never create. Returns an error response to short-circuit
+     * the action, or undefined when the request is ready (task filled in).
+     */
+    async bindTask(request) {
+        const createIfMissing = PAGE_CREATE_VERBS.has(request.action);
+        const isClose = CLOSE_VERBS.has(request.action);
+        // stop with --profile only (no task) is handled by the stop case itself.
+        if (request.action === 'stop' && request.profile && !request.task)
+            return undefined;
+        try {
+            const resolved = await this.service.resolveOrCreateTask({
+                task: request.task,
+                profile: request.profile,
+                actor: request.actor,
+                launchId: request.launchId,
+                sessionId: request.sessionId,
+                createIfMissing,
+                title: request.title,
+                url: request.url,
+            });
+            if (!resolved) {
+                if (isClose) {
+                    return { ok: true, message: 'nothing to close' };
+                }
+                return {
+                    ok: false,
+                    error: actionable('No browser task for this session.', 'Next: agents browser navigate <url>  |  agents browser start'),
+                };
+            }
+            request.task = resolved.task.name;
+            return undefined;
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
     async handleRequest(request) {
         if (request.action === 'upload-stage') {
             const source = request.source;
@@ -327,13 +411,19 @@ export class BrowserIPCServer {
             const result = this.service.stageUpload(source);
             return { ok: true, path: result.path };
         }
+        // Task-scoped actions: resolve identity / create / refuse once here.
+        if (PAGE_RESOLVE_VERBS.has(request.action) || CLOSE_VERBS.has(request.action)) {
+            const early = await this.bindTask(request);
+            if (early)
+                return early;
+        }
         switch (request.action) {
             case 'version': {
                 return { ok: true, version: getCliVersion() };
             }
             case 'start': {
                 if (!request.profile) {
-                    return { ok: false, error: 'Profile required' };
+                    return { ok: false, error: actionable('Profile required.', 'Next: agents browser profiles list') };
                 }
                 const result = await this.service.start(request.profile, {
                     taskName: request.taskName,
@@ -344,6 +434,7 @@ export class BrowserIPCServer {
                     actor: request.actor,
                     launchId: request.launchId,
                     sessionId: request.sessionId,
+                    title: request.title,
                 });
                 return {
                     ok: true,
@@ -358,29 +449,48 @@ export class BrowserIPCServer {
             // only reach `reapAbandoned` through IPC. The daemon's own periodic tick
             // calls the service method directly.
             case 'gc': {
-                const reaped = await this.service.reapAbandoned({
-                    idleMs: request.idleMinutes !== undefined ? request.idleMinutes * 60_000 : undefined,
-                    dryRun: request.dryRun,
-                });
+                // 0 is the "disable idle reaping" signal (browser.task-idle-minutes),
+                // not a zero-ms window — translate it to reapAbandoned's `null` rather
+                // than let it hit the idleMs<=0 guard. Omitting the flag falls back to
+                // this box's own configured default (or 30 minutes when unset).
+                const idleMs = request.idleMinutes !== undefined
+                    ? (request.idleMinutes === 0 ? null : request.idleMinutes * 60_000)
+                    : resolveBrowserTaskIdleMs();
+                const reaped = await this.service.reapAbandoned({ idleMs, dryRun: request.dryRun });
                 return { ok: true, reaped };
             }
             case 'done': {
                 if (!request.task) {
-                    return { ok: false, error: 'Task required' };
+                    return { ok: true, message: 'nothing to close' };
                 }
                 const result = await this.service.done(request.task);
-                return { ok: result.ok, error: result.ok ? undefined : 'Task not found' };
+                return {
+                    ok: result.ok,
+                    error: result.ok
+                        ? undefined
+                        : actionable(`Task "${request.task}" not found.`, 'Next: agents browser status'),
+                    task: result.ok ? request.task : undefined,
+                };
             }
             case 'stop': {
                 if (request.task) {
                     const result = await this.service.stop(request.task);
-                    return { ok: result.ok, error: result.ok ? undefined : 'Task not found' };
+                    return {
+                        ok: result.ok,
+                        error: result.ok
+                            ? undefined
+                            : actionable(`Task "${request.task}" not found.`, 'Next: agents browser status'),
+                        task: result.ok ? request.task : undefined,
+                    };
                 }
                 if (request.profile) {
                     await this.service.stopProfile(request.profile);
                     return { ok: true };
                 }
-                return { ok: false, error: 'Task or profile required' };
+                return {
+                    ok: false,
+                    error: actionable('Task or profile required.', 'Next: agents browser status  |  agents browser stop --profile <name>'),
+                };
             }
             case 'status': {
                 const profiles = await this.service.status(request.profile);
@@ -391,11 +501,20 @@ export class BrowserIPCServer {
                 return { ok: true, history };
             }
             case 'navigate': {
-                if (!request.task || !request.url) {
-                    return { ok: false, error: 'Task and URL required' };
+                if (!request.url) {
+                    return {
+                        ok: false,
+                        error: actionable('URL required.', 'Next: agents browser navigate <url>'),
+                    };
+                }
+                if (!request.task) {
+                    return {
+                        ok: false,
+                        error: actionable('No browser task for this session.', 'Next: agents browser navigate <url>  |  agents browser start'),
+                    };
                 }
                 const result = await this.service.navigate(request.task, request.url, request.profile);
-                return { ok: true, tabId: result.tabId };
+                return { ok: true, tabId: result.tabId, task: request.task };
             }
             case 'tab-add': {
                 if (!request.task || !request.url) {
@@ -460,10 +579,20 @@ export class BrowserIPCServer {
             }
             case 'screenshot': {
                 if (!request.task) {
-                    return { ok: false, error: 'Task required' };
+                    return {
+                        ok: false,
+                        error: actionable('No browser task for this session.', 'Next: agents browser navigate <url>  |  agents browser start'),
+                    };
                 }
                 const shot = await this.service.screenshot(request.task, request.tabId, request.path, request.quality);
-                return { ok: true, path: shot.path, bytes: shot.bytes, width: shot.width, height: shot.height };
+                return {
+                    ok: true,
+                    path: shot.path,
+                    bytes: shot.bytes,
+                    width: shot.width,
+                    height: shot.height,
+                    task: request.task,
+                };
             }
             case 'pdf': {
                 if (!request.task) {
@@ -658,15 +787,32 @@ export class BrowserIPCServer {
 }
 let versionReconciledThisProcess = false;
 /**
- * Decide whether a running daemon is stale and must be restarted. A daemon
- * is stale when it reports a concrete version that differs from this CLI's.
+ * Decide whether a running daemon is stale and must be restarted.
+ *
+ * FORWARD ONLY: restart when the daemon is *older* than this CLI so a newer
+ * install loads current code. An older CLI rides a newer daemon instead of
+ * evicting it — two installs sharing one daemon dir (keyed off $HOME) must
+ * not flap the daemon indefinitely.
+ *
  * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
  * action reliably — don't churn it on that ambiguous signal.
+ *
+ * When numeric compare cannot order two distinct strings (e.g. two
+ * `0.0.0-dev.*` builds), treat the mismatch as a restart so a concrete
+ * code change still loads.
  */
 export function shouldRestartStaleDaemon(daemonVersion, clientVersion) {
     if (!daemonVersion || daemonVersion === 'unknown')
         return false;
-    return daemonVersion !== clientVersion;
+    if (daemonVersion === clientVersion)
+        return false;
+    const cmp = compareVersions(daemonVersion, clientVersion);
+    if (cmp < 0)
+        return true; // daemon older than client → upgrade forward
+    if (cmp > 0)
+        return false; // daemon newer → older CLI rides it
+    // cmp === 0 but strings differ (unorderable tails like 0.0.0-dev.abc)
+    return true;
 }
 /**
  * Reconcile the running daemon's version with ours. If the daemon is serving
@@ -700,7 +846,25 @@ async function reconcileDaemonVersion(socketPath) {
     await new Promise((r) => setTimeout(r, 300));
 }
 export async function sendIPCRequest(request, opts = {}) {
-    return sendRawIPCRequest(request, opts);
+    // Stamp caller identity ONCE here so the 28+ call sites don't each have to.
+    // The daemon cannot resolve the caller's actor/session itself.
+    const stamped = stampCallerIdentity(request);
+    return sendRawIPCRequest(stamped, opts);
+}
+/**
+ * Fill actor / launchId / sessionId from the calling process when the request
+ * left them blank. Explicit values on the request always win.
+ */
+export function stampCallerIdentity(request) {
+    if (request.actor && request.launchId && request.sessionId)
+        return request;
+    const id = resolveCallerIdentity();
+    return {
+        ...request,
+        actor: request.actor ?? id.actor,
+        launchId: request.launchId ?? id.launchId,
+        sessionId: request.sessionId ?? id.sessionId,
+    };
 }
 /**
  * Open one connection that can serve many browser operations. This uses the
@@ -776,7 +940,7 @@ async function prepareIPC(action, opts) {
             await waitForSocket(socketPath, 6000);
         }
         if (!(await isDaemonReachable())) {
-            throw new Error('Failed to start browser daemon');
+            throw new Error(actionable('Failed to start browser daemon.', `Log: ${getDaemonLogPath()}`, 'Next: agents doctor   (checks for a second agents-cli install)'));
         }
         await new Promise((r) => setTimeout(r, 300));
     }

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

@@ -1,13 +1,24 @@
 import type { BrowserProfile } from './types.js';
 export type { BrowserProfile } from './types.js';
 export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
+/**
+ * Where a profile is stored, and therefore who sees it:
+ *   - `local` — this machine's `devices/<machine>/agents.yaml` (`deviceBrowser`)
+ *   - `fleet` — the synced `~/.agents/agents.yaml` (`browser`), visible on every box
+ */
+export type ProfileScope = 'local' | 'fleet';
+/** A profile plus the store it actually lives in. */
+export interface ScopedBrowserProfile {
+    profile: BrowserProfile;
+    scope: ProfileScope;
+}
 /**
  * The device-local configured default profile name (set via
- * `agents browser profiles set-default`), or undefined when unset. When set, it
+ * `agents browser use`), or undefined when unset. When set, it
  * is the profile `agents browser start` resolves to for BOTH the no-`--profile`
  * path and an explicit `--profile default`. Stored as this machine's
- * `browser.profile` device-config key (central `fleet.devices.<name>.config`
- * block — see lib/device-config.ts).
+ * `browser.profile` device-config key (the per-device doc's `config:` block —
+ * see lib/device-config.ts).
  */
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;
@@ -26,6 +37,12 @@ export declare function getProfileDownloadsDir(name: string): string;
  */
 export declare function getProfileSessionsDir(name: string, task: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
+/**
+ * Every visible profile paired with the store it lives in. Same precedence as
+ * {@link listProfiles} — a machine-local entry wins a name collision, so a name
+ * present in both maps reports `local`, which is the copy that is actually used.
+ */
+export declare function listProfilesWithScope(): Promise<ScopedBrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**
  * True when `profile` can actually launch or attach on THIS machine.
@@ -45,7 +62,7 @@ export declare function isProfileLaunchableHere(profile: BrowserProfile): boolea
  * set-default <name>`) when it names an existing profile that can launch here;
  * (2) an existing `default` profile that can launch here; (3) auto-pick the
  * first installed Chromium-family browser per the platform priority list in
- * chrome.ts (macOS: chrome > brave > edge > chromium > comet; Linux: chrome >
+ * chrome.ts (macOS: chrome > brave > edge > chromium > comet > arc; Linux: chrome >
  * chromium > brave > edge; Windows: edge > chrome > brave > comet) and pin a
  * `default` profile to it. Throws an actionable error if none of those binaries
  * are installed.
@@ -77,9 +94,56 @@ export declare function effectiveLocalPort(profile: BrowserProfile): number | un
  * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
-export declare function createProfile(profile: BrowserProfile): Promise<void>;
+/**
+ * Create a profile. **It lands in this machine's own store by default** — pass
+ * `{ fleet: true }` (the CLI's `--fleet`) to put it in the synced `agents.yaml`
+ * where every box will see it.
+ *
+ * Local-by-default is the RUSH-2716 fix. A profile is a local browser install
+ * (`binary:` is an absolute path for one OS) bound to a locally chosen free port,
+ * so the fleet-synced copy is wrong on every other machine to begin with; and
+ * because agents mint throwaway profiles freely, every ad-hoc one was syncing to
+ * every machine as junk that nothing cleaned up (`agents browser profiles prune`
+ * is the other half of that fix). Opting in with `--fleet` is for a profile that
+ * really is fleet config — a remote `ssh://` endpoint, or a named profile whose
+ * shape you want on every box.
+ *
+ * Existing profiles are NOT migrated: this only decides where a NEW entry is
+ * written, so a fleet profile created before this change keeps syncing.
+ */
+export declare function createProfile(profile: BrowserProfile, opts?: {
+    fleet?: boolean;
+}): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
 export declare function deleteProfile(name: string): Promise<void>;
+/**
+ * Pad `text` to exactly `width` visible characters, truncating with an ellipsis
+ * when it does not fit. `padEnd` alone does NOT bound a long value — it returns
+ * the string unchanged when it already exceeds the width, which is what pushed
+ * every later column out of alignment on a name longer than 20 characters
+ * (RUSH-2710). Every column here goes through this, never a bare `padEnd`.
+ */
+export declare function padColumn(text: string, width: number): string;
+/**
+ * Render the `agents browser profiles list` table.
+ *
+ * Pure (no fs, no config reads) so the alignment and the default-marking rules
+ * are unit-testable without a configured machine.
+ *
+ * Two things used to be called "default" in this listing with no way to tell
+ * them apart (RUSH-2710): the profile literally NAMED `default` (the
+ * auto-detected one), and whichever profile this machine resolves a bare
+ * `agents browser start` to (`agents browser use <name>`). They
+ * are frequently different profiles. Now only the second is a marker — a `*` in
+ * a leading column, explained by a legend line — so the name column carries just
+ * the name and `default` in it always means the profile of that name.
+ *
+ * The SCOPE column is the RUSH-2716 companion: it says whether an entry lives on
+ * this machine only (`local`) or in the fleet-synced `agents.yaml` (`fleet`), so
+ * "why does this box have a profile I never made here?" is answerable at a
+ * glance.
+ */
+export declare function formatProfilesTable(rows: ScopedBrowserProfile[], configuredDefault?: string): string[];
 /**
  * Resolve a profile's endpoint presets into a normalized map regardless of
  * whether the YAML uses the legacy `string[]` shape or the new map shape.

package/dist/lib/browser/profiles.js

@@ -8,23 +8,28 @@ export const DEFAULT_BROWSER_PROFILE_NAME = 'default';
  * True for a profile whose contents only make sense on THIS machine, so it must
  * live in the per-machine doc rather than the fleet-synced agents.yaml.
  *
- * Only the auto-detected `default` qualifies: it is generated by probing local
+ * The auto-detected `default` always qualifies: it is generated by probing local
  * browser installs and a free local port, so its `binary:` is an absolute path
  * for one OS. Shared fleet-wide it caused a permanent rewrite loop — a macOS box
  * wrote `/Applications/...`, a Linux box rewrote `/usr/bin/chromium-browser`,
- * each on every `agents browser start`. Named profiles a user created are real
- * fleet config and keep syncing.
+ * each on every `agents browser start`.
+ *
+ * As of RUSH-2716 it is not the only one: EVERY newly created profile is
+ * machine-local unless the caller explicitly asks for the fleet-synced store
+ * (`createProfile(p, { fleet: true })` / `--fleet`). See {@link createProfile}.
+ * This predicate is what keeps an existing `default` that an older version wrote
+ * into central from being written back there by {@link updateProfile}.
  */
 function isMachineLocalProfile(name) {
     return name === DEFAULT_BROWSER_PROFILE_NAME;
 }
 /**
  * The device-local configured default profile name (set via
- * `agents browser profiles set-default`), or undefined when unset. When set, it
+ * `agents browser use`), or undefined when unset. When set, it
  * is the profile `agents browser start` resolves to for BOTH the no-`--profile`
  * path and an explicit `--profile default`. Stored as this machine's
- * `browser.profile` device-config key (central `fleet.devices.<name>.config`
- * block — see lib/device-config.ts).
+ * `browser.profile` device-config key (the per-device doc's `config:` block —
+ * see lib/device-config.ts).
  */
 export function getConfiguredDefaultProfileName() {
     return getConfigValue('browser.profile').value || undefined;
@@ -112,6 +117,19 @@ export async function listProfiles() {
     const configs = allProfileConfigs();
     return Object.entries(configs).map(([name, config]) => configToProfile(name, config));
 }
+/**
+ * Every visible profile paired with the store it lives in. Same precedence as
+ * {@link listProfiles} — a machine-local entry wins a name collision, so a name
+ * present in both maps reports `local`, which is the copy that is actually used.
+ */
+export async function listProfilesWithScope() {
+    const meta = readMeta();
+    const local = meta.deviceBrowser ?? {};
+    return Object.entries(allProfileConfigs()).map(([name, config]) => ({
+        profile: configToProfile(name, config),
+        scope: (local[name] ? 'local' : 'fleet'),
+    }));
+}
 export async function getProfile(name) {
     const config = allProfileConfigs()[name];
     if (!config)
@@ -147,7 +165,7 @@ export function isProfileLaunchableHere(profile) {
  * set-default <name>`) when it names an existing profile that can launch here;
  * (2) an existing `default` profile that can launch here; (3) auto-pick the
  * first installed Chromium-family browser per the platform priority list in
- * chrome.ts (macOS: chrome > brave > edge > chromium > comet; Linux: chrome >
+ * chrome.ts (macOS: chrome > brave > edge > chromium > comet > arc; Linux: chrome >
  * chromium > brave > edge; Windows: edge > chrome > brave > comet) and pin a
  * `default` profile to it. Throws an actionable error if none of those binaries
  * are installed.
@@ -169,18 +187,18 @@ export async function ensureDefaultBrowserProfile() {
         console.warn(chosen
             ? `warning: configured default browser profile "${configured}" can't launch on this ` +
                 `machine (its browser/binary isn't installed here); falling back to auto-detect. ` +
-                `Fix with: agents browser profiles set-default <name>  (or --unset)`
+                `Fix with: agents browser use <name>  (or --unset)`
             : `warning: configured default browser profile "${configured}" no longer exists; ` +
-                `falling back to auto-detect. Fix with: agents browser profiles set-default <name>  (or --unset)`);
+                `falling back to auto-detect. Fix with: agents browser use <name>  (or --unset)`);
     }
     const existing = await getProfile(DEFAULT_BROWSER_PROFILE_NAME);
     if (existing && isProfileLaunchableHere(existing))
         return existing;
     const detected = findFirstInstalledBrowser();
     if (!detected) {
-        throw new Error('No supported browser found. Install one of: Chrome, Brave, Edge, Chromium, or Comet, ' +
+        throw new Error('No supported browser found. Install one of: Chrome, Brave, Edge, Chromium, Comet, or Arc, ' +
             'then re-run `agents browser start`. Or create a profile explicitly with ' +
-            '`agents browser profiles create <name> --browser <chrome|comet|chromium|brave|edge|custom>`. ' +
+            '`agents browser profiles create <name> --browser <chrome|comet|chromium|brave|edge|arc|custom>`. ' +
             'Note: Safari and Firefox are not supported — agents browser drives over the ' +
             'Chrome DevTools Protocol, which they don\'t implement.');
     }
@@ -292,7 +310,24 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
-export async function createProfile(profile) {
+/**
+ * Create a profile. **It lands in this machine's own store by default** — pass
+ * `{ fleet: true }` (the CLI's `--fleet`) to put it in the synced `agents.yaml`
+ * where every box will see it.
+ *
+ * Local-by-default is the RUSH-2716 fix. A profile is a local browser install
+ * (`binary:` is an absolute path for one OS) bound to a locally chosen free port,
+ * so the fleet-synced copy is wrong on every other machine to begin with; and
+ * because agents mint throwaway profiles freely, every ad-hoc one was syncing to
+ * every machine as junk that nothing cleaned up (`agents browser profiles prune`
+ * is the other half of that fix). Opting in with `--fleet` is for a profile that
+ * really is fleet config — a remote `ssh://` endpoint, or a named profile whose
+ * shape you want on every box.
+ *
+ * Existing profiles are NOT migrated: this only decides where a NEW entry is
+ * written, so a fleet profile created before this change keeps syncing.
+ */
+export async function createProfile(profile, opts = {}) {
     const meta = readMeta();
     const existingConfigs = allProfileConfigs();
     if (existingConfigs[profile.name]) {
@@ -327,7 +362,11 @@ export async function createProfile(profile) {
         findBrowserPath(profile.browser, profile.binary);
     }
     const config = profileToConfig(profile);
-    if (isMachineLocalProfile(profile.name)) {
+    // Machine-local unless the caller explicitly asked for the fleet store. The
+    // auto `default` is always local regardless of what a caller passes — its
+    // binary path and port are this box's, and fleet-syncing it is the rewrite
+    // loop RUSH-2161 fixed.
+    if (!opts.fleet || isMachineLocalProfile(profile.name)) {
         updateMeta((m) => ({ ...m, deviceBrowser: { ...m.deviceBrowser, [profile.name]: config } }));
         return;
     }
@@ -365,6 +404,89 @@ export async function deleteProfile(name) {
         return { ...m, browser: Object.keys(next).length > 0 ? next : undefined };
     });
 }
+/** Widest NAME column we will grow to before truncating instead. */
+const MAX_NAME_COLUMN = 28;
+/**
+ * Pad `text` to exactly `width` visible characters, truncating with an ellipsis
+ * when it does not fit. `padEnd` alone does NOT bound a long value — it returns
+ * the string unchanged when it already exceeds the width, which is what pushed
+ * every later column out of alignment on a name longer than 20 characters
+ * (RUSH-2710). Every column here goes through this, never a bare `padEnd`.
+ */
+export function padColumn(text, width) {
+    if (width <= 0)
+        return '';
+    if (text.length <= width)
+        return text.padEnd(width);
+    if (width === 1)
+        return '…';
+    return text.slice(0, width - 1) + '…';
+}
+/**
+ * Render the `agents browser profiles list` table.
+ *
+ * Pure (no fs, no config reads) so the alignment and the default-marking rules
+ * are unit-testable without a configured machine.
+ *
+ * Two things used to be called "default" in this listing with no way to tell
+ * them apart (RUSH-2710): the profile literally NAMED `default` (the
+ * auto-detected one), and whichever profile this machine resolves a bare
+ * `agents browser start` to (`agents browser use <name>`). They
+ * are frequently different profiles. Now only the second is a marker — a `*` in
+ * a leading column, explained by a legend line — so the name column carries just
+ * the name and `default` in it always means the profile of that name.
+ *
+ * The SCOPE column is the RUSH-2716 companion: it says whether an entry lives on
+ * this machine only (`local`) or in the fleet-synced `agents.yaml` (`fleet`), so
+ * "why does this box have a profile I never made here?" is answerable at a
+ * glance.
+ */
+export function formatProfilesTable(rows, configuredDefault) {
+    const cells = rows.map(({ profile, scope }) => {
+        const presets = getEndpointPresets(profile);
+        const endpoints = Object.entries(presets)
+            .map(([name, ep]) => (name.startsWith('endpoint-') ? ep.target : `${name}=${ep.target}`))
+            .join(', ');
+        return {
+            marker: profile.name === configuredDefault ? '*' : ' ',
+            name: profile.name,
+            browser: profile.browser || '-',
+            scope,
+            description: profile.description ?? '',
+            endpoints,
+        };
+    });
+    const nameWidth = Math.min(MAX_NAME_COLUMN, Math.max('NAME'.length, ...cells.map((c) => c.name.length)));
+    const browserWidth = Math.max('BROWSER'.length, ...cells.map((c) => c.browser.length));
+    // 'local' / 'fleet' are both 5 chars, so the header is the widest value.
+    const scopeWidth = 'SCOPE'.length;
+    const hasDescriptions = cells.some((c) => c.description);
+    const descWidth = hasDescriptions
+        ? Math.min(36, Math.max('DESCRIPTION'.length, ...cells.map((c) => c.description.length)))
+        : 0;
+    const row = (marker, name, browser, scope, desc, endpoints) => `${marker} ` +
+        padColumn(name, nameWidth) + '  ' +
+        padColumn(browser, browserWidth) + '  ' +
+        padColumn(scope, scopeWidth) + '  ' +
+        (hasDescriptions ? padColumn(desc, descWidth) + '  ' : '') +
+        endpoints;
+    const header = row(' ', 'NAME', 'BROWSER', 'SCOPE', 'DESCRIPTION', 'ENDPOINTS');
+    const lines = [header, '-'.repeat(header.length)];
+    for (const c of cells) {
+        lines.push(row(c.marker, c.name, c.browser, c.scope, c.description, c.endpoints));
+    }
+    if (configuredDefault) {
+        lines.push('');
+        lines.push(`* = this machine's default profile (${configuredDefault}) — what a bare \`agents browser start\` uses.`);
+    }
+    lines.push(hasFleetRow(rows)
+        ? 'scope: local = this machine only · fleet = synced to every machine (agents.yaml).'
+        : 'scope: local = this machine only. Create a synced one with: agents browser profiles create <name> --fleet');
+    return lines;
+}
+function hasFleetRow(rows) {
+    return rows.some((r) => r.scope === 'fleet');
+}
 /**
  * Resolve a profile's endpoint presets into a normalized map regardless of
  * whether the YAML uses the legacy `string[]` shape or the new map shape.

package/dist/lib/browser/remote-control.d.ts

@@ -1,7 +1,7 @@
 /**
  * Consent gate for driving THIS machine's browser from another fleet machine.
  *
- * `browser --host <device>` routes a browser command to `<device>` over SSH (the
+ * `browser --device <device>` routes a browser command to `<device>` over SSH (the
  * fleet passthrough) and runs `agents browser ...` there. Every such remote
  * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
  * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
@@ -14,7 +14,7 @@
  */
 /** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
 export declare const FLEET_REMOTE_ENV = "AGENTS_FLEET_REMOTE";
-/** True when this process was dispatched to this machine by a fleet `--host` run. */
+/** True when this process was dispatched to this machine by a fleet `--device` run. */
 export declare function isFleetRemoteInvocation(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether this machine allows other fleet machines to drive its browser. Reads