@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/browser/profiles.js

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import * as fs from 'fs';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, updateMeta, } from '../state.js';
 import { getConfigValue } from '../device-config.js';
 import { findBrowserPath, findFirstInstalledBrowser, isPortInUse } from './chrome.js';
@@ -419,6 +420,32 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
+/**
+ * Refuse a profile whose LOCAL port another profile already owns.
+ *
+ * Every CDP/SSH profile ends up listening on (or tunneling to) the same LOCAL
+ * port number as the one configured in the endpoint URL — SSH profiles reuse
+ * `?port=N` locally, so we no longer scope by host. Two profiles that would
+ * need the same local port can't both run at the same time.
+ *
+ * `opts.ignore` is the profile's own name on an edit. Without it every edit
+ * collides with itself, since the stored copy still owns the port being kept.
+ */
+export function assertLocalPortFree(profile, opts = {}) {
+    const wanted = effectiveLocalPort(profile);
+    if (wanted === undefined)
+        return;
+    for (const [existingName, existingConfig] of Object.entries(allProfileConfigs())) {
+        if (existingName === opts.ignore)
+            continue;
+        const existingProfile = configToProfile(existingName, existingConfig);
+        if (effectiveLocalPort(existingProfile) === wanted) {
+            throw new Error(`Local port ${wanted} is already used by profile "${existingName}". ` +
+                `Each profile must own a unique local port (SSH tunnels now bind ` +
+                `to their configured port locally too). Pick a different port.`);
+        }
+    }
+}
 /**
  * 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`
@@ -442,23 +469,7 @@ export async function createProfile(profile, opts = {}) {
     if (existingConfigs[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
-    // Collision check. Every CDP/SSH profile ends up listening on (or
-    // tunneling to) the same LOCAL port number as the one configured in the
-    // endpoint URL — SSH profiles now reuse `?port=N` locally so we no
-    // longer need to scope by host. Two profiles that would need the same
-    // local port can't both run at the same time.
-    const newLocal = effectiveLocalPort(profile);
-    if (newLocal !== undefined) {
-        for (const [existingName, existingConfig] of Object.entries(existingConfigs)) {
-            const existingProfile = configToProfile(existingName, existingConfig);
-            const existingLocal = effectiveLocalPort(existingProfile);
-            if (existingLocal === newLocal) {
-                throw new Error(`Local port ${newLocal} is already used by profile "${existingName}". ` +
-                    `Each profile must own a unique local port (SSH tunnels now bind ` +
-                    `to their configured port locally too). Pick a different port.`);
-            }
-        }
-    }
+    assertLocalPortFree(profile);
     // Resolve the browser binary at create time. Fails fast with an actionable
     // error ("Comet not installed at /Applications/Comet.app") rather than
     // deferring the failure to the first task. `findBrowserPath` short-circuits
@@ -496,6 +507,278 @@ export async function updateProfile(profile) {
     }
     updateMeta((m) => ({ ...m, browser: { ...m.browser, [profile.name]: config } }));
 }
+/**
+ * Flag a fleet-synced profile whose contents only make sense on ONE machine.
+ *
+ * A `cdp://` endpoint on loopback always connects on the machine EVALUATING the
+ * profile, so a fleet-scope copy does not mean "that browser" — it means "port N
+ * on whichever box ran the command". The name then silently resolves to a
+ * different, usually logged-out browser on every other machine, which is the
+ * worst possible failure for a profile that carries live logins.
+ *
+ * Reported by `profiles doctor` (a failing `scope` check) and noted in the
+ * `kept` reason `profiles prune` prints for a fleet profile. The repair is
+ * {@link moveProfileScope}, never an automatic rewrite of the synced doc.
+ */
+export function misfiledFleetProfile(profile, scope) {
+    if (scope !== 'fleet')
+        return { misfiled: false };
+    // Judge the endpoint the profile would actually CONNECT on, resolving
+    // `defaultEndpoint` exactly as effectiveLocalPort does. Scanning every preset
+    // instead would fail a legitimate fleet profile that defaults to `ssh://` and
+    // merely carries a loopback alternate for local debugging.
+    const presets = getEndpointPresets(profile);
+    const chosen = profile.defaultEndpoint && presets[profile.defaultEndpoint]
+        ? profile.defaultEndpoint
+        : Object.keys(presets)[0];
+    if (!chosen)
+        return { misfiled: false };
+    const loopback = presets[chosen].target;
+    if (!loopback.startsWith('cdp://'))
+        return { misfiled: false };
+    const parsed = parseEndpointUrl(loopback);
+    if (!parsed || !isLocalHost(parsed.host))
+        return { misfiled: false };
+    return {
+        misfiled: true,
+        why: `fleet-synced but "${loopback}" is a loopback endpoint — on every other machine ` +
+            `this name resolves to that box's own port, not this browser. ` +
+            `Repair on the machine that owns it: agents browser profiles scope ${profile.name} local`,
+    };
+}
+/**
+ * Merge `patch` onto the stored profile and persist it in the store it already
+ * lives in (see {@link updateProfile} for the scope rules).
+ *
+ * Runs {@link createProfile}'s validations against the MERGED record, not just
+ * the patched fields — a binary edit re-resolves the browser path, a
+ * targetFilter edit re-checks the electron gate, and the local-port scan runs
+ * with this profile excluded so an unchanged port is not a self-collision.
+ */
+export async function editProfile(name, patch) {
+    const meta = readMeta();
+    const local = meta.deviceBrowser?.[name];
+    const fleet = meta.browser?.[name];
+    if (!local && !fleet) {
+        throw new Error(`Profile "${name}" does not exist`);
+    }
+    const current = configToProfile(name, (local ?? fleet));
+    const merged = { ...current, ...patch, name };
+    const changed = Object.keys(patch).filter((k) => JSON.stringify(current[k]) !== JSON.stringify(merged[k]));
+    // A target filter only means anything for an Electron app, and the gate must
+    // read the MERGED record: `--target-filter x` on a profile that is already
+    // electron is valid, and `--no-electron` on one that still carries a filter is
+    // not. Checking the patch alone would accept both.
+    if (merged.targetFilter && !merged.electron) {
+        throw new Error(`--target-filter only applies to an Electron profile. ` +
+            `Pass --electron, or clear the filter with --target-filter ''.`);
+    }
+    assertLocalPortFree(merged, { ignore: name });
+    // Same rule as create: the binary lives on the remote for an SSH profile, so a
+    // local lookup would validate the wrong machine.
+    if (!hasSshEndpoint(merged.endpoints)) {
+        findBrowserPath(merged.browser, merged.binary);
+    }
+    await updateProfile(merged);
+    const landedLocal = !!local || isMachineLocalProfile(name);
+    return {
+        profile: merged,
+        scope: landedLocal ? 'local' : 'fleet',
+        changed,
+        fleetCopyLeftStale: landedLocal && !local && !!fleet ? true : undefined,
+    };
+}
+/**
+ * Move an existing profile between the fleet-synced store and this machine's
+ * device store.
+ *
+ * `fleet -> local` is the repair for a profile whose endpoint is machine-bound
+ * (a loopback `cdp://`) but which was created with `--fleet`: the name resolves
+ * to a DIFFERENT browser on every box, because `cdp:` always connects on the
+ * machine evaluating it. Run it ON the machine that owns the browser — the copy
+ * that survives is the one that works.
+ *
+ * Deliberately not automatic. Rewriting the user's synced `agents.yaml` from a
+ * heuristic is the rewrite loop RUSH-2161 fixed; this is an explicit verb.
+ */
+/** Profile names an agent has to be able to type and an fs path can hold. */
+const PROFILE_NAME_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Throw if `name` cannot be used for a NEW profile.
+ *
+ * Shared by `profiles create` and {@link renameProfile} so the two cannot drift
+ * — the shape rule used to live inline in the command, which is how `rename`
+ * would have accepted a name `create` rejects.
+ *
+ * `default` is refused because it is the reserved ALIAS meaning "whatever
+ * profile this machine is configured to use" (RUSH-2709). A literal profile by
+ * that name makes `--profile default` mean two different things.
+ */
+export function assertRegistrableProfileName(name) {
+    if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(`Invalid profile name ${JSON.stringify(name)}. Use lowercase letters, digits and hyphens, ` +
+            `starting with a letter — e.g. 'agents'.`);
+    }
+    if (name === DEFAULT_PROFILE_ALIAS) {
+        throw new Error(`"${DEFAULT_PROFILE_ALIAS}" is the reserved alias for this machine's configured profile, ` +
+            `not a profile name. Pick another name.`);
+    }
+    // `browser.viewer: os` means "use the OS default handler". A profile by that
+    // name turns the opt-out into a pointer at a profile — silently, since both
+    // are just strings in the same key.
+    if (name === 'os') {
+        throw new Error(`"os" is the reserved browser.viewer value meaning the OS default handler, ` +
+            `not a profile name. Pick another name.`);
+    }
+}
+/**
+ * Rename a profile, taking its on-disk state with it.
+ *
+ * `editProfile` deliberately refuses a name change, and this is why: the name
+ * keys the runtime dir ({@link getProfileRuntimeDir}), every fork/endpoint dir
+ * derived from it, and the `browser.profile` pointer. Delete-and-recreate — the
+ * only route before this — silently abandons the browser's `--user-data-dir`,
+ * which is where a profile's logins live. On a real agent browser that is
+ * gigabytes of session state and every account it has ever signed into.
+ *
+ * Refuses when the profile is in use: moving a `--user-data-dir` out from under
+ * a running browser corrupts it.
+ */
+export async function renameProfile(from, to) {
+    if (from === to)
+        throw new Error(`"${from}" is already its own name.`);
+    const meta = readMeta();
+    const local = meta.deviceBrowser?.[from];
+    const fleet = meta.browser?.[from];
+    if (!local && !fleet)
+        throw new Error(`Profile "${from}" does not exist`);
+    if (allProfileConfigs()[to])
+        throw new Error(`Profile "${to}" already exists`);
+    assertRegistrableProfileName(to);
+    const { isProfileInUse, listProfileCacheDirs } = await import('./runtime-state.js');
+    if (isProfileInUse(from)) {
+        throw new Error(`"${from}" is in use (live browser, tunnel, or open task). Renaming would move its ` +
+            `user-data-dir out from under the running browser. Stop it first: agents browser stop --profile ${from}`);
+    }
+    // A name can exist in BOTH stores (local wins in allProfileConfigs). Rewriting
+    // only one leaves the other listed under the OLD name with its data dir already
+    // moved away — the abandoned-`--user-data-dir` state this command exists to
+    // prevent, produced by this command, and previously reported as a clean
+    // success. Refuse instead: which copy the user means is genuinely ambiguous,
+    // and `profiles scope` is the tool for collapsing the duplicate first.
+    if (local && fleet) {
+        // `scope <name> fleet`, NOT local: moveProfileScope computes `from` as
+        // 'local' whenever a local entry exists, so asking for local is a no-op that
+        // reports success and leaves the duplicate. Sending the user there and then
+        // to `profiles delete` — which drops the cached runtime dirs by default —
+        // walked a data-preservation command into a data-destroying one.
+        throw new Error(`"${from}" exists in BOTH this machine's store and the fleet-synced one. ` +
+            `Renaming would move its browser data while leaving one copy behind under the old name.\n` +
+            `  Collapse the duplicate first:  agents browser profiles scope ${from} fleet\n` +
+            `  Then rename.  (To drop a copy instead, agents browser profiles delete ${from} --keep-cache ` +
+            `keeps the browser data.)`);
+    }
+    const config = (local ?? fleet);
+    const scope = local ? 'local' : 'fleet';
+    // Move the on-disk state BEFORE the config, so a crash between the two leaves
+    // a profile whose dirs are already where the new name expects them rather than
+    // a config pointing at dirs that no longer exist.
+    // PRE-FLIGHT every destination before moving ANY of them. With the check
+    // inside the loop, dir N was validated only after dirs 0..N-1 had already
+    // moved: a collision on the second endpoint left the first one's logins
+    // stranded under a name with no config entry, and the error named only the
+    // squatter. Nothing repaired that, and the user was never told.
+    const plan = [];
+    for (const dir of listProfileCacheDirs(from)) {
+        const base = path.basename(dir);
+        const suffix = base.slice(from.length);
+        const dest = path.join(path.dirname(dir), `${to}${suffix}`);
+        if (fs.existsSync(dest)) {
+            throw new Error(`Cannot rename: ${dest} already exists. Nothing was moved. Remove or rename it first.`);
+        }
+        plan.push({ dir, dest });
+    }
+    const movedDirs = [];
+    for (const { dir, dest } of plan) {
+        fs.renameSync(dir, dest);
+        movedDirs.push(dest);
+    }
+    if (scope === 'local') {
+        updateMeta((m) => {
+            const next = { ...m.deviceBrowser };
+            delete next[from];
+            return { ...m, deviceBrowser: { ...next, [to]: config } };
+        });
+    }
+    else {
+        updateMeta((m) => {
+            const next = { ...m.browser };
+            delete next[from];
+            return { ...m, browser: { ...next, [to]: config } };
+        });
+    }
+    // Both pointers are separate keys. Leaving `browser.profile` behind falls back
+    // to auto-detect on the next `browser start`; leaving `browser.viewer` behind
+    // sends every artifact back to the OS default handler — which is the exact bug
+    // the viewer seam was built to fix, reintroduced by a rename.
+    const { setConfigValue, getConfigValue } = await import('../device-config.js');
+    let repointedDefault = false;
+    if (getConfiguredDefaultProfileName() === from) {
+        setConfigValue('browser.profile', to);
+        repointedDefault = true;
+    }
+    let repointedViewer = false;
+    if (getConfigValue('browser.viewer').value === from) {
+        setConfigValue('browser.viewer', to);
+        repointedViewer = true;
+    }
+    // A fleet rename changes the name on every machine, but each machine's own
+    // config doc is separate — a peer pinning the old name is left dangling. Not
+    // rewritten from here: that would be a cross-machine mutation, and on a peer
+    // the pin may be correct (a LOCAL profile of the same name). Reported instead.
+    const { devicesPinningBrowserProfile } = await import('../device-config.js');
+    const { machineId } = await import('../machine-id.js');
+    const stalePins = scope === 'fleet'
+        ? devicesPinningBrowserProfile(from).filter((p) => p.device !== machineId())
+        : [];
+    return { scope, movedDirs, repointedDefault, repointedViewer, stalePins };
+}
+export async function moveProfileScope(name, to) {
+    const meta = readMeta();
+    const local = meta.deviceBrowser?.[name];
+    const fleet = meta.browser?.[name];
+    if (!local && !fleet) {
+        throw new Error(`Profile "${name}" does not exist`);
+    }
+    const from = local ? 'local' : 'fleet';
+    if (from === to)
+        return { from, to };
+    if (to === 'fleet' && isMachineLocalProfile(name)) {
+        throw new Error(`"${name}" is always machine-local — its binary path and port are this box's. ` +
+            `Fleet-syncing it is the rewrite loop RUSH-2161 fixed.`);
+    }
+    const config = (local ?? fleet);
+    // Write the destination BEFORE dropping the source, so a crash between the two
+    // leaves a duplicate (harmless — local wins in allProfileConfigs) rather than
+    // no profile at all.
+    if (to === 'local') {
+        updateMeta((m) => ({ ...m, deviceBrowser: { ...m.deviceBrowser, [name]: config } }));
+        updateMeta((m) => {
+            const next = { ...m.browser };
+            delete next[name];
+            return { ...m, browser: Object.keys(next).length > 0 ? next : undefined };
+        });
+    }
+    else {
+        updateMeta((m) => ({ ...m, browser: { ...m.browser, [name]: config } }));
+        updateMeta((m) => {
+            const next = { ...m.deviceBrowser };
+            delete next[name];
+            return { ...m, deviceBrowser: Object.keys(next).length > 0 ? next : undefined };
+        });
+    }
+    return { from, to };
+}
 export async function deleteProfile(name) {
     const meta = readMeta();
     const isLocal = !!meta.deviceBrowser?.[name];

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

@@ -9,8 +9,15 @@
  * `browser.remote-control` config key, never synced).
  *
  * Local invocations (no marker) are never gated — this only governs cross-machine
- * drives. Read-only queries are not gated here; the gate sits at the drive entry
- * point (`browser start`), the one command that opens/attaches a browser.
+ * drives. Read-only queries are not gated.
+ *
+ * The authoritative gate is {@link assertRemoteControlAllowedForRequest}, called
+ * inside the browser daemon at the two points that can OPEN a browser
+ * (`BrowserService.start` and the create branch of `resolveOrCreateTask`). It has
+ * to live there because ~18 page verbs (`navigate`, `click`, `screenshot`, …)
+ * create a browser implicitly, and gating only the `browser start` command left
+ * every one of them ungated. {@link assertRemoteControlAllowed} remains as a
+ * fast-fail CLI-side check so a refused `start` never auto-creates a profile.
  */
 /** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
 export declare const FLEET_REMOTE_ENV = "AGENTS_FLEET_REMOTE";
@@ -33,3 +40,20 @@ export declare function assertRemoteControlAllowed(opts?: {
     env?: NodeJS.ProcessEnv;
     enabled?: boolean;
 }): void;
+/**
+ * The daemon-side consent gate.
+ *
+ * Reads ONLY the per-request marker, never `process.env`: the browser daemon is
+ * shared and long-lived, and it may have been auto-started by a fleet-remote CLI
+ * that leaked `AGENTS_FLEET_REMOTE=1` into its environment permanently. Reading
+ * the daemon's env would then refuse every subsequent LOCAL drive on this
+ * machine until the daemon restarted.
+ *
+ * `actor` is likewise the caller's forwarded identity, not the daemon's.
+ */
+export declare function assertRemoteControlAllowedForRequest(fleetRemote: boolean | undefined, opts?: {
+    actor?: string;
+    enabled?: boolean;
+}): void;
+/** The refusal text, shared by the CLI-side and daemon-side gates. */
+export declare function remoteControlRefusal(who: string): string;

package/dist/lib/browser/remote-control.js

@@ -9,8 +9,15 @@
  * `browser.remote-control` config key, never synced).
  *
  * Local invocations (no marker) are never gated — this only governs cross-machine
- * drives. Read-only queries are not gated here; the gate sits at the drive entry
- * point (`browser start`), the one command that opens/attaches a browser.
+ * drives. Read-only queries are not gated.
+ *
+ * The authoritative gate is {@link assertRemoteControlAllowedForRequest}, called
+ * inside the browser daemon at the two points that can OPEN a browser
+ * (`BrowserService.start` and the create branch of `resolveOrCreateTask`). It has
+ * to live there because ~18 page verbs (`navigate`, `click`, `screenshot`, …)
+ * create a browser implicitly, and gating only the `browser start` command left
+ * every one of them ungated. {@link assertRemoteControlAllowed} remains as a
+ * fast-fail CLI-side check so a refused `start` never auto-creates a profile.
  */
 import { getConfigValue } from '../device-config.js';
 /** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
@@ -42,7 +49,30 @@ export function assertRemoteControlAllowed(opts) {
     if (enabled)
         return;
     const who = env.AGENTS_ACTOR_HOST || env.AGENTS_ACTOR || 'A fleet machine';
-    throw new Error(`${who} tried to drive this machine's browser over \`browser --device\`, but remote ` +
+    throw new Error(remoteControlRefusal(who));
+}
+/**
+ * The daemon-side consent gate.
+ *
+ * Reads ONLY the per-request marker, never `process.env`: the browser daemon is
+ * shared and long-lived, and it may have been auto-started by a fleet-remote CLI
+ * that leaked `AGENTS_FLEET_REMOTE=1` into its environment permanently. Reading
+ * the daemon's env would then refuse every subsequent LOCAL drive on this
+ * machine until the daemon restarted.
+ *
+ * `actor` is likewise the caller's forwarded identity, not the daemon's.
+ */
+export function assertRemoteControlAllowedForRequest(fleetRemote, opts = {}) {
+    if (!fleetRemote)
+        return;
+    const enabled = opts.enabled ?? remoteControlEnabled();
+    if (enabled)
+        return;
+    throw new Error(remoteControlRefusal(opts.actor || 'A fleet machine'));
+}
+/** The refusal text, shared by the CLI-side and daemon-side gates. */
+export function remoteControlRefusal(who) {
+    return (`${who} tried to drive this machine's browser over \`browser --device\`, but remote ` +
         `browser control is off here. To allow it, run on THIS machine:\n` +
         `  agents browser remote-control on`);
 }

package/dist/lib/browser/runtime-state.d.ts

@@ -148,6 +148,13 @@ export interface PrunePlan {
         name: string;
         scope: ProfileScope;
         why: string;
+        /**
+         * True for a fleet profile whose endpoint only makes sense on one machine.
+         * A structured flag, not a substring of `why`: both the CLI's human output
+         * and `--json` consumers branch on it, and sniffing the reason text would
+         * couple them to wording.
+         */
+        misfiled?: boolean;
     }>;
 }
 export declare const PRUNE_REASON_TEXT: Record<PruneReason, string>;
@@ -182,6 +189,8 @@ export declare function planProfilePrune(profiles: Array<{
     name: string;
     scope: ProfileScope;
     launchableHere: boolean;
+    /** Set when this fleet profile's endpoint only makes sense on one machine. */
+    misfiledWhy?: string;
 }>, opts?: {
     includeFleet?: boolean;
     configuredDefault?: string;

package/dist/lib/browser/runtime-state.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { getProfileRuntimeDir, getBrowserRuntimeDir, listProfilesWithScope, getConfiguredDefaultProfileName, isProfileLaunchableHere, deleteProfile, DEFAULT_BROWSER_PROFILE_NAME, LEGACY_DEFAULT_BROWSER_PROFILE_NAME, } from './profiles.js';
+import { getProfileRuntimeDir, getBrowserRuntimeDir, listProfilesWithScope, getConfiguredDefaultProfileName, isProfileLaunchableHere, deleteProfile, DEFAULT_BROWSER_PROFILE_NAME, LEGACY_DEFAULT_BROWSER_PROFILE_NAME, misfiledFleetProfile, } from './profiles.js';
 import { keyBelongsToProfile } from './types.js';
 const PID_FILE = 'pid';
 const PORT_FILE = 'port';
@@ -308,8 +308,20 @@ export const PRUNE_REASON_TEXT = {
  */
 export function planProfilePrune(profiles, opts = {}) {
     const plan = { candidates: [], kept: [] };
-    for (const { name, scope, launchableHere } of profiles) {
-        const keep = (why) => { plan.kept.push({ name, scope, why }); };
+    for (const { name, scope, launchableHere, misfiledWhy } of profiles) {
+        const keep = (why, misfiled = false) => {
+            plan.kept.push(misfiled ? { name, scope, why, misfiled } : { name, scope, why });
+        };
+        // Checked FIRST, ahead of every other rule including --fleet. Deleting a
+        // fleet entry deletes it on EVERY machine, and a misfiled profile's defining
+        // symptom is that the browser is absent on whatever box you are standing on
+        // — so `prune --fleet` would otherwise read `binary-missing` and destroy it
+        // fleet-wide, which is the opposite of the repair. The repair is a scope
+        // move; an intentional delete is still available as `profiles delete`.
+        if (misfiledWhy) {
+            keep(`MISFILED — ${misfiledWhy}`, true);
+            continue;
+        }
         if (scope === 'fleet' && !opts.includeFleet) {
             keep('fleet-synced (pass --fleet to include it)');
             continue;
@@ -345,11 +357,15 @@ export function planProfilePrune(profiles, opts = {}) {
  */
 export async function buildProfilePrunePlan(opts = {}) {
     const scoped = await listProfilesWithScope();
-    return planProfilePrune(scoped.map(({ profile, scope }) => ({
-        name: profile.name,
-        scope,
-        launchableHere: isProfileLaunchableHere(profile),
-    })), { includeFleet: opts.includeFleet, configuredDefault: getConfiguredDefaultProfileName() });
+    return planProfilePrune(scoped.map(({ profile, scope }) => {
+        const misfiled = misfiledFleetProfile(profile, scope);
+        return {
+            name: profile.name,
+            scope,
+            launchableHere: isProfileLaunchableHere(profile),
+            misfiledWhy: misfiled.misfiled ? misfiled.why : undefined,
+        };
+    }), { includeFleet: opts.includeFleet, configuredDefault: getConfiguredDefaultProfileName() });
 }
 /**
  * Execute a prune plan: drop each candidate's config entry and wipe its cache

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

@@ -161,6 +161,8 @@ export declare class BrowserService {
         launchId?: string;
         /** Calling agent session, forwarded from the CLI (see IPCRequest.sessionId). */
         sessionId?: string;
+        /** Whether the CALLER was dispatched here by a fleet `--device` hop. */
+        fleetRemote?: boolean;
         /** Explicit human label (`--title`). */
         title?: string;
     }): Promise<{
@@ -469,6 +471,8 @@ export declare class BrowserService {
      *   - no handle, zero, !createIfMissing → return null (caller reports "nothing to close")
      */
     resolveOrCreateTask(opts: {
+        /** Whether the CALLER was dispatched here by a fleet `--device` hop. */
+        fleetRemote?: boolean;
         task?: string;
         profile?: string;
         actor?: string;
@@ -536,6 +540,39 @@ export declare class BrowserService {
     private saveTaskState;
     private loadTaskState;
     private saveToHistory;
+    /**
+     * The cached connection for `key`, or undefined — evicting it first if the
+     * browser died underneath us.
+     *
+     * A browser killed externally (Cmd-Q, crash, a user clearing the profile by
+     * hand) leaves a closed WebSocket in the map. Without this the next
+     * `cdp.send` throws "CDP connection not open" and there is no recovery short
+     * of killing the daemon.
+     */
+    private reuseHealthyConnection;
+    /** Connect a profile at `target`, register it under `key`, and arm downloads. */
+    private openConnection;
+    /**
+     * Open a tab for a HUMAN to read, bound to no task.
+     *
+     * That is the entire difference from {@link start}, and it is the point. The
+     * abandoned-task reaper closes a task's tabs when the calling session dies or
+     * after the idle window, but it "deliberately never touches a tab that is not
+     * in `task.tabs`" (hygiene.ts) — so a viewer tab must not be in one, or the
+     * artifact the user is reading vanishes when the agent that rendered it exits.
+     *
+     * Consequently `stop`/`done` do not close it either, which is correct: it is
+     * the user's tab now.
+     */
+    showUrl(profileName: ProfileName, url: string, opts?: {
+        endpointName?: string;
+        fleetRemote?: boolean;
+        actor?: string;
+    }): Promise<{
+        profile: ProfileName;
+        key: ConnectionKey;
+        tabId: string;
+    }>;
     getHistory(limit?: number): Promise<HistoricalTask[]>;
 }
 export {};