@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/browser/registry.js

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import * as yaml from 'yaml';
+import { getUserAgentsDir, readMeta, updateMeta } from '../state.js';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+export function centralBrowserProfiles() {
+    const central = readMeta().browser;
+    if (!central || Object.keys(central).length === 0)
+        return {};
+    return { ...central };
+}
+/**
+ * Fold leftover central `browser:` entries into THIS device's declaration file.
+ *
+ * Never called implicitly, and that is the point. Every device can read the
+ * central map, so an implicit claim races: whichever box happens to read first
+ * claims the name, {@link profileKind} then reports it `identity`, and the
+ * daemon tunnels to that box — which for a fleet-wide `cdp://localhost:*`
+ * profile is a logged-out headless browser wearing a credentialed browser's
+ * name. That is the exact bug this module exists to remove, and an implicit
+ * migration would write it to disk as a stored fact.
+ *
+ * The claim is an explicit operator action (`agents browser profiles claim`),
+ * run on the machine that actually owns the browser. `canHostHere` is supplied
+ * by the command layer so this module stays a leaf — it must not import
+ * `isProfileLaunchableHere` (that would cycle through chrome.ts → profiles.ts).
+ * Only profiles this machine can host are claimed; the rest stay central,
+ * undeclared, and fail loudly on resolve.
+ */
+export function migrateCentralBrowserProfiles(canHostHere, name) {
+    const meta = readMeta();
+    const central = meta.browser;
+    if (!central || Object.keys(central).length === 0) {
+        if (name) {
+            throw new Error(`No leftover central browser profile named "${name}".`);
+        }
+        return { claimed: [], skipped: [] };
+    }
+    const local = meta.deviceBrowser ?? {};
+    if (name) {
+        const config = central[name];
+        if (!config) {
+            throw new Error(local[name]
+                ? `Browser profile "${name}" is already declared on this device.`
+                : `No leftover central browser profile named "${name}".`);
+        }
+        if (!canHostHere(config)) {
+            throw new Error(`Cannot claim browser profile "${name}": this machine cannot host it ` +
+                `(its browser/binary isn't installed here). Run this command on the machine that has that browser.`);
+        }
+    }
+    const toClaim = {};
+    const skipped = [];
+    for (const [profileName, config] of Object.entries(central)) {
+        if (name && profileName !== name)
+            continue;
+        if (!canHostHere(config)) {
+            skipped.push(profileName);
+            continue;
+        }
+        const existing = local[profileName];
+        if (existing && !isDeepStrictEqual(existing, config)) {
+            throw new Error(`Cannot migrate browser profile "${profileName}": central agents.yaml and this device's ` +
+                `agents.yaml declare different configurations. Resolve the duplicate before retrying.`);
+        }
+        toClaim[profileName] = config;
+    }
+    const claimed = Object.keys(toClaim).sort();
+    skipped.sort();
+    if (claimed.length === 0)
+        return { claimed, skipped };
+    updateMeta((current) => {
+        const legacy = current;
+        const remaining = {};
+        for (const [profileName, config] of Object.entries(legacy.browser ?? {})) {
+            if (!(profileName in toClaim))
+                remaining[profileName] = config;
+        }
+        const { browser: _removed, ...withoutCentralBrowser } = legacy;
+        return {
+            ...withoutCentralBrowser,
+            ...(Object.keys(remaining).length > 0 ? { browser: remaining } : {}),
+            deviceBrowser: { ...current.deviceBrowser, ...toClaim },
+        };
+    });
+    return { claimed, skipped };
+}
+/**
+ * Every profile any device declares, keyed by name to all declaring devices.
+ * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.
+ */
+export function profileRegistry() {
+    const registry = new Map();
+    const devicesDir = path.join(getUserAgentsDir(), 'devices');
+    if (!fs.existsSync(devicesDir))
+        return registry;
+    const devices = fs
+        .readdirSync(devicesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const device of devices) {
+        const file = path.join(devicesDir, device, 'agents.yaml');
+        if (!fs.existsSync(file))
+            continue;
+        let parsed;
+        try {
+            parsed = yaml.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`Cannot read browser declarations from ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (parsed == null)
+            continue;
+        if (!isRecord(parsed)) {
+            throw new Error(`Cannot read browser declarations from ${file}: document root must be a map.`);
+        }
+        const browser = parsed.browser;
+        if (browser == null)
+            continue;
+        if (!isRecord(browser)) {
+            throw new Error(`Cannot read browser declarations from ${file}: browser must be a map.`);
+        }
+        for (const [name, config] of Object.entries(browser)) {
+            if (!isRecord(config)) {
+                throw new Error(`Cannot read browser declaration "${name}" from ${file}: profile must be a map.`);
+            }
+            const declarations = registry.get(name) ?? [];
+            declarations.push({ device, config: config });
+            registry.set(name, declarations);
+        }
+    }
+    return registry;
+}
+/** Devices declaring `name`, empty when nobody does. */
+export function declaringDevices(name) {
+    return (profileRegistry().get(name) ?? []).map((declaration) => declaration.device);
+}
+/** Exactly one declaring device is identity-bearing; several are fungible. */
+export function profileKind(name) {
+    const count = profileRegistry().get(name)?.length ?? 0;
+    if (count === 0)
+        return null;
+    return count === 1 ? 'identity' : 'fungible';
+}

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

@@ -9,8 +9,17 @@
  * `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 top of `resolveOrCreateTask` — the one
+ * chokepoint every task-scoped verb resolves through — plus `BrowserService.start`
+ * for the task-less `browser start` command. It has to live there because ~18
+ * page verbs (`navigate`, `click`, `screenshot`, `tab-add`, …) launch OR attach
+ * to a browser implicitly, and gating only the `browser start` command left every
+ * one of them ungated; gating only the create branch of `resolveOrCreateTask` left
+ * the attach paths ungated (RUSH-3064). {@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 +42,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,17 @@
  * `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 top of `resolveOrCreateTask` — the one
+ * chokepoint every task-scoped verb resolves through — plus `BrowserService.start`
+ * for the task-less `browser start` command. It has to live there because ~18
+ * page verbs (`navigate`, `click`, `screenshot`, `tab-add`, …) launch OR attach
+ * to a browser implicitly, and gating only the `browser start` command left every
+ * one of them ungated; gating only the create branch of `resolveOrCreateTask` left
+ * the attach paths ungated (RUSH-3064). {@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 +51,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/resolve-target.d.ts

@@ -0,0 +1,68 @@
+import { type ProfileDeclaration } from './registry.js';
+import { type BrowserProfile, type ConnectionKey } from './types.js';
+import type { BrowserProfileConfig } from '../types.js';
+export type DeviceProbeResult = {
+    reachable: true;
+    os?: string;
+} | {
+    reachable: false;
+    reason: string;
+};
+export type DeviceProbe = (device: string) => DeviceProbeResult;
+export interface ResolvedBrowserTarget {
+    name: string;
+    kind: 'identity' | 'fungible';
+    /** Device the daemon will talk to. */
+    device: string;
+    local: boolean;
+    key: ConnectionKey;
+    /** `cdp:` locally, `ssh:` when tunnelling to a declaring device. */
+    target: string;
+    profile: BrowserProfile;
+    /**
+     * Human line when the daemon picked a remote device. Command output
+     * surfaces this so the caller knows WHERE the browser actually lives.
+     */
+    picked?: string;
+}
+/** Fork only fungible Electron profiles; identity-bearing ones share one connection. */
+export declare function shouldForkProfile(kind: 'identity' | 'fungible', conn: {
+    electron?: boolean;
+    tasks: {
+        size: number;
+    };
+}): boolean;
+export declare function profileFromDeclaration(name: string, declaration: ProfileDeclaration): BrowserProfile;
+/** Runtime key: profile name plus the resolved device. Drops `@endpoint-N`. */
+export declare function profileConnectionKey(profileName: string, device: string): ConnectionKey;
+/** Declared names that look like `query` — used in the undeclared error. */
+export declare function similarProfileNames(query: string, names: string[]): string[];
+export declare function undeclaredProfileError(name: string): Error;
+export declare function unreachableDeclaringDevicesError(name: string, devices: string[], failures: string[]): Error;
+export declare function sshEndpointForDeclaration(device: string, config: BrowserProfileConfig, endpointName?: string, os?: string): string;
+/**
+ * Decide where `name` connects. Never claims a central leftover. Never
+ * falls back to a local browser when the name is declared elsewhere.
+ */
+export declare function resolveBrowserTarget(name: string, opts?: {
+    endpointName?: string;
+    here?: string;
+    probe?: DeviceProbe;
+}): ResolvedBrowserTarget;
+/**
+ * Rename a leftover `<name>@endpoint-N` runtime dir to the new
+ * `<name>@<device>` key so logins in chrome-data are not orphaned.
+ *
+ * Only when exactly one legacy dir exists and the destination does not —
+ * several endpoint dirs stay put so a multi-endpoint profile is not merged.
+ */
+/**
+ * Adopt a leftover `@endpoint-N` runtime dir onto the new key ONLY for a
+ * local connect. Doing this for a tunnel key would rename this machine's
+ * pre-T2 logged-out chrome-data onto `comet-local@zion`, and connectProfile
+ * would then attach localhost CDP instead of tunnelling.
+ */
+export declare function adoptLegacyRuntimeIfLocal(local: boolean, profileName: string, newKey: ConnectionKey, runtimeRoot: string): void;
+export declare function migrateLegacyRuntimeDir(profileName: string, newKey: ConnectionKey, runtimeRoot: string): void;
+/** True when a live key is a leftover `@endpoint-N` key of `profileName`. */
+export declare function isLegacyEndpointKey(key: string, profileName: string): boolean;

package/dist/lib/browser/resolve-target.js

@@ -0,0 +1,250 @@
+/**
+ * Registry-driven browser target resolution.
+ *
+ * The profile KIND is not a field: it falls out of how many devices declare
+ * the name ({@link profileKind}). This module answers where a name should
+ * connect, and never claims a leftover central profile (that race is T1).
+ *
+ * Three outcomes, no fourth:
+ *   1. THIS device declares the name → connect locally.
+ *   2. Only OTHER devices declare it → tunnel to a reachable declaring device.
+ *   3. Nobody declares it → fail loud. Never auto-create a local browser
+ *      under a name that means a logged-in browser somewhere else.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { machineId } from '../machine-id.js';
+import { centralBrowserProfiles, declaringDevices, profileKind, profileRegistry, } from './registry.js';
+import { parseEndpointUrl, resolveEndpoint } from './profiles.js';
+import { connectionKey, parseConnectionKey, } from './types.js';
+import { probeHost } from '../hosts/ready.js';
+/** Fork only fungible Electron profiles; identity-bearing ones share one connection. */
+export function shouldForkProfile(kind, conn) {
+    if (kind === 'identity')
+        return false;
+    return Boolean(conn.electron && conn.tasks.size > 0);
+}
+export function profileFromDeclaration(name, declaration) {
+    const config = declaration.config;
+    return {
+        name,
+        description: config.description,
+        browser: config.browser,
+        binary: config.binary,
+        electron: config.electron,
+        targetFilter: config.targetFilter,
+        endpoints: config.endpoints,
+        defaultEndpoint: config.defaultEndpoint,
+        chrome: config.chrome,
+        secrets: config.secrets,
+        viewport: config.viewport,
+        logDir: config.logDir,
+        logHost: config.logHost,
+    };
+}
+/** Runtime key: profile name plus the resolved device. Drops `@endpoint-N`. */
+export function profileConnectionKey(profileName, device) {
+    return connectionKey(profileName, device);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 0; i < a.length; i++) {
+        let prev = row[0];
+        row[0] = i + 1;
+        for (let j = 0; j < b.length; j++) {
+            const cur = row[j + 1];
+            const cost = a[i] === b[j] ? 0 : 1;
+            row[j + 1] = Math.min(row[j] + 1, row[j + 1] + 1, prev + cost);
+            prev = cur;
+        }
+    }
+    return row[b.length];
+}
+/** Declared names that look like `query` — used in the undeclared error. */
+export function similarProfileNames(query, names) {
+    const q = query.toLowerCase();
+    const maxDist = Math.max(2, Math.floor(q.length / 4));
+    return names
+        .filter((name) => {
+        const x = name.toLowerCase();
+        if (x === q)
+            return false;
+        if (x.includes(q) || q.includes(x))
+            return Math.min(x.length, q.length) >= 3;
+        return levenshtein(x, q) <= maxDist;
+    })
+        .sort();
+}
+function lines(...parts) {
+    return parts.filter((part) => part != null && part !== '').join('\n');
+}
+export function undeclaredProfileError(name) {
+    const central = centralBrowserProfiles();
+    if (central[name]) {
+        return new Error(lines(`Browser profile "${name}" is not declared by any device.`, `It still lives in the central agents.yaml browser: map.`, `Claim it on the machine that hosts that browser with: agents browser profiles claim ${name}`));
+    }
+    const registry = profileRegistry();
+    const similar = similarProfileNames(name, [...registry.keys()]);
+    const similarLines = similar.map((candidate) => {
+        const devices = (registry.get(candidate) ?? []).map((entry) => entry.device);
+        return devices.length > 0
+            ? `  ${candidate} (declared on ${devices.join(', ')})`
+            : `  ${candidate}`;
+    });
+    return new Error(lines(`Browser profile "${name}" is not declared by any device.`, ...(similarLines.length > 0
+        ? ['Similar names:', ...similarLines]
+        : ['No device declares a similar name.']), `Create it on the machine that hosts the browser: agents browser profiles create ${name} --browser <chrome|comet|chromium|brave|edge|arc|custom>`, `Or, if it is a leftover central profile, claim it: agents browser profiles claim ${name}`));
+}
+export function unreachableDeclaringDevicesError(name, devices, failures) {
+    return new Error(lines(`Browser profile "${name}" is declared on ${devices.join(', ')}, but none of those devices are reachable.`, ...failures.map((line) => `  ${line}`), `A local browser will not be launched — that would be a logged-out copy of an identity-bearing profile.`));
+}
+/**
+ * Build the SSH endpoint used to tunnel to a declaring device's own browser.
+ *
+ * A `cdp://localhost:N` declaration on that device is THIS machine's loopback
+ * if used as-is — that is the original bug. Rewrite it to `ssh://<device>?port=N`.
+ * An already-`ssh://` declaration is used as written.
+ */
+function isWindowsOs(os) {
+    if (!os)
+        return false;
+    const normalized = os.toLowerCase();
+    return (normalized.includes('windows') ||
+        normalized === 'win32' ||
+        normalized === 'win64' ||
+        normalized === 'windows_nt');
+}
+export function sshEndpointForDeclaration(device, config, endpointName, os) {
+    const profile = profileFromDeclaration('_', { device, config });
+    const resolved = resolveEndpoint(profile, endpointName);
+    if (resolved.target.startsWith('ssh:'))
+        return resolved.target;
+    const parsed = parseEndpointUrl(resolved.target);
+    const port = parsed?.port ?? 9222;
+    const osQuery = isWindowsOs(os) ? '&os=windows' : '';
+    return `ssh://${device}?port=${port}${osQuery}`;
+}
+function defaultProbe(device) {
+    try {
+        const result = probeHost(device);
+        if (result.reachable)
+            return { reachable: true, os: result.os };
+        return { reachable: false, reason: `ssh to ${device} failed` };
+    }
+    catch (error) {
+        return {
+            reachable: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Decide where `name` connects. Never claims a central leftover. Never
+ * falls back to a local browser when the name is declared elsewhere.
+ */
+export function resolveBrowserTarget(name, opts = {}) {
+    const here = opts.here ?? machineId();
+    const kind = profileKind(name);
+    const declarations = profileRegistry().get(name) ?? [];
+    if (kind === null || declarations.length === 0) {
+        throw undeclaredProfileError(name);
+    }
+    const devices = declaringDevices(name);
+    const local = declarations.find((entry) => entry.device === here);
+    if (local) {
+        const profile = profileFromDeclaration(name, local);
+        const resolved = resolveEndpoint(profile, opts.endpointName);
+        return {
+            name,
+            kind,
+            device: here,
+            local: true,
+            key: profileConnectionKey(name, here),
+            target: resolved.target,
+            profile: {
+                ...profile,
+                binary: resolved.binary,
+                targetFilter: resolved.targetFilter,
+            },
+        };
+    }
+    const probe = opts.probe ?? defaultProbe;
+    const candidates = [...declarations].sort((a, b) => a.device.localeCompare(b.device));
+    const failures = [];
+    for (const declaration of candidates) {
+        const result = probe(declaration.device);
+        if (!result.reachable) {
+            failures.push(`${declaration.device}: ${result.reason}`);
+            continue;
+        }
+        const profile = profileFromDeclaration(name, declaration);
+        const resolved = resolveEndpoint(profile, opts.endpointName);
+        const target = sshEndpointForDeclaration(declaration.device, declaration.config, opts.endpointName, result.os);
+        const picked = candidates.length > 1
+            ? `Using ${name} on ${declaration.device} (declared on ${devices.join(', ')})`
+            : `Using ${name} on ${declaration.device}`;
+        return {
+            name,
+            kind,
+            device: declaration.device,
+            local: false,
+            key: profileConnectionKey(name, declaration.device),
+            target,
+            profile: {
+                ...profile,
+                binary: resolved.binary,
+                targetFilter: resolved.targetFilter,
+            },
+            picked,
+        };
+    }
+    throw unreachableDeclaringDevicesError(name, devices, failures);
+}
+/**
+ * Rename a leftover `<name>@endpoint-N` runtime dir to the new
+ * `<name>@<device>` key so logins in chrome-data are not orphaned.
+ *
+ * Only when exactly one legacy dir exists and the destination does not —
+ * several endpoint dirs stay put so a multi-endpoint profile is not merged.
+ */
+/**
+ * Adopt a leftover `@endpoint-N` runtime dir onto the new key ONLY for a
+ * local connect. Doing this for a tunnel key would rename this machine's
+ * pre-T2 logged-out chrome-data onto `comet-local@zion`, and connectProfile
+ * would then attach localhost CDP instead of tunnelling.
+ */
+export function adoptLegacyRuntimeIfLocal(local, profileName, newKey, runtimeRoot) {
+    if (!local)
+        return;
+    migrateLegacyRuntimeDir(profileName, newKey, runtimeRoot);
+}
+export function migrateLegacyRuntimeDir(profileName, newKey, runtimeRoot) {
+    const dest = path.join(runtimeRoot, newKey);
+    if (fs.existsSync(dest))
+        return;
+    if (!fs.existsSync(runtimeRoot))
+        return;
+    const legacy = fs.readdirSync(runtimeRoot).filter((entry) => {
+        const parsed = parseConnectionKey(entry);
+        return (parsed.profile === profileName &&
+            parsed.endpoint !== undefined &&
+            /^endpoint-\d+$/.test(parsed.endpoint) &&
+            parsed.fork === undefined);
+    });
+    if (legacy.length !== 1)
+        return;
+    fs.renameSync(path.join(runtimeRoot, legacy[0]), dest);
+}
+/** True when a live key is a leftover `@endpoint-N` key of `profileName`. */
+export function isLegacyEndpointKey(key, profileName) {
+    const parsed = parseConnectionKey(key);
+    return (parsed.profile === profileName &&
+        parsed.endpoint !== undefined &&
+        /^endpoint-\d+$/.test(parsed.endpoint));
+}

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

@@ -1,5 +1,33 @@
-import { type ProfileScope } from './profiles.js';
+import { type BrowserProfileWithDeclarations } from './profiles.js';
 import { type ProfileName } from './types.js';
+/**
+ * How many devices declare this profile — the shipped model's two kinds.
+ *
+ * NOT the deleted `scope: local | fleet`, which described where the config was
+ * stored. `fungible` means several devices declare the name and each uses its
+ * own browser; `identity` means exactly one does, so the name is a singular
+ * browser. Prune only ever sees profiles THIS device declares, so `fungible`
+ * here means "declared here and elsewhere too".
+ */
+type PruneProfileClass = 'identity' | 'fungible';
+/**
+ * Detect an identity-bearing profile whose stored endpoint is loopback, viewed
+ * from a machine that is NOT the declaring device.
+ *
+ * That is the original `comet-local` bug: five real logins on the declaring
+ * box, a bare logged-out chromium answering to the same name on a worker
+ * because `cdp://localhost:N` is evaluated on the machine running the command.
+ * The daemon now tunnels that shape (`resolve-target.ts`); doctor still flags
+ * it so a worker does not report a green local binary/port for someone else's
+ * browser. Kind comes from the registry (exactly one declaring device), never
+ * from a stored field.
+ */
+export declare function identityLoopbackMismatch(profile: BrowserProfileWithDeclarations): {
+    misfiled: false;
+} | {
+    misfiled: true;
+    why: string;
+};
 /**
  * Per-profile runtime files we persist under
  * `~/.agents/.cache/browser/<composite>/`:
@@ -51,7 +79,7 @@ export declare function readProfileRuntime(profileName: string): ProfileRuntime
 export declare function clearProfileRuntime(profileName: string): void;
 /**
  * Recursively remove the whole profile cache (chrome-data, tasks.json,
- * everything). Used by `profiles delete` so an old profile name doesn't
+ * everything). Used by `profiles remove` so an old profile name doesn't
  * leak its history into a freshly-recreated one.
  */
 export declare function removeProfileCache(profileName: string): void;
@@ -135,7 +163,7 @@ export declare function isProfileInUse(profileName: string): boolean;
 export type PruneReason = 'binary-missing' | 'never-used';
 export interface PruneCandidate {
     name: string;
-    scope: ProfileScope;
+    scope: PruneProfileClass;
     reason: PruneReason;
     /** Cache dirs that would be removed along with the config entry. */
     cacheDirs: string[];
@@ -146,8 +174,15 @@ export interface PrunePlan {
     /** Profiles deliberately left alone, with the guard that kept them. */
     kept: Array<{
         name: string;
-        scope: ProfileScope;
+        scope: PruneProfileClass;
         why: string;
+        /**
+         * True for an identity-bearing profile whose loopback endpoint only makes
+         * sense on the declaring device. 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>;
@@ -170,8 +205,6 @@ export declare const PRUNE_REASON_TEXT: Record<PruneReason, string>;
  *   - **the auto-detected profile** (`auto-chrome`, or the `default` an older
  *     build wrote) — auto-regenerated by `ensureDefaultBrowserProfile`, so
  *     pruning it is pure churn.
- *   - **fleet-synced** — deleting one removes it from EVERY machine, so it takes
- *     the explicit `includeFleet` opt-in.
  *
  * Known limitation: `BrowserProfileConfig` records no creation time, so a
  * profile created seconds ago and not yet started is indistinguishable from an
@@ -180,22 +213,22 @@ export declare const PRUNE_REASON_TEXT: Record<PruneReason, string>;
  */
 export declare function planProfilePrune(profiles: Array<{
     name: string;
-    scope: ProfileScope;
+    scope: PruneProfileClass;
     launchableHere: boolean;
+    /** Set when this identity-bearing profile's endpoint only makes sense on one machine. */
+    misfiledWhy?: string;
 }>, opts?: {
-    includeFleet?: boolean;
     configuredDefault?: string;
 }): PrunePlan;
 /**
  * Build the prune plan from live config. Split from {@link planProfilePrune} so
  * the decision rules stay unit-testable without a configured machine.
  */
-export declare function buildProfilePrunePlan(opts?: {
-    includeFleet?: boolean;
-}): Promise<PrunePlan>;
+export declare function buildProfilePrunePlan(): Promise<PrunePlan>;
 /**
  * Execute a prune plan: drop each candidate's config entry and wipe its cache
  * dirs. Returns the plan that was applied so the caller can report exactly what
  * went, matching what `--dry-run` printed.
  */
 export declare function pruneProfiles(plan: PrunePlan): Promise<PrunePlan>;
+export {};