@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/browser/profiles.js

@@ -1,8 +1,12 @@
 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 { machineId } from '../machine-id.js';
+import { declaringDevices, profileRegistry, } from './registry.js';
 import { findBrowserPath, findFirstInstalledBrowser, isPortInUse } from './chrome.js';
 import { DEFAULT_VIEWPORT } from './devices.js';
+export { declaringDevices, profileKind, profileRegistry, } from './registry.js';
 /**
  * Name of the profile `ensureDefaultBrowserProfile` auto-detects and pins.
  *
@@ -28,25 +32,6 @@ export const LEGACY_DEFAULT_BROWSER_PROFILE_NAME = 'default';
  * wins, so no existing config breaks.
  */
 export const DEFAULT_PROFILE_ALIAS = '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.
- *
- * 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`.
- *
- * 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 || name === LEGACY_DEFAULT_BROWSER_PROFILE_NAME;
-}
 /**
  * The device-local configured default profile name (set via
  * `agents browser use`), or undefined when unset. When set, it
@@ -81,7 +66,7 @@ export function getProfileDownloadsDir(name) {
 export function getProfileSessionsDir(name, task) {
     return path.join(getProfileRuntimeDir(name), 'sessions', task);
 }
-function configToProfile(name, config) {
+function configToProfile(name, config, devices = []) {
     validateRemoteBrowserBinaries(config);
     return {
         name,
@@ -97,6 +82,7 @@ function configToProfile(name, config) {
         viewport: config.viewport,
         logDir: config.logDir,
         logHost: config.logHost,
+        devices,
     };
 }
 function profileToConfig(profile) {
@@ -127,38 +113,24 @@ function profileToConfig(profile) {
         config.logHost = profile.logHost;
     return config;
 }
-/**
- * Every profile visible on this machine: the fleet-shared ones plus this
- * machine's own. A machine-local entry WINS on a name collision — it was written
- * by this box for this box, whereas the shared copy may carry another OS's
- * binary path (that mismatch is exactly why `default` moved local).
- */
-function allProfileConfigs() {
-    const meta = readMeta();
-    return { ...meta.browser, ...meta.deviceBrowser };
+function selectedDeclaration(declarations) {
+    return declarations.find((declaration) => declaration.device === machineId()) ?? declarations[0];
 }
-export async function listProfiles() {
-    const configs = allProfileConfigs();
-    return Object.entries(configs).map(([name, config]) => configToProfile(name, config));
+function localDeclaration(name) {
+    return profileRegistry().get(name)?.find((declaration) => declaration.device === machineId());
 }
-/**
- * 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 listProfiles() {
+    return [...profileRegistry()].map(([name, declarations]) => {
+        const selected = selectedDeclaration(declarations);
+        return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
+    });
 }
 export async function getProfile(name) {
-    const config = allProfileConfigs()[name];
-    if (!config)
+    const declarations = profileRegistry().get(name);
+    if (!declarations?.length)
         return null;
-    return configToProfile(name, config);
+    const selected = selectedDeclaration(declarations);
+    return configToProfile(name, selected.config, declarations.map((declaration) => declaration.device));
 }
 /**
  * True when `profile` can actually launch or attach on THIS machine.
@@ -182,26 +154,6 @@ export function isProfileLaunchableHere(profile) {
         return false;
     }
 }
-/**
- * Resolve the profile `agents browser start` uses when no `--profile` is given.
- *
- * Order: (1) the device-local configured default (`agents browser profiles
- * 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 > 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.
- *
- * "Can launch here" matters because `agents.yaml` syncs across the fleet: a
- * `default` auto-created on macOS carries a `/Applications/...` binary path that
- * doesn't exist on a Linux box. Rather than hand that broken profile back (the
- * top browser roadblock — "Custom binary not found"), we re-detect and
- * regenerate the `default` for this machine. A configured or existing default
- * that no longer exists, or can't launch here, warns and falls through — never a
- * hard fail.
- */
 /**
  * The auto-detected profile this machine already carries, under either name —
  * the current `auto-chrome` or the `default` an older build wrote. Callers that
@@ -209,8 +161,14 @@ export function isProfileLaunchableHere(profile) {
  * name, or a machine that predates the RUSH-2709 rename grows a second one.
  */
 export async function getAutoDetectedProfile() {
-    return ((await getProfile(DEFAULT_BROWSER_PROFILE_NAME)) ??
-        (await getProfile(LEGACY_DEFAULT_BROWSER_PROFILE_NAME)));
+    const current = machineId();
+    const registry = profileRegistry();
+    for (const name of [DEFAULT_BROWSER_PROFILE_NAME, LEGACY_DEFAULT_BROWSER_PROFILE_NAME]) {
+        const declaration = registry.get(name)?.find((entry) => entry.device === current);
+        if (declaration)
+            return configToProfile(name, declaration.config, [current]);
+    }
+    return null;
 }
 /**
  * Resolve what a caller typed after `--profile` to a real, BARE profile name.
@@ -261,15 +219,16 @@ export async function resolveProfileRef(ref) {
  * `start`'s resolver. Same order as {@link resolveProfileRef} for an explicit
  * name, but the IMPLICIT path (no `--profile`, or the bare `default` alias with
  * no profile of that name) goes through {@link ensureDefaultBrowserProfile} —
- * which additionally verifies the resolved default can launch on THIS machine,
- * warns and falls through when it can't, and regenerates or creates one.
+ * which additionally verifies the resolved default can launch on THIS machine.
+ * An undeclared configured default is an error. A declared default whose
+ * browser isn't installed here warns and falls through to auto-detect.
  *
  * `start` is the only command that launches a browser, so it is the only one
  * that may do those things; routing a filter-only command through this would
  * warn about, and rewrite, config the user never asked it to touch.
  *
- * Throws when no profile exists and no supported browser is installed —
- * `ensureDefaultBrowserProfile`'s actionable "install one of …" error.
+ * Throws when the configured default is undeclared, or when no profile exists
+ * and no supported browser is installed.
  */
 export async function resolveProfileRefForStart(ref) {
     if (ref && ref !== DEFAULT_PROFILE_ALIAS)
@@ -279,25 +238,51 @@ export async function resolveProfileRefForStart(ref) {
         return ref;
     return (await ensureDefaultBrowserProfile()).name;
 }
+/**
+ * Resolve the profile a bare `agents browser start` uses.
+ *
+ * Order: (1) the device-local configured default (`agents browser use <name>`)
+ * when it names a profile that exists and can launch here; (2) an existing
+ * auto-detected profile that can launch here; (3) auto-pick the first installed
+ * Chromium-family browser and pin `auto-chrome` (or repair a stale legacy
+ * `default`) to it.
+ *
+ * Two failure modes at the configured-default step are not the same:
+ *   - No device declares the name (including a leftover central `browser:`
+ *     entry that was never claimed) → throw. Auto-creating `auto-chrome` would
+ *     hand the agent a logged-out browser while `browser.profile` still names
+ *     the credentialed one.
+ *   - The name is declared, but its browser/binary is not installed HERE →
+ *     warn and fall through. That is a missing binary on this box, not a
+ *     missing identity; auto-detect is the existing repair.
+ */
 export async function ensureDefaultBrowserProfile() {
     const configured = getConfiguredDefaultProfileName();
     if (configured && configured !== DEFAULT_PROFILE_ALIAS) {
         const chosen = await getProfile(configured);
         if (chosen && isProfileLaunchableHere(chosen))
             return chosen;
-        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 use <name>  (or --unset)`
-            : `warning: configured default browser profile "${configured}" no longer exists; ` +
-                `falling back to auto-detect. Fix with: agents browser use <name>  (or --unset)`);
+        if (!chosen) {
+            const central = readMeta().browser ?? {};
+            if (central[configured]) {
+                throw new Error(`configured default browser profile "${configured}" 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 ${configured}`);
+            }
+            throw new Error(`configured default browser profile "${configured}" is not declared by any device. ` +
+                `Create it with: agents browser profiles create ${configured} --browser <chrome|comet|chromium|brave|edge|arc|custom> ` +
+                `(or, if it is a leftover central profile, claim it with: agents browser profiles claim ${configured}). ` +
+                `Or unset the default with: agents browser use --unset`);
+        }
+        console.warn(`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 use <name>  (or --unset)`);
     }
     // Prefer whichever auto-detected profile this machine already carries: the
     // current `auto-chrome`, else the `default` an older build wrote. Reusing the
     // legacy one is what keeps a currently-running browser (and its runtime dirs,
     // keyed `default@endpoint-0`) attached after the rename.
-    const existing = (await getProfile(DEFAULT_BROWSER_PROFILE_NAME)) ??
-        (await getProfile(LEGACY_DEFAULT_BROWSER_PROFILE_NAME));
+    const existing = await getAutoDetectedProfile();
     if (existing && isProfileLaunchableHere(existing))
         return existing;
     const detected = findFirstInstalledBrowser();
@@ -420,45 +405,40 @@ function hasSshEndpoint(endpoints) {
     });
 }
 /**
- * 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.
+ * Refuse a profile whose LOCAL port another profile already owns.
  *
- * 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.
+ * 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.
  *
- * Existing profiles are NOT migrated: this only decides where a NEW entry is
- * written, so a fleet profile created before this change keeps syncing.
+ * `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 async function createProfile(profile, opts = {}) {
-    const meta = readMeta();
-    const existingConfigs = allProfileConfigs();
-    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.`);
-            }
+export function assertLocalPortFree(profile, opts = {}) {
+    const wanted = effectiveLocalPort(profile);
+    if (wanted === undefined)
+        return;
+    for (const [existingName, declarations] of profileRegistry()) {
+        if (existingName === opts.ignore)
+            continue;
+        const declaration = declarations.find((entry) => entry.device === machineId());
+        if (!declaration)
+            continue;
+        const existingProfile = configToProfile(existingName, declaration.config, [machineId()]);
+        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.`);
         }
     }
+}
+/** Declare a profile on this device. The same name may be declared by peers. */
+export async function createProfile(profile) {
+    if (localDeclaration(profile.name)) {
+        throw new Error(`Profile "${profile.name}" already exists on ${machineId()}`);
+    }
+    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
@@ -471,46 +451,188 @@ export async function createProfile(profile, opts = {}) {
         findBrowserPath(profile.browser, profile.binary);
     }
     const config = profileToConfig(profile);
-    // 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;
-    }
-    updateMeta((m) => ({ ...m, browser: { ...m.browser, [profile.name]: config } }));
+    updateMeta((meta) => ({
+        ...meta,
+        deviceBrowser: { ...meta.deviceBrowser, [profile.name]: config },
+    }));
 }
 export async function updateProfile(profile) {
-    const meta = readMeta();
-    const local = meta.deviceBrowser?.[profile.name];
-    if (!local && !meta.browser?.[profile.name]) {
-        throw new Error(`Profile "${profile.name}" does not exist`);
+    const local = localDeclaration(profile.name);
+    if (!local) {
+        const devices = declaringDevices(profile.name);
+        const where = devices.length > 0 ? `; declared on ${devices.join(', ')}` : '';
+        throw new Error(`Profile "${profile.name}" is not declared on ${machineId()}${where}`);
     }
     const config = profileToConfig(profile);
-    // A profile that already lives machine-locally stays there; so does the auto
-    // `default`, whose binary path and port are specific to this machine.
-    if (local || isMachineLocalProfile(profile.name)) {
-        updateMeta((m) => ({ ...m, deviceBrowser: { ...m.deviceBrowser, [profile.name]: config } }));
-        return;
+    updateMeta((meta) => ({
+        ...meta,
+        deviceBrowser: { ...meta.deviceBrowser, [profile.name]: config },
+    }));
+}
+/**
+ * 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 local = localDeclaration(name);
+    if (!local) {
+        const devices = declaringDevices(name);
+        const where = devices.length > 0 ? `; declared on ${devices.join(', ')}` : '';
+        throw new Error(`Profile "${name}" is not declared on ${machineId()}${where}`);
+    }
+    const devices = declaringDevices(name);
+    const current = configToProfile(name, local.config, devices);
+    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);
+    return {
+        profile: merged,
+        devices,
+        changed,
+    };
+}
+/** 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.`);
     }
-    updateMeta((m) => ({ ...m, browser: { ...m.browser, [profile.name]: config } }));
 }
-export async function deleteProfile(name) {
-    const meta = readMeta();
-    const isLocal = !!meta.deviceBrowser?.[name];
-    if (!isLocal && !meta.browser?.[name]) {
-        throw new Error(`Profile "${name}" does not exist`);
-    }
-    updateMeta((m) => {
-        if (isLocal) {
-            const next = { ...m.deviceBrowser };
-            delete next[name];
-            return { ...m, deviceBrowser: Object.keys(next).length > 0 ? next : undefined };
+/**
+ * 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 local = localDeclaration(from);
+    if (!local) {
+        const devices = declaringDevices(from);
+        const where = devices.length > 0 ? `; declared on ${devices.join(', ')}` : '';
+        throw new Error(`Profile "${from}" is not declared on ${machineId()}${where}`);
+    }
+    if (profileRegistry().has(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}`);
+    }
+    const config = local.config;
+    const devices = declaringDevices(from);
+    // 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.`);
         }
-        const next = { ...m.browser };
+        plan.push({ dir, dest });
+    }
+    const movedDirs = [];
+    for (const { dir, dest } of plan) {
+        fs.renameSync(dir, dest);
+        movedDirs.push(dest);
+    }
+    updateMeta((meta) => {
+        const next = { ...meta.deviceBrowser };
+        delete next[from];
+        return { ...meta, deviceBrowser: { ...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 rename changes only this device's declaration. If it was the only
+    // declaration, peer pins become stale and are reported rather than rewritten.
+    const { devicesPinningBrowserProfile } = await import('../device-config.js');
+    const stalePins = devices.length === 1
+        ? devicesPinningBrowserProfile(from).filter((p) => p.device !== machineId())
+        : [];
+    return { devices, movedDirs, repointedDefault, repointedViewer, stalePins };
+}
+export async function deleteProfile(name) {
+    if (!localDeclaration(name)) {
+        const devices = declaringDevices(name);
+        const where = devices.length > 0 ? `; declared on ${devices.join(', ')}` : '';
+        throw new Error(`Profile "${name}" is not declared on ${machineId()}${where}`);
+    }
+    updateMeta((meta) => {
+        const next = { ...meta.deviceBrowser };
         delete next[name];
-        return { ...m, browser: Object.keys(next).length > 0 ? next : undefined };
+        return { ...meta, deviceBrowser: Object.keys(next).length > 0 ? next : undefined };
     });
 }
 /** Widest NAME column we will grow to before truncating instead. */
@@ -545,13 +667,10 @@ export function padColumn(text, width) {
  * 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.
+ * WHERE lists the devices whose own files declare the name.
  */
 export function formatProfilesTable(rows, configuredDefault) {
-    const cells = rows.map(({ profile, scope }) => {
+    const cells = rows.map((profile) => {
         const presets = getEndpointPresets(profile);
         const endpoints = Object.entries(presets)
             .map(([name, ep]) => (name.startsWith('endpoint-') ? ep.target : `${name}=${ep.target}`))
@@ -560,42 +679,35 @@ export function formatProfilesTable(rows, configuredDefault) {
             marker: profile.name === configuredDefault ? '*' : ' ',
             name: profile.name,
             browser: profile.browser || '-',
-            scope,
+            where: profile.devices.join(', '),
             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 whereWidth = Math.min(36, Math.max('WHERE'.length, ...cells.map((c) => c.where.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} ` +
+    const row = (marker, name, browser, where, desc, endpoints) => `${marker} ` +
         padColumn(name, nameWidth) + '  ' +
         padColumn(browser, browserWidth) + '  ' +
-        padColumn(scope, scopeWidth) + '  ' +
+        padColumn(where, whereWidth) + '  ' +
         (hasDescriptions ? padColumn(desc, descWidth) + '  ' : '') +
         endpoints;
-    const header = row(' ', 'NAME', 'BROWSER', 'SCOPE', 'DESCRIPTION', 'ENDPOINTS');
+    const header = row(' ', 'NAME', 'BROWSER', 'WHERE', '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));
+        lines.push(row(c.marker, c.name, c.browser, c.where, 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/registry.d.ts

@@ -0,0 +1,39 @@
+import type { BrowserProfileConfig } from '../types.js';
+export interface ProfileDeclaration {
+    device: string;
+    config: BrowserProfileConfig;
+}
+/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+export declare function centralBrowserProfiles(): Record<string, BrowserProfileConfig>;
+export interface CentralClaimResult {
+    claimed: string[];
+    skipped: string[];
+}
+/**
+ * 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 declare function migrateCentralBrowserProfiles(canHostHere: (config: BrowserProfileConfig) => boolean, name?: string): CentralClaimResult;
+/**
+ * Every profile any device declares, keyed by name to all declaring devices.
+ * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.
+ */
+export declare function profileRegistry(): Map<string, ProfileDeclaration[]>;
+/** Devices declaring `name`, empty when nobody does. */
+export declare function declaringDevices(name: string): string[];
+/** Exactly one declaring device is identity-bearing; several are fungible. */
+export declare function profileKind(name: string): 'identity' | 'fungible' | null;