@mehmoodqureshi/chrome-mcp 0.9.4 → 0.9.6

package/dist/src/bridge/server.d.ts

@@ -7,10 +7,25 @@
  *   1. Accept any loopback upgrade.
  *   2. Require a valid `hello` (matching version + token) within HELLO_TIMEOUT;
  *      otherwise send `unauthorized` and close 4401.
- *   3. On success, send `welcome`, promote to the single ACTIVE connection
- *      (superseding any prior one — a security-relevant displacement event).
+ *   3. On success, send `welcome` and file the connection under its profile
+ *      (superseding only that profile's prior one — a security-relevant
+ *      displacement event).
+ * Other chrome-mcp servers (one per Claude session) may join the same port as
+ * peers with `peer_hello` and relay their commands through us; see ./peer.
  */
 import { type WireEvent, type WireMethod, type WirePolicy } from '../../shared/protocol';
+/** Where a live connection's profile name came from. */
+export type ProfileNaming = 'options' | 'auto' | 'legacy';
+/** One paired browser, as reported by chrome_status. */
+export interface PairedProfile {
+    name: string;
+    /** options = typed in the extension's Options; auto = assigned by the server
+     *  (renamable with profile_rename); legacy = an older extension, "default". */
+    naming: ProfileNaming;
+    /** The browser's active tab when it last reported one — a hint for telling
+     *  auto-named browsers apart. */
+    activeUrl?: string;
+}
 export interface DisplacementInfo {
     oldExtId: string;
     newExtId: string;
@@ -33,7 +48,19 @@ export interface BridgeOptions {
     onLog?: (message: string) => void;
     onDisplacement?: (info: DisplacementInfo) => void;
     onEvent?: (event: WireEvent, data: Record<string, unknown>) => void;
+    /**
+     * Called whenever this server takes a role on the port: 'hub' when it binds
+     * it (publish the handshake + pairing files then), 'peer' when it joins the
+     * chrome-mcp already holding it. Fires again after a failover.
+     */
+    onRole?: (role: BridgeRole, info: {
+        port: number;
+        token: string;
+        hubPid?: number;
+    }) => void;
 }
+/** hub = owns the port and the browser connections; peer = relays through the hub. */
+export type BridgeRole = 'hub' | 'peer';
 export declare class BridgeServer {
     private readonly opts;
     private wss;
@@ -41,11 +68,41 @@ export declare class BridgeServer {
      *  once; a command is routed to the connection for its target profile. A new
      *  hello for the SAME profile supersedes that profile's connection only. */
     private conns;
+    /** Profile routing key → how that live connection got its name, and the
+     *  install behind it (absent for extensions too old to send one). */
+    private origins;
+    /** Remembers which name each extension install was given. */
+    private registry;
     private boundPort;
     private readonly heartbeatMs;
+    /** The pairing secret. Starts as ours; a peer adopts the hub's, so if it
+     *  later takes the port over the extension re-pairs without a new token. */
+    private token;
+    /** Peer role: the link to the hub that owns the browsers. */
+    private hub;
+    /** Hub role: the other chrome-mcp servers relaying through us. */
+    private readonly peers;
+    private stopped;
     constructor(opts: BridgeOptions);
-    /** Bind and start listening. Returns the actual port (useful with port 0). */
+    /** 'hub' or 'peer' once started; null before start and between roles. */
+    get role(): BridgeRole | null;
+    /**
+     * Bind and start listening, or — when a pinned port is held by another live
+     * chrome-mcp — join it as a peer. Returns the port (useful with port 0).
+     */
     start(): Promise<number>;
+    private claim;
+    /**
+     * Join the chrome-mcp holding `port` as a peer. Tries the token in the
+     * handshake it published first (sessions without --persist-token each mint
+     * their own), then ours.
+     */
+    private joinHub;
+    /** The token the port's current owner published, if its handshake describes that port. */
+    private publishedToken;
+    /** The hub exited (its session ended): race the other peers for the port. */
+    private onHubLost;
+    private failover;
     /** One bind attempt. Resolves with a listening server or rejects with the listen error. */
     private listenOnce;
     stop(): Promise<void>;
@@ -73,13 +130,36 @@ export declare class BridgeServer {
     lastActiveUrl(profile: string | undefined, maxAgeMs: number): string | null;
     /** Same, for an explicitly-targeted tab (wire id) — see ExtensionConnection.lastTabUrl. */
     lastTabUrl(profile: string | undefined, tabId: string, maxAgeMs: number): string | null;
-    private noPairMessage;
+    /** How to pair a browser for `profile` — surfaced whenever that profile has no live connection. */
+    noPairMessage(profile: string): string;
+    /** Every paired browser with how it was named — for chrome_status. */
+    pairedProfiles(): PairedProfile[];
+    /**
+     * Rename an automatically named browser. The new name sticks across restarts
+     * (it's stored against the extension install); a live connection is re-keyed
+     * in place, so it keeps working without re-pairing.
+     */
+    renameProfile(from: string, to: string): Promise<string>;
     status(): {
         extensionConnected: boolean;
         port: number;
         connectedProfiles: string[];
     };
     private handleConnection;
+    /**
+     * Pick the routing key for an authenticated hello. A Profile typed into the
+     * Options wins; otherwise an install keeps the name the registry gave it, and
+     * a new install gets the first free one — never a name another browser holds,
+     * so a second blank-profile Chrome joins instead of knocking the first off.
+     * An extension too old to send an installId pairs as "default", as before.
+     */
+    private nameFor;
+    /** Hub side: serve a joined peer's relayed commands against our browsers. */
+    private acceptPeer;
+    private handlePeerFrame;
+    /** Tell every peer which browsers are paired — on each pair, unpair and rename. */
+    private broadcastState;
+    private sendPeer;
     private reject;
     private promote;
     private send;

package/dist/src/bridge/server.js

@@ -8,8 +8,11 @@
  *   1. Accept any loopback upgrade.
  *   2. Require a valid `hello` (matching version + token) within HELLO_TIMEOUT;
  *      otherwise send `unauthorized` and close 4401.
- *   3. On success, send `welcome`, promote to the single ACTIVE connection
- *      (superseding any prior one — a security-relevant displacement event).
+ *   3. On success, send `welcome` and file the connection under its profile
+ *      (superseding only that profile's prior one — a security-relevant
+ *      displacement event).
+ * Other chrome-mcp servers (one per Claude session) may join the same port as
+ * peers with `peer_hello` and relay their commands through us; see ./peer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BridgeServer = void 0;
@@ -22,6 +25,8 @@ const connection_1 = require("./connection");
 const auth_1 = require("./auth");
 const evict_1 = require("./evict");
 const config_1 = require("../config");
+const profiles_1 = require("./profiles");
+const peer_1 = require("./peer");
 /** The routing label for a hello with no/blank profile — the back-compat default. */
 const DEFAULT_PROFILE = 'default';
 /** Reduce a hello's profile label to a safe routing key; blank/invalid → "default". */
@@ -61,16 +66,42 @@ class BridgeServer {
      *  once; a command is routed to the connection for its target profile. A new
      *  hello for the SAME profile supersedes that profile's connection only. */
     conns = new Map();
+    /** Profile routing key → how that live connection got its name, and the
+     *  install behind it (absent for extensions too old to send one). */
+    origins = new Map();
+    /** Remembers which name each extension install was given. */
+    registry;
     boundPort = 0;
     heartbeatMs;
+    /** The pairing secret. Starts as ours; a peer adopts the hub's, so if it
+     *  later takes the port over the extension re-pairs without a new token. */
+    token;
+    /** Peer role: the link to the hub that owns the browsers. */
+    hub = null;
+    /** Hub role: the other chrome-mcp servers relaying through us. */
+    peers = new Set();
+    stopped = false;
     constructor(opts) {
         this.opts = opts;
         this.heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+        this.registry = new profiles_1.ProfileRegistry(opts.dataDir);
+        this.token = opts.token;
     }
-    /** Bind and start listening. Returns the actual port (useful with port 0). */
+    /** 'hub' or 'peer' once started; null before start and between roles. */
+    get role() {
+        return this.wss ? 'hub' : this.hub ? 'peer' : null;
+    }
+    /**
+     * Bind and start listening, or — when a pinned port is held by another live
+     * chrome-mcp — join it as a peer. Returns the port (useful with port 0).
+     */
     async start() {
-        if (this.wss)
+        if (this.wss || this.hub)
             return this.boundPort;
+        this.stopped = false;
+        return this.claim();
+    }
+    async claim() {
         const host = this.opts.host ?? protocol_1.BRIDGE_HOST;
         const port = this.opts.port ?? 0;
         // A fixed port can be briefly held by a just-replaced instance of ourselves
@@ -79,23 +110,34 @@ class BridgeServer {
         // it never frees up do we surface a plain-English, actionable error.
         const deadline = Date.now() + PORT_WAIT_MS;
         let evicted = false;
+        let triedJoin = false;
         for (let attempt = 1;; attempt++) {
             try {
                 const wss = await this.listenOnce(host, port);
                 const addr = wss.address();
                 this.boundPort = typeof addr === 'object' && addr ? addr.port : port;
                 this.wss = wss;
+                // A peer promoted by failover picks up names the old hub assigned since.
+                this.registry = new profiles_1.ProfileRegistry(this.opts.dataDir);
                 this.log(`bridge listening on ${host}:${this.boundPort}`);
+                this.opts.onRole?.('hub', { port: this.boundPort, token: this.token });
                 return this.boundPort;
             }
             catch (err) {
                 const inUse = err?.code === 'EADDRINUSE';
                 if (!inUse || port === 0)
                     throw inUse ? new Error(portBusyMessage(host, port)) : err;
-                // A live chrome-mcp from another session will never release the port on
-                // its own, so waiting it out is futile — take it over (once). Only a
-                // verified chrome-mcp is ever killed; anything else falls through to the
-                // wait-and-retry below, which covers our own just-replaced instance.
+                // Another Claude session's chrome-mcp owns the port: share it rather
+                // than kill it, so every session keeps working at once.
+                if (!triedJoin) {
+                    triedJoin = true;
+                    if (await this.joinHub(host, port))
+                        return this.boundPort;
+                }
+                // Still busy after a failed join: an older chrome-mcp that can't share,
+                // or a hung one. It will never release the port on its own, so take it
+                // over (once). Only a verified chrome-mcp is ever killed; anything else
+                // falls through to the wait-and-retry below.
                 if (!evicted && this.opts.dataDir) {
                     evicted = true;
                     if (await (0, evict_1.evictPortOwner)(this.opts.dataDir, port, (m) => this.log(m))) {
@@ -110,6 +152,68 @@ class BridgeServer {
             }
         }
     }
+    /**
+     * Join the chrome-mcp holding `port` as a peer. Tries the token in the
+     * handshake it published first (sessions without --persist-token each mint
+     * their own), then ours.
+     */
+    async joinHub(host, port) {
+        const tokens = new Set();
+        const published = this.publishedToken(port);
+        if (published)
+            tokens.add(published);
+        tokens.add(this.token);
+        for (const token of tokens) {
+            const link = await peer_1.HubLink.join(host, port, token, () => this.onHubLost());
+            if (!link)
+                continue;
+            if (this.stopped) {
+                link.close();
+                return false;
+            }
+            this.hub = link;
+            this.token = token;
+            this.boundPort = port;
+            this.log(`port ${host}:${port} is held by chrome-mcp pid ${link.hubPid || '?'} — sharing its browsers as a peer`);
+            this.opts.onRole?.('peer', { port, token, hubPid: link.hubPid });
+            return true;
+        }
+        return false;
+    }
+    /** The token the port's current owner published, if its handshake describes that port. */
+    publishedToken(port) {
+        if (!this.opts.dataDir)
+            return null;
+        try {
+            const h = (0, auth_1.readHandshake)(this.opts.dataDir);
+            return h.port === port && h.pid !== process.pid && typeof h.token === 'string' ? h.token : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The hub exited (its session ended): race the other peers for the port. */
+    onHubLost() {
+        this.hub = null;
+        if (this.stopped)
+            return;
+        this.log('the chrome-mcp sharing its browsers with us went away — taking over the port');
+        void this.failover();
+    }
+    async failover() {
+        // Stagger so surviving peers don't all bind at once; the losers join the winner.
+        await delay(50 + Math.floor(Math.random() * 250));
+        for (let attempt = 1; !this.stopped && !this.wss && !this.hub; attempt++) {
+            try {
+                await this.claim();
+                return;
+            }
+            catch (err) {
+                this.log(`failover attempt ${attempt} failed: ${err instanceof Error ? err.message : String(err)}`);
+                await delay(1_000);
+            }
+        }
+    }
     /** One bind attempt. Resolves with a listening server or rejects with the listen error. */
     listenOnce(host, port) {
         return new Promise((resolve, reject) => {
@@ -135,6 +239,12 @@ class BridgeServer {
         });
     }
     async stop() {
+        this.stopped = true;
+        this.hub?.close();
+        this.hub = null;
+        for (const peer of this.peers)
+            peer.close(1001, 'server stopping');
+        this.peers.clear();
         for (const conn of this.conns.values())
             conn.close(1001, 'server stopping');
         this.conns.clear();
@@ -148,6 +258,8 @@ class BridgeServer {
     }
     /** True when ANY browser is paired (used as the selector's cheap gate). */
     hasActiveExtension() {
+        if (this.hub)
+            return this.hub.profiles.length > 0;
         for (const conn of this.conns.values())
             if (conn.isOpen())
                 return true;
@@ -155,11 +267,15 @@ class BridgeServer {
     }
     /** True when the given profile has a live connection. */
     hasConnection(profile) {
+        if (this.hub)
+            return this.hub.profiles.some((p) => p.name === routeKey(profile));
         const conn = this.conns.get(routeKey(profile));
         return !!conn && conn.isOpen();
     }
     /** Profiles with a live connection right now. */
     connectedProfiles() {
+        if (this.hub)
+            return this.hub.profiles.map((p) => p.name);
         const out = [];
         for (const [profile, conn] of this.conns)
             if (conn.isOpen())
@@ -171,6 +287,8 @@ class BridgeServer {
      * Rejects with an actionable message if that profile has no live browser.
      */
     async sendCommand(method, params, opts) {
+        if (this.hub)
+            return this.hub.relay(method, params, opts);
         const profile = routeKey(opts?.profile);
         const conn = this.conns.get(profile);
         if (!conn || !conn.isOpen()) {
@@ -184,19 +302,68 @@ class BridgeServer {
      * to report URLs, a tab shuffle since, or simply nothing recent enough.
      */
     lastActiveUrl(profile, maxAgeMs) {
+        if (this.hub)
+            return null; // a peer has no cache; the caller asks properly
         const conn = this.conns.get(routeKey(profile));
         return conn?.isOpen() ? conn.lastActiveUrl(maxAgeMs) : null;
     }
     /** Same, for an explicitly-targeted tab (wire id) — see ExtensionConnection.lastTabUrl. */
     lastTabUrl(profile, tabId, maxAgeMs) {
+        if (this.hub)
+            return null;
         const conn = this.conns.get(routeKey(profile));
         return conn?.isOpen() ? conn.lastTabUrl(tabId, maxAgeMs) : null;
     }
+    /** How to pair a browser for `profile` — surfaced whenever that profile has no live connection. */
     noPairMessage(profile) {
         return (`No browser is paired for profile "${profile}". In that Chrome's chrome-mcp ` +
             `extension Options, set Port ${this.boundPort}, paste the token, set Profile to ` +
             `"${profile}", and Save — then it joins without disturbing your other profiles.`);
     }
+    /** Every paired browser with how it was named — for chrome_status. */
+    pairedProfiles() {
+        if (this.hub)
+            return [...this.hub.profiles];
+        const out = [];
+        for (const [name, conn] of this.conns) {
+            if (!conn.isOpen())
+                continue;
+            const activeUrl = conn.lastActiveUrl(Number.POSITIVE_INFINITY) ?? undefined;
+            out.push({ name, naming: this.origins.get(name)?.naming ?? 'legacy', ...(activeUrl ? { activeUrl } : {}) });
+        }
+        return out;
+    }
+    /**
+     * Rename an automatically named browser. The new name sticks across restarts
+     * (it's stored against the extension install); a live connection is re-keyed
+     * in place, so it keeps working without re-pairing.
+     */
+    async renameProfile(from, to) {
+        if (this.hub)
+            return String(await this.hub.rename(from, to));
+        const src = routeKey(from);
+        const live = this.conns.get(src);
+        if (live?.isOpen() && this.origins.get(src)?.naming === 'options') {
+            throw new Error(`Profile "${src}" was named in that Chrome's extension Options — change it there ` +
+                `(clear the field to let the server name it).`);
+        }
+        const target = (0, config_1.sanitizeName)(to, 'profile');
+        if (target !== src && this.conns.get(target)?.isOpen()) {
+            throw new Error(`profile "${target}" already has a paired browser`);
+        }
+        const name = this.registry.rename(src, target);
+        if (name !== src && live) {
+            this.conns.delete(src);
+            this.conns.set(name, live);
+            const origin = this.origins.get(src);
+            this.origins.delete(src);
+            if (origin)
+                this.origins.set(name, origin);
+            this.log(`profile "${src}" renamed to "${name}"`);
+            this.broadcastState();
+        }
+        return name;
+    }
     status() {
         return {
             extensionConnected: this.hasActiveExtension(),
@@ -233,6 +400,19 @@ class BridgeServer {
                 this.reject(ws, 'bad_token');
                 return;
             }
+            if (frame.type === 'peer_hello') {
+                // Another chrome-mcp (a second Claude session) joining to share our browsers.
+                const peer = frame;
+                clearTimeout(helloTimer);
+                if (peer.v !== protocol_1.PROTOCOL_VERSION)
+                    return this.reject(ws, 'bad_version');
+                if (typeof peer.token !== 'string' || !(0, auth_1.tokensMatch)(peer.token, this.token))
+                    return this.reject(ws, 'bad_token');
+                authed = true;
+                ws.off('message', onMessage);
+                this.acceptPeer(ws, peer.pid);
+                return;
+            }
             if (frame.type !== 'hello')
                 return; // ignore noise until a hello arrives
             if (frame.v !== protocol_1.PROTOCOL_VERSION) {
@@ -240,7 +420,7 @@ class BridgeServer {
                 this.reject(ws, 'bad_version');
                 return;
             }
-            if (typeof frame.token !== 'string' || !(0, auth_1.tokensMatch)(frame.token, this.opts.token)) {
+            if (typeof frame.token !== 'string' || !(0, auth_1.tokensMatch)(frame.token, this.token)) {
                 clearTimeout(helloTimer);
                 this.reject(ws, 'bad_token');
                 return;
@@ -249,13 +429,77 @@ class BridgeServer {
             authed = true;
             clearTimeout(helloTimer);
             ws.off('message', onMessage);
-            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile), Array.isArray(frame.caps) ? frame.caps : undefined);
+            const { profile, naming, installId } = this.nameFor(frame);
+            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, profile, Array.isArray(frame.caps) ? frame.caps : undefined, { naming, installId });
         };
         ws.on('message', onMessage);
         ws.on('error', () => {
             /* pre-auth socket errors are non-fatal; the close will clean up */
         });
     }
+    /**
+     * Pick the routing key for an authenticated hello. A Profile typed into the
+     * Options wins; otherwise an install keeps the name the registry gave it, and
+     * a new install gets the first free one — never a name another browser holds,
+     * so a second blank-profile Chrome joins instead of knocking the first off.
+     * An extension too old to send an installId pairs as "default", as before.
+     */
+    nameFor(frame) {
+        const installId = (0, profiles_1.isValidInstallId)(frame.installId) ? frame.installId : undefined;
+        if (frame.profile && frame.profile.trim())
+            return { profile: routeKey(frame.profile), naming: 'options', installId };
+        if (!installId)
+            return { profile: DEFAULT_PROFILE, naming: 'legacy' };
+        const heldByOther = (name) => {
+            const conn = this.conns.get(name);
+            return !!conn && conn.isOpen() && this.origins.get(name)?.installId !== installId;
+        };
+        return { profile: this.registry.assign(installId, heldByOther), naming: 'auto', installId };
+    }
+    /** Hub side: serve a joined peer's relayed commands against our browsers. */
+    acceptPeer(ws, pid) {
+        this.peers.add(ws);
+        this.log(`chrome-mcp pid ${pid ?? '?'} joined as a peer (${this.peers.size} sharing these browsers)`);
+        this.sendPeer(ws, { type: 'peer_welcome', hubPid: process.pid });
+        this.sendPeer(ws, { type: 'peer_state', profiles: this.pairedProfiles() });
+        ws.on('message', (raw) => this.handlePeerFrame(ws, raw.toString()));
+        ws.on('close', () => this.peers.delete(ws));
+        ws.on('error', () => {
+            /* the close that follows cleans up */
+        });
+    }
+    handlePeerFrame(ws, raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const answer = (id, work) => {
+            work.then((data) => this.sendPeer(ws, { type: 'relay_result', id, ok: true, data }), (err) => this.sendPeer(ws, (0, peer_1.relayError)(id, err)));
+        };
+        if (frame.type === 'relay')
+            answer(frame.id, this.sendCommand(frame.method, frame.params ?? {}, frame.opts));
+        else if (frame.type === 'peer_rename')
+            answer(frame.id, this.renameProfile(frame.from, frame.to));
+    }
+    /** Tell every peer which browsers are paired — on each pair, unpair and rename. */
+    broadcastState() {
+        if (this.peers.size === 0)
+            return;
+        const state = { type: 'peer_state', profiles: this.pairedProfiles() };
+        for (const peer of this.peers)
+            this.sendPeer(peer, state);
+    }
+    sendPeer(ws, frame) {
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* peer already gone */
+        }
+    }
     reject(ws, reason) {
         this.send(ws, { type: 'unauthorized', v: protocol_1.PROTOCOL_VERSION, reason });
         this.log(`rejected a connection: ${reason}`);
@@ -266,7 +510,7 @@ class BridgeServer {
             /* ignore */
         }
     }
-    promote(ws, ext, profile, caps) {
+    promote(ws, ext, profile, caps, origin) {
         const sessionId = (0, node_crypto_1.randomUUID)();
         // Supersede only the SAME profile's connection (a re-pair). Other profiles
         // keep their live connections, so several browsers stay paired at once.
@@ -293,12 +537,20 @@ class BridgeServer {
             onEvent: this.opts.onEvent,
             onLog: (m) => this.log(m),
             onClose: () => {
-                // Only clear if a newer re-pair hasn't already replaced this slot.
-                if (this.conns.get(profile)?.sessionId === sessionId)
-                    this.conns.delete(profile);
+                // Only clear if a newer re-pair hasn't already replaced this slot. Look it
+                // up by session: profile_rename may have re-keyed the slot since.
+                for (const [key, c] of this.conns) {
+                    if (c.sessionId !== sessionId)
+                        continue;
+                    this.conns.delete(key);
+                    this.origins.delete(key);
+                }
+                this.broadcastState();
             },
         });
         this.conns.set(profile, conn);
+        this.origins.set(profile, origin);
+        this.broadcastState();
         const welcome = {
             type: 'welcome',
             v: protocol_1.PROTOCOL_VERSION,
@@ -306,6 +558,7 @@ class BridgeServer {
             sessionId,
             heartbeatMs: this.heartbeatMs,
             policy: this.opts.policy ?? policy_1.DENY_ALL_WIRE_POLICY,
+            profile,
         };
         this.send(ws, welcome);
         this.log(`extension paired (profile "${profile}", session ${sessionId}, id "${ext.id}")`);

package/dist/src/cli.js

@@ -211,8 +211,37 @@ async function main() {
         dataDir,
         onLog: (m) => (0, server_2.logErr)(m),
         onDisplacement: (d) => (0, server_2.logErr)(`SECURITY: extension connection displaced (different id: ${d.differentId})`),
+        // Only the server that owns the port publishes pairing files. A peer (another
+        // Claude session sharing this Chrome) leaves them alone, and publishes them
+        // itself if the hub exits and it takes the port over.
+        onRole: (role, info) => {
+            if (role === 'hub')
+                publishPairing(info.port, info.token);
+            else
+                (0, server_2.logErr)(`sharing the browsers of the chrome-mcp already on port ${info.port} (pid ${info.hubPid || '?'}) — several sessions can drive Chrome at once`);
+        },
     });
+    const publishPairing = (port, pairToken) => {
+        const path = (0, auth_1.writeHandshake)(dataDir, { port, token: pairToken });
+        (0, server_2.logErr)(`pairing handshake written to ${path} (mode 0600; token not logged)`);
+        // Drop the same port + token into the bundled extension folder so a Load
+        // unpacked from there pairs itself. Best-effort: a read-only install just
+        // falls back to the Options-page paste.
+        const extDir = installExtension();
+        const bundled = (0, auth_1.writeBundledPairing)(extDir, { port, token: pairToken });
+        if (bundled) {
+            (0, server_2.logErr)(`auto-pairing file written to ${bundled} — Load unpacked from ${extDir} needs no token paste`);
+        }
+        else {
+            (0, server_2.logDebug)(`auto-pairing file not written (extension folder missing or read-only at ${extDir})`);
+        }
+        // Anyone who loaded the extension straight from the package folder (0.8.0
+        // docs) keeps pairing too.
+        if (extDir !== (0, extension_install_1.bundledExtensionDir)())
+            (0, auth_1.writeBundledPairing)((0, extension_install_1.bundledExtensionDir)(), { port, token: pairToken });
+    };
     const port = await bridge.start();
+    (0, tools_1.setProfileBridge)(bridge);
     // Never includes the pairing token — only the resolved, non-secret config.
     (0, server_2.logDebug)(`resolved config: ${JSON.stringify({
         wsPort: port,
@@ -222,23 +251,7 @@ async function main() {
         prefer: cfg.prefer,
         policy: cfg.policy,
     })}`);
-    const handshakePath = (0, auth_1.writeHandshake)(dataDir, { port, token });
-    (0, server_2.logErr)(`pairing handshake written to ${handshakePath} (mode 0600; token not logged)`);
-    // Drop the same port + token into the bundled extension folder so a Load
-    // unpacked from there pairs itself. Best-effort: a read-only install just
-    // falls back to the Options-page paste.
-    const extDir = installExtension();
-    const bundled = (0, auth_1.writeBundledPairing)(extDir, { port, token });
-    if (bundled) {
-        (0, server_2.logErr)(`auto-pairing file written to ${bundled} — Load unpacked from ${extDir} needs no token paste`);
-    }
-    else {
-        (0, server_2.logDebug)(`auto-pairing file not written (extension folder missing or read-only at ${extDir})`);
-    }
-    // Anyone who loaded the extension straight from the package folder (0.8.0
-    // docs) keeps pairing too.
-    if (extDir !== (0, extension_install_1.bundledExtensionDir)())
-        (0, auth_1.writeBundledPairing)((0, extension_install_1.bundledExtensionDir)(), { port, token });
+    const handshakePath = (0, datadir_1.handshakePath)(dataDir);
     if (process.env.CHROME_MCP_TOKEN) {
         (0, server_2.logErr)('token: pinned from CHROME_MCP_TOKEN (stable; pair once, never again).');
     }
@@ -246,7 +259,10 @@ async function main() {
         (0, server_2.logErr)('token: persisted across restarts (--persist-token; pair once, never again).');
     }
     const cleanup = () => {
-        (0, auth_1.removeHandshake)(dataDir);
+        // The handshake belongs to whichever server owns the port; a peer exiting
+        // must not delete the hub's.
+        if (bridge.role === 'hub')
+            (0, auth_1.removeHandshake)(dataDir);
     };
     // Manual pairing helper: run the bridge, print the path, keep alive. NOT MCP.
     if (cfg.printPairing) {

package/dist/src/config.js

@@ -294,8 +294,10 @@ Connection:
   --profile <name>       Default browser profile / identity (default "default").
                          Artifacts live under profiles/<name>/. At runtime, switch
                          with the profile_use tool. Several browsers can pair to the
-                         SAME port+token at once, each declaring its own Profile in
-                         the extension Options; tools route to the active profile.
+                         SAME port+token at once; each is named automatically
+                         (default, profile-2, ...; rename with profile_rename) unless
+                         its extension Options pins a Profile. Tools route to the
+                         active profile.
   --task <name>          Task label (default "default"). Downloads and a meta.json
                          land in profiles/<profile>/tasks/<task>/.
   --print-pairing        Write the handshake, print its path, and keep the bridge

package/dist/src/executor/extension-executor.d.ts

@@ -20,6 +20,9 @@ export declare class ExtensionExecutor implements Executor {
     status(): ExecutorStatus;
     ensureReady(): Promise<void>;
     ping(deadlineMs?: number): Promise<boolean>;
+    /** Why this executor can't serve the active profile right now: not paired, or
+     *  paired but not answering pings. Used for the selector's NO_BACKEND message. */
+    unavailableReason(): string;
     dispose(): Promise<void>;
     /** The active tab's URL as reported by the last command on this profile, if it
      *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */