@phnx-labs/agents-cli 1.22.93 → 1.22.95

package/dist/lib/browser/firefox-discovery.js

@@ -0,0 +1,162 @@
+/**
+ * Read-only Firefox profile discovery from `profiles.ini` (PHNX-4043).
+ *
+ * One agents-cli profile per `[ProfileN]` entry, named `firefox-<name-slug>`
+ * and pinned to that entry's directory. The profile already carries its
+ * cookies and logins, so it IS the browser profile agents pick with
+ * `--profile` — the same shape Arc Space discovery uses (`arc-discovery.ts`).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Every directory a `profiles.ini` may live in on this machine. Ubuntu's snap
+ * Firefox keeps its whole `.mozilla` under `~/snap/firefox/common/`, a deb or
+ * tarball Firefox uses `~/.mozilla/firefox/` — a box can carry both, so both
+ * are read. `AGENTS_FIREFOX_DIRS` (path-separator list) points tests and
+ * non-default installs elsewhere.
+ */
+export function firefoxProfileRoots() {
+    const override = process.env.AGENTS_FIREFOX_DIRS;
+    if (override)
+        return override.split(path.delimiter).filter(Boolean).map((p) => path.resolve(p));
+    const home = os.homedir();
+    switch (process.platform) {
+        case 'darwin':
+            return [path.join(home, 'Library', 'Application Support', 'Firefox')];
+        case 'win32':
+            return [path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Mozilla', 'Firefox')];
+        default:
+            return [
+                path.join(home, '.mozilla', 'firefox'),
+                path.join(home, 'snap', 'firefox', 'common', '.mozilla', 'firefox'),
+            ];
+    }
+}
+/**
+ * Parse one `profiles.ini`. Only `[Profile<n>]` sections are profiles;
+ * `[General]` and `[Install<hash>]` (which record the per-install default) are
+ * skipped. A `[Profile]` section that lacks `Name` or `Path` is a malformed
+ * file, not a profile to guess at.
+ */
+export function parseProfilesIni(iniPath) {
+    let text;
+    try {
+        text = fs.readFileSync(iniPath, 'utf8');
+    }
+    catch (error) {
+        return { error: `Cannot read ${iniPath}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const root = path.dirname(iniPath);
+    const sections = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith(';') || line.startsWith('#'))
+            continue;
+        const header = line.match(/^\[(.+)\]$/);
+        if (header) {
+            sections.push({ header: header[1], values: {} });
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq === -1 || sections.length === 0) {
+            return { error: `${iniPath} has a malformed line: ${JSON.stringify(raw)}` };
+        }
+        sections[sections.length - 1].values[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+    const profiles = [];
+    for (const section of sections) {
+        if (!/^Profile\d+$/.test(section.header))
+            continue;
+        const name = section.values.Name;
+        const rel = section.values.Path;
+        if (!name || !rel) {
+            return { error: `${iniPath} [${section.header}] has no Name or Path` };
+        }
+        const isRelative = section.values.IsRelative !== '0';
+        const dir = isRelative ? path.resolve(root, rel) : path.resolve(rel);
+        profiles.push({ name, dir, isDefault: section.values.Default === '1', iniPath });
+    }
+    return profiles;
+}
+export function discoverFirefoxProfilesAt(roots) {
+    const iniPaths = roots.map((root) => path.join(root, 'profiles.ini')).filter((p) => fs.existsSync(p));
+    if (iniPaths.length === 0) {
+        return {
+            ok: false,
+            kind: 'not-installed',
+            reason: `No Firefox profiles.ini under ${roots.join(', ')}`,
+        };
+    }
+    const profiles = [];
+    for (const iniPath of iniPaths) {
+        const parsed = parseProfilesIni(iniPath);
+        if ('error' in parsed)
+            return { ok: false, kind: 'invalid', reason: parsed.error };
+        profiles.push(...parsed);
+    }
+    if (profiles.length === 0) {
+        return { ok: false, kind: 'invalid', reason: `No [Profile] entries in ${iniPaths.join(', ')}` };
+    }
+    return { ok: true, profiles, iniPaths };
+}
+export function discoverFirefoxProfiles() {
+    return discoverFirefoxProfilesAt(firefoxProfileRoots());
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** FNV-1a over the path, folded into the range. Stable across runs and daemons. */
+function stableHash(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+/** Firefox BiDi ports live in their own range so they never collide with the 9222-9399 CDP profiles. */
+export const FIREFOX_PORT_RANGE = Object.freeze({ base: 9600, size: 100 });
+/**
+ * The port a discovered Firefox profile listens on: derived from its directory,
+ * so the relaunch hint in an attach error is the same string every time and a
+ * daemon restart reattaches to the Firefox it launched earlier. Collisions
+ * between two discovered profiles resolve by linear probing within the range.
+ */
+export function firefoxProfilePort(profileDir, taken = new Set()) {
+    const { base, size } = FIREFOX_PORT_RANGE;
+    let port = base + (stableHash(profileDir) % size);
+    for (let i = 0; i < size && taken.has(port); i++) {
+        port = base + ((port - base + 1) % size);
+    }
+    return port;
+}
+/**
+ * Flatten discovery into one agents-cli profile per `profiles.ini` entry, named
+ * `firefox-<name>` (`firefox-default`, `firefox-default-release`, …). Two
+ * entries with the same name (one per ini, say) get the first six hex
+ * characters of their directory hash appended so the names stay distinct.
+ */
+export function firefoxDiscoveredProfiles(result) {
+    if (!result.ok)
+        return [];
+    const taken = new Set();
+    const flat = result.profiles.map((profile) => {
+        const port = firefoxProfilePort(profile.dir, taken);
+        taken.add(port);
+        return {
+            name: `firefox-${slugify(profile.name) || 'profile'}`,
+            profileName: profile.name,
+            profileDir: profile.dir,
+            iniPath: profile.iniPath,
+            isDefault: profile.isDefault,
+            port,
+        };
+    });
+    const counts = new Map();
+    for (const entry of flat)
+        counts.set(entry.name, (counts.get(entry.name) ?? 0) + 1);
+    return flat.map((entry) => (counts.get(entry.name) ?? 0) > 1
+        ? { ...entry, name: `${entry.name}-${stableHash(entry.profileDir).toString(16).padStart(8, '0').slice(0, 6)}` }
+        : entry);
+}

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

@@ -85,8 +85,46 @@ export declare function getProfileDownloadsDir(name: string): string;
  * one-shot migration in migrate.ts folds old captures into here.
  */
 export declare function getProfileSessionsDir(name: string, task: string): string;
+/**
+ * Every browser profile this Mac already has, as agents-cli profiles:
+ *
+ * - each Arc Space (PHNX-2399): a Space carries its Arc profile's cookies and
+ *   logins, so it IS the browser profile agents pick with `--profile`;
+ * - each Comet profile from Comet's own `Local State` (PHNX-4042): pinned to
+ *   Comet's user-data dir and profile directory, so the window agents open is
+ *   the owner's window and a sign-in done once serves both.
+ *
+ * No second concept: agents see one `--profile` list. Discovery reads files
+ * the browsers rewrite on every change, so a torn read is an ordinary event,
+ * not corruption. It is reported as `errors` rather than thrown: the profile
+ * store serves every browser on this machine, and a momentary Arc read must
+ * never take the Comet or Chrome rows down with it. An error surfaces where a
+ * profile of that browser is actually asked for by name.
+ */
+export interface DiscoveredProfiles {
+    profiles: BrowserProfileWithDeclarations[];
+    /** Per-browser discovery failures, keyed by the profile-name prefix (`arc`, `comet`). */
+    errors: Record<string, string>;
+}
+export declare function discoverNativeProfiles(): DiscoveredProfiles;
+/**
+ * Publish every discovered native profile that this device has not declared
+ * yet into its device declaration (`~/.agents/devices/<device>/agents.yaml`),
+ * which the fleet shared-store sync carries to every other box (PHNX-4042).
+ * That is what lets `agents browser profiles list` on a worker show this
+ * Mac's `arc-*` and `comet-*` rows with WHERE=<this device>, and a start from
+ * there route here. Idempotent; a discovery error skips that browser.
+ */
+export declare function publishDiscoveredProfiles(): Promise<{
+    published: string[];
+    errors: Record<string, string>;
+}>;
+/** Whether this name has persisted agents-cli metadata on the current device. */
+export declare function isProfileDeclaredHere(name: string): boolean;
 export declare function listProfiles(): Promise<BrowserProfileWithDeclarations[]>;
 export declare function getProfile(name: string): Promise<BrowserProfileWithDeclarations | null>;
+/** Persist only the agents-cli alias for an auto-discovered native profile; never the browser's own data. */
+export declare function persistDiscoveredProfile(name: string): Promise<void>;
 /**
  * True when `profile` can actually launch or attach on THIS machine.
  *
@@ -245,7 +283,7 @@ export declare function updateProfile(profile: BrowserProfile): Promise<void>;
  * ({@link getProfileRuntimeDir}) and any live `<name>@<endpoint>` connection, so
  * changing either orphans the cached browser data. Delete and recreate instead.
  */
-export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'launchPolicy' | 'userDataDir' | 'chrome' | 'secrets' | 'viewport'>>;
+export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'launchPolicy' | 'userDataDir' | 'chrome' | 'secrets' | 'viewport' | 'arc'>>;
 export interface EditProfileResult {
     profile: BrowserProfile;
     devices: string[];

package/dist/lib/browser/profiles.js

@@ -5,6 +5,9 @@ import { getConfigValue } from '../device-config.js';
 import { machineId } from '../machine-id.js';
 import { declaringDevices, profileRegistry, } from './registry.js';
 import { findBrowserPath, isPortInUse } from './chrome.js';
+import { arcSpaceProfiles, discoverArcProfiles } from './arc-discovery.js';
+import { discoverChromiumProfiles, discoverableChromiumBrowsers } from './chromium-discovery.js';
+import { firefoxDiscoveredProfiles, discoverFirefoxProfiles } from './firefox-discovery.js';
 export { declaringDevices, profileKind, profileRegistry, } from './registry.js';
 /**
  * Name of the profile the setup wizards pin as this machine's default browser
@@ -124,11 +127,14 @@ function configToProfile(name, config, devices = []) {
         defaultEndpoint: config.defaultEndpoint,
         launchPolicy: config.launchPolicy,
         userDataDir: config.userDataDir,
+        profileDirectory: config.profileDirectory,
         chrome: config.chrome,
         secrets: config.secrets,
         viewport: config.viewport,
         logDir: config.logDir,
         logHost: config.logHost,
+        arc: config.arc,
+        firefox: config.firefox,
         devices,
     };
 }
@@ -152,6 +158,8 @@ function profileToConfig(profile) {
         config.launchPolicy = profile.launchPolicy;
     if (profile.userDataDir)
         config.userDataDir = profile.userDataDir;
+    if (profile.profileDirectory)
+        config.profileDirectory = profile.profileDirectory;
     if (profile.chrome)
         config.chrome = profile.chrome;
     if (profile.secrets)
@@ -162,26 +170,214 @@ function profileToConfig(profile) {
         config.logDir = profile.logDir;
     if (profile.logHost)
         config.logHost = profile.logHost;
+    if (profile.arc)
+        config.arc = profile.arc;
+    if (profile.firefox)
+        config.firefox = profile.firefox;
     return config;
 }
+export function discoverNativeProfiles() {
+    const profiles = [];
+    const errors = {};
+    const arc = discoverArcProfiles();
+    if (arc.ok) {
+        for (const space of arcSpaceProfiles(arc)) {
+            profiles.push({
+                name: space.name,
+                description: `Arc Space "${space.spaceTitle}" (${space.profileName})`,
+                browser: 'arc',
+                endpoints: { native: { target: 'arc-native://local' } },
+                defaultEndpoint: 'native',
+                launchPolicy: 'attach-only',
+                arc: {
+                    profileId: space.profileId,
+                    profileName: space.profileName,
+                    spaceId: space.spaceId,
+                    spaceTitle: space.spaceTitle,
+                },
+                devices: [machineId()],
+            });
+        }
+    }
+    else if (arc.kind === 'invalid') {
+        errors.arc = `Cannot discover Arc Spaces: ${arc.reason}`;
+    }
+    // Ports handed out earlier in this pass: two unpublished profiles must never
+    // derive the same port before either is declared.
+    const reserved = new Set();
+    for (const browser of discoverableChromiumBrowsers()) {
+        const found = discoverChromiumProfiles(browser);
+        if (!found.ok) {
+            if (found.kind === 'invalid')
+                errors[browser] = `Cannot discover ${browser} profiles: ${found.reason}`;
+            continue;
+        }
+        for (const native of found.profiles) {
+            const port = nativeChromiumPort(native.name, reserved);
+            reserved.add(port);
+            profiles.push({
+                name: native.name,
+                description: `${browser} profile "${native.displayName}" (${native.profileDirectory})`,
+                browser,
+                endpoints: [`cdp://127.0.0.1:${port}`],
+                userDataDir: native.userDataDir,
+                profileDirectory: native.profileDirectory,
+                devices: [machineId()],
+            });
+        }
+    }
+    // Firefox (PHNX-4043): one profiles.ini entry is one `firefox-<slug>` profile,
+    // pinned to that directory and a stable WebDriver BiDi port. Firefox dropped
+    // CDP in 129, so these use a `firefox-bidi:` endpoint, not `cdp://`.
+    const firefox = discoverFirefoxProfiles();
+    if (firefox.ok) {
+        for (const entry of firefoxDiscoveredProfiles(firefox)) {
+            profiles.push({
+                name: entry.name,
+                description: `Firefox profile "${entry.profileName}"${entry.isDefault ? ' (default)' : ''}`,
+                browser: 'firefox',
+                endpoints: { bidi: { target: `firefox-bidi://127.0.0.1:${entry.port}` } },
+                defaultEndpoint: 'bidi',
+                userDataDir: entry.profileDir,
+                firefox: {
+                    profileName: entry.profileName,
+                    iniPath: entry.iniPath,
+                    isDefault: entry.isDefault,
+                },
+                devices: [machineId()],
+            });
+        }
+    }
+    else if (firefox.kind === 'invalid') {
+        errors.firefox = `Cannot discover Firefox profiles: ${firefox.reason}`;
+    }
+    return { profiles, errors };
+}
+/**
+ * The CDP port a discovered Chromium profile attaches on. Once the profile is
+ * declared its port lives in the declaration; before that, the port is the
+ * first free one from the canonical Comet port (9333, PHNX-3967), stepping
+ * past ports other local declarations hold and past `reserved`, the ports
+ * already given to sibling profiles in the same discovery pass.
+ */
+function nativeChromiumPort(name, reserved) {
+    const declared = localDeclaration(name)?.config;
+    const declaredPort = declared ? parseEndpointPort(declared) : undefined;
+    if (declaredPort)
+        return declaredPort;
+    const taken = new Set(reserved);
+    for (const [other, declarations] of profileRegistry()) {
+        if (other === name)
+            continue;
+        for (const declaration of declarations) {
+            if (declaration.device !== machineId())
+                continue;
+            const port = parseEndpointPort(declaration.config);
+            if (port)
+                taken.add(port);
+        }
+    }
+    let port = 9333;
+    while (taken.has(port))
+        port += 1;
+    return port;
+}
+function parseEndpointPort(config) {
+    const endpoints = config.endpoints;
+    const first = Array.isArray(endpoints)
+        ? endpoints[0]
+        : endpoints && typeof endpoints === 'object'
+            ? Object.values(endpoints)[0]?.target
+            : undefined;
+    if (typeof first !== 'string')
+        return undefined;
+    const match = /^cdp:\/\/[^:/?]+(?::(\d+)|\?port=(\d+))/.exec(first);
+    const raw = match?.[1] ?? match?.[2];
+    return raw ? Number(raw) : undefined;
+}
+/**
+ * Publish every discovered native profile that this device has not declared
+ * yet into its device declaration (`~/.agents/devices/<device>/agents.yaml`),
+ * which the fleet shared-store sync carries to every other box (PHNX-4042).
+ * That is what lets `agents browser profiles list` on a worker show this
+ * Mac's `arc-*` and `comet-*` rows with WHERE=<this device>, and a start from
+ * there route here. Idempotent; a discovery error skips that browser.
+ */
+export async function publishDiscoveredProfiles() {
+    const discovered = discoverNativeProfiles();
+    const published = [];
+    for (const profile of discovered.profiles) {
+        if (localDeclaration(profile.name))
+            continue;
+        await createProfile(profile);
+        published.push(profile.name);
+    }
+    return { published, errors: discovered.errors };
+}
+/**
+ * Bring a persisted discovered profile up to date with its live source (an Arc
+ * Space title rename, a Comet profile rename). A source that is no longer
+ * discoverable leaves the declaration as stored: listing still works, and using
+ * the profile fails loud where the browser is actually reached.
+ */
+function refreshDiscoveredProfile(profile, live) {
+    if (!profile.devices.includes(machineId()))
+        return profile;
+    if (profile.arc) {
+        const current = live.find((candidate) => candidate.arc?.spaceId === profile.arc?.spaceId);
+        if (!current)
+            return profile;
+        return { ...profile, arc: current.arc, description: profile.description ?? current.description };
+    }
+    if (profile.userDataDir && profile.profileDirectory) {
+        const current = live.find((candidate) => candidate.userDataDir === profile.userDataDir && candidate.profileDirectory === profile.profileDirectory);
+        if (!current)
+            return profile;
+        return { ...profile, description: profile.description ?? current.description };
+    }
+    return profile;
+}
 function selectedDeclaration(declarations) {
     return declarations.find((declaration) => declaration.device === machineId()) ?? declarations[0];
 }
 function localDeclaration(name) {
     return profileRegistry().get(name)?.find((declaration) => declaration.device === machineId());
 }
+/** Whether this name has persisted agents-cli metadata on the current device. */
+export function isProfileDeclaredHere(name) {
+    return localDeclaration(name) !== undefined;
+}
 export async function listProfiles() {
-    return [...profileRegistry()].map(([name, declarations]) => {
+    const native = discoverNativeProfiles();
+    const configured = [...profileRegistry()].map(([name, declarations]) => {
         const selected = selectedDeclaration(declarations);
-        return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
+        return refreshDiscoveredProfile(configToProfile(name, selected.config, declarations.map((declaration) => declaration.device)), native.profiles);
     });
+    const names = new Set(configured.map((profile) => profile.name));
+    return [...configured, ...native.profiles.filter((profile) => !names.has(profile.name))];
 }
 export async function getProfile(name) {
+    const native = discoverNativeProfiles();
     const declarations = profileRegistry().get(name);
-    if (!declarations?.length)
-        return null;
-    const selected = selectedDeclaration(declarations);
-    return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
+    if (declarations?.length) {
+        const selected = selectedDeclaration(declarations);
+        return refreshDiscoveredProfile(configToProfile(name, selected.config, declarations.map((declaration) => declaration.device)), native.profiles);
+    }
+    const discovered = native.profiles.find((profile) => profile.name === name) ?? null;
+    // Only a profile of that browser asked for by name pays for its failed read.
+    const prefix = name.split('-')[0];
+    if (!discovered && native.errors[prefix])
+        throw new Error(native.errors[prefix]);
+    return discovered;
+}
+/** Persist only the agents-cli alias for an auto-discovered native profile; never the browser's own data. */
+export async function persistDiscoveredProfile(name) {
+    if (localDeclaration(name))
+        return;
+    const profile = discoverNativeProfiles().profiles.find((candidate) => candidate.name === name);
+    if (!profile)
+        return;
+    await createProfile(profile);
 }
 /**
  * True when `profile` can actually launch or attach on THIS machine.
@@ -194,6 +390,25 @@ export async function getProfile(name) {
  * for the current machine.
  */
 export function isProfileLaunchableHere(profile) {
+    const nativeArc = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (nativeArc) {
+        return !!profile.arc && discoverNativeProfiles().profiles.some((candidate) => candidate.arc?.spaceId === profile.arc?.spaceId);
+    }
+    const bidi = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('firefox-bidi:'));
+    if (bidi) {
+        // Launchable here only when Firefox is installed AND this box holds the
+        // pinned profile directory (a synced-in firefox- profile from another box
+        // has that box's path, so it command-dispatches instead).
+        if (!profile.userDataDir || !fs.existsSync(profile.userDataDir))
+            return false;
+        try {
+            findBrowserPath('firefox', profile.binary);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     const remote = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('ssh://'));
     if (remote)
         return true;
@@ -334,7 +549,7 @@ export async function ensureDefaultBrowserProfile() {
     const configured = getConfiguredDefaultProfileName();
     if (configured && configured !== DEFAULT_PROFILE_ALIAS) {
         const chosen = await getProfile(configured);
-        if (chosen && isProfileLaunchableHere(chosen))
+        if (chosen && (!chosen.devices.includes(machineId()) || isProfileLaunchableHere(chosen)))
             return chosen;
         if (!chosen) {
             const central = readMeta().browser ?? {};
@@ -520,7 +735,21 @@ export async function createProfile(profile) {
     // Skip for SSH profiles: the browser binary lives on the remote host, so a
     // local lookup would validate the wrong machine. The remote launcher resolves
     // it at connect time.
-    if (!hasSshEndpoint(profile.endpoints)) {
+    const nativeArc = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (nativeArc && (!profile.arc || profile.browser !== 'arc')) {
+        throw new Error('An arc-native profile requires stable Arc Space metadata. Pick a discovered one from `agents browser profiles list`.');
+    }
+    const firefoxBidi = Object.values(getEndpointPresets(profile)).some((preset) => preset.target.startsWith('firefox-bidi:'));
+    if (firefoxBidi && (!profile.firefox || profile.browser !== 'firefox')) {
+        throw new Error('A firefox-bidi profile requires a discovered Firefox profile. Pick one from `agents browser profiles list`.');
+    }
+    // A discovered profile is pinned to a browser store on this disk
+    // (`userDataDir` + `profileDirectory`) and is published unattended by the
+    // daemon tick. Its binary is resolved where it is launched (`launchBrowser`),
+    // so an app that was removed after its store fails loud at `start` instead of
+    // blocking every other discovered row from publishing.
+    const storePinned = !!profile.userDataDir && !!profile.profileDirectory;
+    if (!hasSshEndpoint(profile.endpoints) && !nativeArc && !storePinned) {
         findBrowserPath(profile.browser, profile.binary);
     }
     const config = profileToConfig(profile);
@@ -575,7 +804,8 @@ export async function editProfile(name, patch) {
     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)) {
+    const nativeArc = Object.values(getEndpointPresets(merged)).some((preset) => preset.target.startsWith('arc-native:'));
+    if (!hasSshEndpoint(merged.endpoints) && !nativeArc) {
         findBrowserPath(merged.browser, merged.binary);
     }
     await updateProfile(merged);

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

@@ -10,6 +10,8 @@ export interface RefNode {
     name: string;
     attrs: string[];
     backendNodeId?: number;
+    /** Stable selector used by non-CDP DOM backends such as native Arc. */
+    selector?: string;
     editor?: string;
 }
 /**

package/dist/lib/browser/refs.js

@@ -6,6 +6,7 @@ export function describeRefs(nodeMap) {
         role: n.role,
         name: n.name,
         attrs: n.attrs.slice(),
+        selector: n.selector,
     }));
 }
 /**
@@ -57,7 +58,7 @@ export function healRef(descriptor, freshNodeMap) {
         // Lexicographic key, all "higher is better":
         //   [ DOM-backed, attribute similarity, -distance-to-original-ref ].
         const key = [
-            node.backendNodeId !== undefined ? 1 : 0,
+            node.backendNodeId !== undefined || node.selector !== undefined ? 1 : 0,
             attrScore(node),
             -Math.abs(node.ref - ref),
         ];

package/dist/lib/browser/resolve-target.d.ts

@@ -24,6 +24,8 @@ export interface ResolvedBrowserTarget {
      * surfaces this so the caller knows WHERE the browser actually lives.
      */
     picked?: string;
+    /** Native endpoints cannot be tunnelled; the CLI must re-exec on this device. */
+    commandDispatch?: boolean;
 }
 /** Fork only fungible Electron profiles; identity-bearing ones share one connection. */
 export declare function shouldForkProfile(kind: 'identity' | 'fungible', conn: {

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

@@ -35,11 +35,15 @@ export function profileFromDeclaration(name, declaration) {
         targetFilter: config.targetFilter,
         endpoints: config.endpoints,
         defaultEndpoint: config.defaultEndpoint,
+        launchPolicy: config.launchPolicy,
+        userDataDir: config.userDataDir,
         chrome: config.chrome,
         secrets: config.secrets,
         viewport: config.viewport,
         logDir: config.logDir,
         logHost: config.logHost,
+        arc: config.arc,
+        firefox: config.firefox,
     };
 }
 /** Runtime key: profile name plus the resolved device. Drops `@endpoint-N`. */
@@ -125,6 +129,15 @@ export function sshEndpointForDeclaration(device, config, endpointName, os) {
     const resolved = resolveEndpoint(profile, endpointName);
     if (resolved.target.startsWith('ssh:'))
         return resolved.target;
+    // Native Arc endpoints (arc-native:) must NOT be rewritten into SSH tunnels
+    // (PHNX-2399). They dispatch the whole command to the owner device instead.
+    if (resolved.target.startsWith('arc-native:'))
+        return resolved.target;
+    // Firefox BiDi endpoints (firefox-bidi:) are a local WebSocket bound to a
+    // specific profile directory on the owner box; they dispatch the whole
+    // command to that box rather than tunnelling (PHNX-4043).
+    if (resolved.target.startsWith('firefox-bidi:'))
+        return resolved.target;
     const parsed = parseEndpointUrl(resolved.target);
     const port = parsed?.port ?? 9222;
     const osQuery = isWindowsOs(os) ? '&os=windows' : '';
@@ -202,6 +215,7 @@ export function resolveBrowserTarget(name, opts = {}) {
                 targetFilter: resolved.targetFilter,
             },
             picked,
+            commandDispatch: resolved.target.startsWith('arc-native:') || resolved.target.startsWith('firefox-bidi:'),
         };
     }
     throw unreachableDeclaringDevicesError(name, devices, failures);

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, getEndpointPresets, listProfiles, getConfiguredDefaultProfileName, isProfileLaunchableHere, deleteProfile, DEFAULT_BROWSER_PROFILE_NAME, LEGACY_DEFAULT_BROWSER_PROFILE_NAME, } from './profiles.js';
+import { getProfileRuntimeDir, getBrowserRuntimeDir, getEndpointPresets, listProfiles, getConfiguredDefaultProfileName, isProfileLaunchableHere, isProfileDeclaredHere, deleteProfile, DEFAULT_BROWSER_PROFILE_NAME, LEGACY_DEFAULT_BROWSER_PROFILE_NAME, } from './profiles.js';
 import { keyBelongsToProfile } from './types.js';
 import { declaringDevices, profileKind } from './registry.js';
 import { machineId } from '../machine-id.js';
@@ -405,6 +405,14 @@ export async function buildProfilePrunePlan() {
     for (const profile of profiles) {
         const scope = profile.devices.length > 1 ? 'fungible' : 'identity';
         const misfiled = identityLoopbackMismatch(profile);
+        if (profile.arc && !isProfileDeclaredHere(profile.name)) {
+            peerKept.push({
+                name: profile.name,
+                scope,
+                why: 'read-only native Arc discovery; no agents-cli alias to prune',
+            });
+            continue;
+        }
         if (profile.devices.includes(current)) {
             declaredHere.push({
                 name: profile.name,