@evan_zhong/browser-attach 0.16.0 → 0.17.0

package/README.md

@@ -67,7 +67,7 @@ Merge the following into your client's MCP configuration, or see [mcp-config.jso
 
 On Windows clients that require a full command extension, use `npx.cmd`. With a global install you can also configure `"command": "browser-attach", "args": ["mcp"]`. Restart the MCP client to discover the tools.
 
-`@latest` resolves the newest npm version at launch. The MCP package and the loaded extension must be the same version; after an upgrade, rerun `browser-attach setup` and reload the extension on the extensions page, otherwise the Hub rejects the old extension connection.
+`@latest` selects the npm package at launch. For a pair already running 0.17 or newer, startup coordinates an idle Hub upgrade, synchronizes the paired extension directory and asks older connected extensions to reload themselves. First-time extension loading and the first upgrade from a pre-0.17 pair still require one manual extension reload; a pre-0.17 Hub must be stopped once before the new MCP can start. If another MCP connection is using the Hub, close it and reconnect to retry the upgrade.
 
 Assembly steps for supported hosts are in [agent integration](docs/AGENT-INTEGRATION.md); other clients use the stdio entry above.
 
@@ -113,13 +113,12 @@ Override it explicitly with the absolute path `BROWSER_ATTACH_HOME`. The Windows
 A host assembly step that writes the client entry pins the absolute paths of the current Node, CLI and the actual pairing file and sets `BROWSER_ATTACH_HOME`; it works together with a custom `--config`. When the MCP launches the Hub it passes the same absolute pairing path and directory, so different launch environments cannot derive a second configuration. See [agent integration](docs/AGENT-INTEGRATION.md).
 
 ```sh
-browser-attach status
-browser-attach stop
 npm install --global @evan_zhong/browser-attach
-browser-attach setup
 ```
 
-After upgrading, reload the extension on the extensions page, then restart the MCP connection. Hub and extension versions must match. The first time you use this project's new name, stop any previously running Hub and pair again; the default port is `47831` and `setup --port` changes it.
+Then restart the MCP connection. With `@latest`, restarting MCP is sufficient for later upgrades once Hub and extension are on 0.17 or newer; `setup` and `start` use the same coordination when run explicitly. Upgrading from an older pair first requires `browser-attach stop`, a restart and one manual extension reload. Custom pairing paths, ports and extension directories are retained. Closed browser profiles update when they next connect. An older MCP package cannot downgrade a newer Hub or installed extension.
+
+An upgrade waits for extension cleanup and confirms the new version after reload; cleanup or reload failures are reported instead of replaying page actions. Manual reload remains available on the extension options page for recovery. Hub and extension versions must match for page control. The default port is `47831`; choose another port with `setup --port` when creating a pairing.
 
 ## Architecture and boundaries
 
@@ -164,6 +163,7 @@ Real-browser tests need a Chromium / Edge executable that allows loading extensi
 npm run test:live -- --executable /path/to/chromium --family chromium
 npm run test:interaction -- --executable /path/to/chromium --family chromium
 npm run test:interaction -- --tab-indicators --executable /path/to/chromium --family chromium
+npm run test:upgrade -- --executable /path/to/chromium
 ```
 
 These tests use temporary profiles and local fixtures. Coverage and limits: [test report](docs/TEST-REPORT.md); implementation and design trade-offs: [architecture](docs/ARCHITECTURE.md).

package/README.zh.md

@@ -67,7 +67,7 @@ npx --yes --package=@evan_zhong/browser-attach@latest browser-attach setup
 
 Windows 客户端若要求完整命令扩展名，使用 `npx.cmd`。已全局安装时，也可以配置 `"command": "browser-attach", "args": ["mcp"]`。重启 MCP 客户端后发现工具。
 
-`@latest` 会在启动时解析 npm 最新版本。MCP 包与已加载扩展必须为同一版本；升级后重新运行 `browser-attach setup` 并在扩展页重新加载扩展，否则 Hub 会拒绝旧扩展连接。
+`@latest` 在启动时选择 npm 包版本。当配对已经运行 0.17 或更高版本时，MCP 启动会协调空闲 Hub 升级、同步已配对的扩展目录，并通知较旧扩展自行重新加载。首次加载扩展，以及从 0.17 之前版本进行的第一次升级，仍需手动重载一次扩展；旧 Hub 必须先停止，新 MCP 才能启动。如果其他 MCP 连接正在使用 Hub，请关闭这些连接后重连，以重试升级。
 
 各宿主的装配步骤见 [Agent 集成](docs/AGENT-INTEGRATION.md)；其他客户端直接使用上面的 stdio 配置。
 
@@ -113,13 +113,12 @@ Windows 客户端若要求完整命令扩展名，使用 `npx.cmd`。已全局
 宿主装配步骤写入客户端条目时，会固定当前 Node、CLI 和实际配对文件的绝对路径，并设置 MCP 的 `BROWSER_ATTACH_HOME`；支持与自定义 `--config` 一起使用。MCP 启动 Hub 时继续传入同一绝对配对路径及目录，避免不同启动环境重新推导出另一份配置。详见 [Agent 集成](docs/AGENT-INTEGRATION.md)。
 
 ```sh
-browser-attach status
-browser-attach stop
 npm install --global @evan_zhong/browser-attach
-browser-attach setup
 ```
 
-升级后在浏览器扩展管理页重新加载扩展，再重启 MCP 连接。Hub 与扩展版本必须一致。首次使用本项目的新名称时，应停止之前运行的 Hub 并重新配对；默认端口为 `47831`，可用 `setup --port` 修改。
+安装新版后重连 MCP。使用 `@latest` 时，在 Hub 与扩展已经运行 0.17 或更高版本后，重连 MCP 即可协调后续升级；显式运行 `setup` 或 `start` 也使用同一流程。从更旧版本升级时，需要先执行 `browser-attach stop`、重启 MCP，并手动重载一次扩展。自定义配对路径、端口和扩展目录会保留。未打开的浏览器 profile 在下次连接时完成更新。旧 MCP 包不会降级新版 Hub 或已安装扩展。
+
+升级会等待扩展清理，并在重载后确认新版本；清理或重载失败会明确报告，不重放页面动作。扩展设置页保留手动重新加载按钮用于恢复。正常页面控制仍要求 Hub 与扩展版本一致。默认端口为 `47831`，创建配对时可通过 `setup --port` 选择其他端口。
 
 ## 架构与使用边界
 
@@ -164,6 +163,7 @@ node bin/browser-attach.mjs mcp
 npm run test:live -- --executable /path/to/chromium --family chromium
 npm run test:interaction -- --executable /path/to/chromium --family chromium
 npm run test:interaction -- --tab-indicators --executable /path/to/chromium --family chromium
+npm run test:upgrade -- --executable /path/to/chromium
 ```
 
 这些测试使用临时配置和本地 fixture。测试覆盖与限制见 [验证报告](docs/TEST-REPORT.md)，实现与设计取舍见 [架构与设计](docs/ARCHITECTURE.md)。

package/bin/browser-attach.mjs

@@ -6,7 +6,7 @@ import { ensureHub, hubIsRunning, AttachClient } from '../src/client.mjs';
 try {
   const { values, positionals } = parseArgs({ allowPositionals: true, options: {
     config: { type: 'string', default: DEFAULT_CONFIG },
-    'extension-dir': { type: 'string' }, port: { type: 'string', default: '47831' },
+    'extension-dir': { type: 'string' }, port: { type: 'string' },
     nosis: { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h' },
   } });
   const action = positionals[0] || 'mcp', configPath = values.config;
@@ -20,10 +20,10 @@ try {
     const stop = () => hub.close(); process.once('SIGINT', stop); process.once('SIGTERM', stop);
   } else if (action === 'setup') {
     const { setup, configureNosis } = await import('../src/setup.mjs');
-    const result = await setup({ configPath, extensionDir: values['extension-dir'], port: Number(values.port) });
+    const result = await setup({ configPath, extensionDir: values['extension-dir'], port: values.port === undefined ? undefined : Number(values.port) });
     console.log(`Extension folder: ${result.extensionDir}\nExtension ID: ${result.config.extension_id}\nPairing: ${result.configPath}`);
     if (values.nosis) console.log(JSON.stringify(await configureNosis(undefined, { configPath: result.configPath })));
-    await ensureHub(result.configPath); console.log('Local hub started. Load/reload the extension in Chrome/Edge.');
+    await ensureHub(result.configPath); console.log('Local hub ready. Load the extension in each Chrome/Edge profile on first use; subsequent upgrades reload it automatically.');
   } else if (action === 'start') { await ensureHub(configPath); console.log('Local hub started.'); }
   else if (action === 'status') {
     const config = await loadConfig(configPath);

package/docs/AGENT-INTEGRATION.md

@@ -26,7 +26,7 @@ node <安装位置>/bin/browser-attach.mjs mcp --config <配对文件绝对路
 
 - `BROWSER_ATTACH_HOME` 指向配对文件所在目录。
 - Node 可执行文件、CLI 与配对文件一律使用绝对路径。宿主的启动环境（PATH、工作目录、AppData 重定向）不同，重新推导会得到第二份配对。
-- 安装位置变化或升级后重新执行 `setup` 并更新宿主条目。MCP 包与已加载扩展必须同版本，否则 Hub 直接拒绝连接。
+- 安装位置变化后重新执行 `setup` 并更新宿主条目。Hub 与扩展已经运行 0.17 或更高版本时，安装新版后重连 MCP 会协调空闲 Hub 与扩展自动升级；从更旧版本首次升级需先停止 Hub、重启 MCP 并手动重载一次扩展。其他 MCP 仍连接时关闭它们后重试。正常页面控制要求同版本。
 
 工具前缀由宿主决定，原始工具名不变（`browser_discover`、`browser_claim_tab` 等）。装配后的最小验证在各宿主一致：`browser_discover(kind="browsers")` → `kind="tabs"` → `browser_claim_tab` → `browser_snapshot` → `browser_tab_control(action="release")`。
 
@@ -110,7 +110,7 @@ npm root -g       # 全局安装目录；CLI 位于 <root>/@evan_zhong/browser-a
 - `web` profile 开启 HMR，修改条目会就地重连；`headless`、`sdk`、`acp` 关闭 HMR，需要重启 harness。
 - MCP 工具与原生工具一样经过 DSH 的权限检查与审批策略。
 
-升级后重新加载扩展并重启 harness；包与扩展版本必须一致。
+安装新版后重启或重连 harness，由 MCP 启动流程协调 0.17+ 的后续 Hub 与扩展升级；首次加载扩展以及从更旧版本首次升级仍需手动重载。
 
 ## 新增宿主
 
@@ -122,4 +122,4 @@ npm root -g       # 全局安装目录；CLI 位于 <root>/@evan_zhong/browser-a
 - 失效句柄不能跨连接复用，错误后应重新 discover + claim。
 - 文件上传只在浏览器本机读取路径，内容不经过 Hub 或模型。
 - 宿主把大结果保存为 Artifact 时，嵌套 JSON 长行可能被宿主的读取工具截断；这是宿主的分页行为，不能靠调大 Attach 的预算解决，也不等同于快照游标分页。
-- `Connection closed` 时依次检查：宿主的 stderr、配对文件是否可见、`hub.log`、以及 Hub 与扩展的版本是否一致（版本不一致会直接拒绝连接）。
+- `Connection closed` 时依次检查：宿主的 stderr、配对文件是否可见、`hub.log`、是否有其他 MCP 连接阻止升级，以及扩展清理或自动重载是否失败。扩展设置页可手动重新加载以恢复。

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构与设计边界
 
-当前实现为 **0.16.0**。本文说明 BrowserAttach 的组件、控制模型与设计取舍；工具参数见 [使用指南](USAGE.md)。
+当前实现为 **0.17.0**。本文说明 BrowserAttach 的组件、控制模型与设计取舍；工具参数见 [使用指南](USAGE.md)。
 
 ## 组件与数据流
 
@@ -17,11 +17,12 @@ MCP 客户端
 |---|---|
 | `bin/browser-attach.mjs` | `setup` / `mcp` / `hub` / `status` / `stop` 入口 |
 | `src/config.mjs` | 数据目录、配对文件校验、版本常量 |
-| `src/setup.mjs` | 生成配对密钥、复制稳定扩展目录、写 Nosis 配置 |
+| `src/setup.mjs` | 生成配对密钥、暂存并替换稳定扩展目录、写 Nosis 配置 |
 | `src/hub.mjs` | 浏览器与会话注册、独占 claim、每标签串行队列、超时 |
-| `src/client.mjs` | MCP 进程到 Hub 的 WebSocket 客户端，按需拉起 Hub |
+| `src/client.mjs` | MCP 到 Hub 的 WebSocket 客户端、启动升级协调与就绪检查 |
 | `src/mcp.mjs` | 23 个工具的 schema、结果与图片封装 |
 | `extension/controller.js` | 操作实现；传输层从不暴露原始 CDP |
+| `extension/connection.js` | 扩展连接、重连清理、升级维护与自行重载 |
 | `extension/sessions.js` | 扁平 debugger session 与 frame/OOPIF 归属 |
 | `extension/{click,input,actionability,scroll}.js` | 原生/DOM 输入、逐字按键、可操作性、容器滚动与有界查找 |
 | `extension/{drag,wait}.js` | 复用鼠标准备和严格定位的拖拽、只读条件等待；网络空闲复用被动请求表 |
@@ -119,7 +120,7 @@ HTTP 状态复用 diagnostics 的 Network.responseReceived 观察，按主文档
 ## 安全与隐私
 
 - Hub 只监听 `127.0.0.1`；HTTP 端点拒绝任何带 `Origin` 的请求，客户端必须携带 Bearer 密钥。
-- 扩展连接固定校验 `chrome-extension://<extension_id>` Origin、随机 token 与版本号，三者任一不符即断开。
+- 扩展连接固定校验 `chrome-extension://<extension_id>` Origin 与随机 token。同版本才注册为可控浏览器；已配对的较旧扩展仅进入维护连接，收到重载请求后校验本机文件、完成清理再自行重载。客户端握手同样要求版本一致。
 - 配对文件 `config.json` 与生成的 `extension/config.generated.js` 含密钥：目录在 Windows 上用当前用户 SID 收紧 ACL，在 POSIX 上为 `0700`/`0600`；发布包检查会拒绝包含 `config.generated.js`。
 - 扩展具备 `debugger` 与 `tabGroups` 权限，操作使用用户现有登录态；只应接入信任的 MCP 客户端。网页内容、控制台与网络日志均视为非可信数据。
 - 文件上传只传路径，Hub 与模型都不接触文件内容；选择文件可能立即把内容发给网站，因此只传任务明确指定的文件。
@@ -142,4 +143,6 @@ HTTP 状态复用 diagnostics 的 Network.responseReceived 观察，按主文档
 
 ## 版本与兼容
 
-`package.json`、`src/config.mjs`、`extension/manifest.json` 的版本必须一致；Hub 会拒绝版本不同的扩展，`hubIsRunning` 也会拒绝版本不同的 Hub。MCP 示例配置使用 `@latest`，升级流程：停止旧 Hub → `browser-attach setup` → 在扩展管理页重新加载扩展 → 重连 MCP。
+`package.json`、`src/config.mjs`、`extension/manifest.json` 的版本必须一致。MCP 示例配置使用 `@latest`，MCP 启动、`start` 和 `setup` 共用升级协调：检查已配对 Hub → 空闲 Hub 暂停接入并确认扩展清理 → 旧 Hub 退出 → 新 Hub 独占端口后同步扩展 → 旧扩展自行重载 → 确认新版重连。该自动路径要求 Hub 与扩展已经具备 0.17 的 `connection.js` 维护协议；更旧版本的首次升级必须先停止 Hub、重启 MCP 并手动重载扩展（旧 Hub 没有升级端点，旧扩展也不处理重载命令）。MCP 在 stdio 就绪前即连接 Hub，尚未调用工具的 MCP 会话也会阻止升级。有客户端、断连清理或在途请求时返回占用错误，关闭其他 MCP 连接后重试；不强制打断页面动作。
+
+Hub 的监听端口同时保证同一配对的文件同步只有一个执行者。扩展先完整暂存，保留稳定目录本身，逐文件替换并最后提交 manifest；替换失败恢复旧文件，进程在替换中退出时通过 `.previous` 副本恢复。配对密钥、端口和自定义目录保留，旧包不得降级新版 Hub 或扩展。扩展重载记录尝试，防止失败后无限循环；派发重载不代表升级成功，启动协调仍等待实际版本。未打开的 profile 在下次连接时处理；首次安装仍需手动加载扩展。此流程不热替换正在运行的 MCP 进程。

package/docs/TEST-REPORT.md

@@ -1,9 +1,16 @@
 # 验证报告
 
-当前版本 **0.16.0**（2026-10-22）。浏览器验证使用本地 fixture 和临时 profile；测试链路在各项下说明。
+当前版本 **0.17.0**（2026-10-23）。浏览器验证使用本地 fixture 和临时 profile；测试链路在各项下说明。
 
 ## 当前版本
 
+- `npm test`：196 项通过。新增并发升级与冷启动、无浏览器启动和离线 profile 迟到更新、尚未调用工具的 MCP 会话阻止升级、清理失败恢复、禁止降级、独占端口后才同步、文件中断恢复、自定义配对保留、维护期间拒绝页面动作、本机版本核验、重载循环抑制、detach 失败后禁止重连，以及旧配对缺少 `extension_dir` 时回落到同目录 `extension` 的兼容处理。
+- Chromium 156 与 Edge 155：`npm run test:upgrade -- --executable <路径>` 均通过。临时 profile 开启开发者模式后，两个并发启动者将 Hub 和真实扩展从当前代码改版本号构造的兼容旧协议 0.16.9 升到 0.17.0；确认同一 profile、实际 runtime 重载后的版本，以及升级后发现/接管 → AX 查询 → DOM 点击 → 查询结果 → 释放。CDP 只用于临时 profile 的开发者模式设置，页面操作走扩展与 Hub。该脚本验证升级协议本身，不代表真实 0.16 扩展能自行重载；真实旧版本首次升级仍需手动重载。
+- `npm run test:package`：仓库外安装运行通过，23 个工具、50 个发布文件；由已安装包中的 Hub 同步稳定扩展目录并运行 stdio MCP，不含配对密钥，无新增运行依赖或扩展权限。
+- 本机部署：Hub 已从工作区重启并返回 0.17.0 / ready；`F:\.nosis\browser-attach\extension` 已同步，manifest 为 0.17.0。Chrome、Edge 均上报 0.17.0 并已重连。
+
+## 0.16.0 验证
+
 - `npm test`：184 项通过。新增 offset 的变换/越界处理、延迟区间校验、默认路径不采样随机数、拖拽曲线与精确终点、batch 参数预检、真实 stdio MCP 参数转发，以及 settle/拖拽超时后停止和调试分离取消待点击的回归。
 - Chromium 156 与 Edge 155 headless 输入集成：各 19 个场景通过（扩展 → 独立 Hub 客户端）。新增非中心可信点击、offset hover、settle、区间逐字输入、曲线 pointer 与 HTML5 拖拽；实际记录移动坐标、可信事件和按键时间，保留原有默认路径及跨屏拖拽验证。不据此声称能通过任意网站的行为验证。
 - Chromium 156 完整 stdio MCP 集成：244 次调用通过，保留发现/接管、输入、导航、OOPIF、日志、分页及临时页清理覆盖。

package/docs/USAGE.md

@@ -1,6 +1,6 @@
 # BrowserAttach 使用指南
 
-适用于 **0.16.0**：Node.js 22+、Chrome / Edge 125+、23 个 MCP 工具。安装、配对与升级见 [README](../README.md)；内部实现与安全模型见 [架构说明](ARCHITECTURE.md)。
+适用于 **0.17.0**：Node.js 22+、Chrome / Edge 125+、23 个 MCP 工具。安装、配对与升级见 [README](../README.md)；内部实现与安全模型见 [架构说明](ARCHITECTURE.md)。
 
 工具发现采用三层说明：初始化 `instructions` 提供跨工具规则；工具 description 说明用途、独有行为与结果语义；参数 schema 及其短说明提供类型、默认值和选择规则。本文保留完整原理、边界和示例。客户端集成时应把 MCP 初始化响应中的 instructions 传入模型上下文；仅读取 tools/list 不会包含完整的通用调用规则。
 
@@ -31,6 +31,8 @@
 
 `discover.kind` 与 `tab_control.action` 必填，无默认值。`browser_id` 仅在 `kind=tabs` 时使用且必填；`focus_window` 仅在 `action=activate` 时使用，省略时为 `true`。其他分支传入这些参数会在派发前报错。新建标签仍需加载后发现并显式接管，不会自动取得控制权。
 
+`discover(kind="browsers")` 仅在 `browsers` 中列出同版本、可接受页面操作的扩展。0.17+ 的较旧扩展自动重载期间列在 `upgrades` 中，失败时附带 `error`；维护连接不提供可用于接管的浏览器身份。从 0.17 之前版本升级时，旧扩展不具备自动重载能力，需要手动重载一次。
+
 ### 观察
 
 | 工具 | 主要参数 | 说明 |

package/extension/background.js

@@ -1,98 +1,7 @@
-import { CONNECTION } from './config.generated.js';
-import { createController } from './controller.js';
-
-let socket;
-let connecting = false;
-let keepAlive;
-let reconnect;
-let status = 'disconnected';
-let identity;
-const controller = createController(chrome, event => {
-  if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(event));
-});
-
-async function getIdentity() {
-  const local = await chrome.storage.local.get(['instanceId', 'profileName']);
-  const session = await chrome.storage.session.get('runId');
-  const instanceId = local.instanceId || crypto.randomUUID();
-  const runId = session.runId || crypto.randomUUID();
-  if (!local.instanceId) await chrome.storage.local.set({ instanceId });
-  if (!session.runId) await chrome.storage.session.set({ runId });
-  const family = /Edg\//.test(navigator.userAgent) ? 'edge' : 'chrome';
-  return { instance_id: instanceId, run_id: runId, family,
-    profile_name: local.profileName || (family === 'edge' ? 'Edge' : 'Chrome'),
-    user_agent: navigator.userAgent, extension_id: chrome.runtime.id, extension_version: chrome.runtime.getManifest().version };
-}
-
-async function connect() {
-  if (connecting || socket?.readyState === WebSocket.OPEN) return;
-  connecting = true;
-  try {
-    identity = await getIdentity();
-    const ws = new WebSocket(CONNECTION.url);
-    socket = ws;
-    ws.onopen = () => {
-      ws.send(JSON.stringify({ type: 'hello', token: CONNECTION.token, browser: identity }));
-      keepAlive = setInterval(() => {
-        if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
-      }, 20000);
-    };
-    ws.onmessage = async event => {
-      let request;
-      try {
-        request = JSON.parse(event.data);
-        if (request.type === 'connected') {
-          status = 'connected';
-          await chrome.action.setBadgeText({ text: 'ON' });
-          await chrome.action.setBadgeBackgroundColor({ color: '#13755b' });
-          return;
-        }
-        if (!request.id) return;
-        const result = await controller.execute(request.owner, request.command, request.arguments || {});
-        if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ id: request.id, result }));
-      } catch (error) {
-        if (request?.id && ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ id: request.id, error: error.message || String(error) }));
-        }
-      }
-    };
-    ws.onclose = async () => {
-      clearInterval(keepAlive);
-      status = 'disconnected';
-      connecting = false;
-      await controller.releaseAll();
-      await chrome.action.setBadgeText({ text: 'OFF' });
-      clearTimeout(reconnect);
-      reconnect = setTimeout(connect, 2000);
-    };
-    ws.onerror = () => ws.close();
-  } catch (error) {
-    connecting = false;
-    status = error.message;
-  }
-}
-
-chrome.runtime.onMessage.addListener((message, sender, respond) => {
-  if (sender.id !== chrome.runtime.id) return;
-  if (message.type === 'status') {
-    getIdentity().then(browser => respond({ status, browser, claims: controller.claimedCount() }));
-    return true;
-  }
-  if (message.type === 'reconnect') {
-    if (socket?.readyState === WebSocket.OPEN) socket.close();
-    else connect();
-    respond({ ok: true });
-  }
-  if (message.type === 'release_all') {
-    controller.releaseAll().then(() => respond({ ok: true }));
-    return true;
-  }
-});
-chrome.alarms.onAlarm.addListener(alarm => { if (alarm.name === 'connect') connect(); });
-chrome.runtime.onStartup.addListener(connect);
-chrome.runtime.onInstalled.addListener(async () => {
-  await chrome.alarms.create('connect', { periodInMinutes: 0.5 });
-  connect();
-});
-chrome.alarms.create('connect', { periodInMinutes: 0.5 });
-connect();
+import { CONNECTION } from './config.generated.js';
+import { createController } from './controller.js';
+import { createConnection } from './connection.js';
+
+let connection;
+const controller = createController(chrome, event => connection?.send(event));
+connection = createConnection(chrome, CONNECTION, controller);

package/extension/connection.js

@@ -0,0 +1,142 @@
+import { compareVersions } from './version.js';
+
+export function createConnection(chrome, CONNECTION, controller) {
+  let socket;
+  let connecting = false;
+  let keepAlive;
+  let reconnect;
+  let status = 'disconnected';
+  let identity;
+  let maintenance = false;
+  let cleanup = Promise.resolve();
+
+  async function release() {
+    const result = await controller.releaseAll();
+    if (result.errors?.length) throw new Error(`Extension cleanup failed: ${result.errors.join('; ')}`);
+  }
+
+  async function prepareReload(version) {
+    const current = chrome.runtime.getManifest().version;
+    if (compareVersions(version, current) <= 0) throw new Error('Reload target must be newer than the running extension');
+    const response = await fetch(chrome.runtime.getURL('manifest.json'), { cache: 'no-store' });
+    if (!response.ok || (await response.json()).version !== version) throw new Error('Extension files do not match the Hub; reload was not attempted');
+    const previous = (await chrome.storage.local.get('reloadAttempt')).reloadAttempt;
+    if (previous?.from === current && previous.target === version) throw new Error('Extension reload did not apply the update; reload manually after checking the extension directory');
+    maintenance = true;
+    await release();
+    await chrome.storage.local.set({ reloadAttempt: { from: current, target: version } });
+  }
+
+  async function getIdentity() {
+    const local = await chrome.storage.local.get(['instanceId', 'profileName']);
+    const session = await chrome.storage.session.get('runId');
+    const instanceId = local.instanceId || crypto.randomUUID();
+    const runId = session.runId || crypto.randomUUID();
+    if (!local.instanceId) await chrome.storage.local.set({ instanceId });
+    if (!session.runId) await chrome.storage.session.set({ runId });
+    const family = /Edg\//.test(navigator.userAgent) ? 'edge' : 'chrome';
+    return { instance_id: instanceId, run_id: runId, family,
+      profile_name: local.profileName || (family === 'edge' ? 'Edge' : 'Chrome'),
+      user_agent: navigator.userAgent, extension_id: chrome.runtime.id, extension_version: chrome.runtime.getManifest().version };
+  }
+
+  async function connect() {
+    if (connecting || socket?.readyState === WebSocket.OPEN) return;
+    connecting = true;
+    try {
+      await cleanup;
+      await release();
+      identity = await getIdentity();
+      const ws = new WebSocket(CONNECTION.url);
+      socket = ws;
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ type: 'hello', token: CONNECTION.token, browser: identity }));
+        keepAlive = setInterval(() => {
+          if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
+        }, 20000);
+      };
+      ws.onmessage = async event => {
+        let request;
+        try {
+          request = JSON.parse(event.data);
+          if (request.type === 'connected') {
+            maintenance = false;
+            status = 'connected';
+            await chrome.storage.local.remove('reloadAttempt');
+            await chrome.action.setBadgeText({ text: 'ON' });
+            await chrome.action.setBadgeBackgroundColor({ color: '#13755b' });
+            return;
+          }
+          if (!request.id) return;
+          let result;
+          if (request.command === 'prepare_upgrade') {
+            maintenance = true;
+            await release();
+            result = { prepared: true };
+          } else if (request.command === 'resume') {
+            maintenance = false;
+            result = { resumed: true };
+          } else if (request.command === 'reload_extension') {
+            await prepareReload(request.arguments?.version);
+            if (ws.readyState !== WebSocket.OPEN) return;
+            ws.send(JSON.stringify({ id: request.id, result: { reloading: true } }));
+            chrome.runtime.reload();
+            return;
+          } else {
+            if (maintenance) throw new Error('Extension is preparing an upgrade');
+            result = await controller.execute(request.owner, request.command, request.arguments || {});
+          }
+          if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ id: request.id, result }));
+        } catch (error) {
+          if (request?.id && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ id: request.id, error: error.message || String(error) }));
+          }
+        }
+      };
+      ws.onclose = () => {
+        clearInterval(keepAlive);
+        status = 'disconnected';
+        connecting = false;
+        cleanup = release().catch(error => { status = error.message; });
+        chrome.action.setBadgeText({ text: 'OFF' }).catch(() => {});
+        scheduleReconnect();
+      };
+      ws.onerror = () => ws.close();
+    } catch (error) {
+      connecting = false;
+      status = error.message;
+      scheduleReconnect();
+    }
+  }
+
+  function scheduleReconnect() {
+    clearTimeout(reconnect);
+    reconnect = setTimeout(connect, 2000);
+  }
+
+  chrome.runtime.onMessage.addListener((message, sender, respond) => {
+    if (sender.id !== chrome.runtime.id) return;
+    if (message.type === 'status') {
+      getIdentity().then(browser => respond({ status, browser, claims: controller.claimedCount() }));
+      return true;
+    }
+    if (message.type === 'reconnect') {
+      if (socket?.readyState === WebSocket.OPEN) socket.close();
+      else connect();
+      respond({ ok: true });
+    }
+    if (message.type === 'release_all') {
+      controller.releaseAll().then(() => respond({ ok: true }));
+      return true;
+    }
+  });
+  chrome.alarms.onAlarm.addListener(alarm => { if (alarm.name === 'connect') connect(); });
+  chrome.runtime.onStartup.addListener(connect);
+  chrome.runtime.onInstalled.addListener(async () => {
+    await chrome.alarms.create('connect', { periodInMinutes: 0.5 });
+    connect();
+  });
+  chrome.alarms.create('connect', { periodInMinutes: 0.5 });
+  connect();
+  return { send(event) { if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(event)); } };
+}

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "BrowserAttach",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Connect existing Chrome and Edge tabs to a locally paired MCP client.",
   "minimum_chrome_version": "125",
   "permissions": [

package/extension/version.js

@@ -0,0 +1,11 @@
+export function compareVersions(a, b) {
+  const parse = value => {
+    if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value)) throw new Error('Invalid BrowserAttach version');
+    const parts = value.split('.').map(Number);
+    if (!parts.every(Number.isSafeInteger)) throw new Error('Invalid BrowserAttach version');
+    return parts;
+  };
+  const left = parse(a), right = parse(b);
+  for (let i = 0; i < left.length; i++) if (left[i] !== right[i]) return Math.sign(left[i] - right[i]);
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evan_zhong/browser-attach",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "MCP for existing signed-in Chrome and Edge tabs through a locally paired extension",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "test": "node --test tests/*.test.mjs",
     "test:live": "node scripts/live-smoke.mjs",
     "test:interaction": "node scripts/interaction-smoke.mjs",
+    "test:upgrade": "node scripts/upgrade-smoke.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "prepack": "node scripts/check-package.mjs"
   },

package/scripts/check-package.mjs

@@ -14,6 +14,7 @@ const names = result.files.map(file => file.path);
 for (const path of names) {
   if (/config\.generated\.js|(^|\/)(\.local|\.venv|test-results|node_modules)\//.test(path)) throw new Error(`Private file included in package: ${path}`);
 }
+for (const path of ['extension/connection.js', 'extension/version.js']) if (!names.includes(path)) throw new Error(`Package is missing ${path}`);
 for (const path of ['bin/browser-attach.mjs', 'src/mcp.mjs', 'src/hub.mjs', 'extension/manifest.json', 'extension/evaluate.js', 'extension/fetch.js', 'extension/locator.js', 'extension/batch.js', 'extension/wait.js', 'extension/outcomes.js', 'extension/scroll.js', 'extension/drag.js', 'extension/text.js', 'extension/diagnostics.js', 'extension/sessions.js', 'extension/actionability.js', 'extension/limits.js', 'extension/icons/BrowserAttach.png']) {
   if (!names.includes(path)) throw new Error(`Package is missing ${path}`);
 }

package/src/client.mjs

@@ -5,43 +5,86 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import WebSocket from 'ws';
 import { loadConfig, VERSION } from './config.mjs';
+import { compareVersions } from '../extension/version.js';
 
-export async function hubIsRunning(config) {
+async function hubHealth(config) {
   let response;
   try {
     response = await fetch(`http://127.0.0.1:${config.port}/health`, {
       headers: { Authorization: `Bearer ${config.token}` }, signal: AbortSignal.timeout(1000),
     });
   } catch (error) {
-    if (error.cause?.code === 'ECONNREFUSED' || error.name === 'TimeoutError') return false;
+    if (['ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'UND_ERR_SOCKET'].includes(error.cause?.code) || error.name === 'TimeoutError') return null;
     throw error;
   }
   if (!response.ok) throw new Error('BrowserAttach port is occupied by an unpaired service');
   const health = await response.json();
-  if (health.service !== 'browser-attach' || health.version !== VERSION)
-    throw new Error('Hub version differs from this package; stop the hub and start again.');
-  return true;
+  if (health.service !== 'browser-attach') throw new Error('BrowserAttach port is occupied by another service');
+  compareVersions(health.version, VERSION);
+  return health;
+}
+
+export async function hubIsRunning(config) {
+  const health = await hubHealth(config);
+  if (!health) return false;
+  if (health.version !== VERSION) throw new Error(`Hub ${health.version} differs from this package ${VERSION}; reconnect MCP to coordinate an upgrade`);
+  return health.state === 'ready';
 }
 
 export async function ensureHub(configPath) {
   configPath = resolve(configPath);
   const config = await loadConfig(configPath);
-  if (await hubIsRunning(config)) return config;
+  const deadline = Date.now() + 18000;
+  const expected = new Set();
+  let spawned = false, requested = false, readyAfter = 0, spawnError;
+  while (Date.now() < deadline) {
+    if (spawnError) throw spawnError;
+    const health = await hubHealth(config);
+    if (!health) {
+      if (!spawned) {
+        spawned = true;
+        await spawnHub(configPath, error => { spawnError = error; });
+        readyAfter = Date.now() + 2500;
+      }
+    } else {
+      const comparison = compareVersions(health.version, VERSION);
+      if (comparison > 0) throw new Error(`Hub ${health.version} is newer than this package ${VERSION}; refusing to downgrade`);
+      if (comparison < 0 && health.state == null) {
+        throw new Error(`Hub ${health.version} predates coordinated upgrades; run browser-attach stop, restart MCP, and reload the extension manually if it was already loaded`);
+      }
+      if (comparison < 0 && health.state === 'ready' && !requested) {
+        requested = true;
+        for (const item of health.extensions) expected.add(item.instance_id);
+        const response = await fetch(`http://127.0.0.1:${config.port}/upgrade`, { method: 'POST',
+          headers: { Authorization: `Bearer ${config.token}`, 'X-Browser-Attach-Version': VERSION }, signal: AbortSignal.timeout(10000) });
+        const result = await response.json();
+        if (!response.ok) {
+          const current = await hubHealth(config);
+          if (current && compareVersions(current.version, VERSION) < 0 && !['upgrading', 'stopping'].includes(current.state)) throw new Error(result.error);
+        } else for (const id of result.extensions) expected.add(id);
+      } else if (comparison < 0 && health.state === 'ready' && requested) {
+        throw new Error(health.upgrade_error || 'Hub upgrade did not complete; reconnect MCP to retry');
+      } else if (comparison === 0 && health.state === 'ready') {
+        const failure = health.extensions.find(item => item.error);
+        if (failure) throw new Error(`Extension upgrade failed (${failure.instance_id}): ${failure.error}`);
+        for (const item of health.extensions) if (item.ready) expected.delete(item.instance_id);
+        if (!expected.size && health.extensions.every(item => item.ready) && Date.now() >= readyAfter) return config;
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 150));
+  }
+  throw new Error(`Hub/extension upgrade did not become ready${expected.size ? `; waiting for ${[...expected].join(', ')}` : ''}. See ${join(dirname(configPath), 'hub.log')}`);
+}
+
+async function spawnHub(configPath, onError) {
   await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
   const log = await open(join(dirname(configPath), 'hub.log'), 'a', 0o600);
   const child = spawn(process.execPath, [fileURLToPath(new URL('../bin/browser-attach.mjs', import.meta.url)), 'hub', '--config', configPath], {
     detached: true, windowsHide: true, stdio: ['ignore', log.fd, log.fd],
     env: { ...process.env, BROWSER_ATTACH_HOME: dirname(configPath) },
   });
-  let spawnError;
-  child.on('error', error => { spawnError = error; });
+  child.on('error', onError);
   child.unref(); await log.close();
-  for (let i = 0; i < 40; i++) {
-    if (spawnError) throw spawnError;
-    await new Promise(resolve => setTimeout(resolve, 150));
-    if (await hubIsRunning(config)) return config;
-  }
-  throw new Error(`Hub did not start. See ${join(dirname(configPath), 'hub.log')}`);
 }
 
 export class AttachClient {
@@ -51,7 +94,7 @@ export class AttachClient {
     if (this.connecting) return this.connecting;
     this.connecting = new Promise((resolve, reject) => {
       const ws = new WebSocket(`ws://127.0.0.1:${this.config.port}/client`, {
-        headers: { Authorization: `Bearer ${this.config.token}` }, maxPayload: 24 * 1024 * 1024,
+        headers: { Authorization: `Bearer ${this.config.token}`, 'X-Browser-Attach-Version': VERSION }, maxPayload: 24 * 1024 * 1024,
       });
       this.socket = ws;
       ws.once('open', resolve); ws.once('error', reject);

package/src/config.mjs

@@ -15,13 +15,17 @@ export const DATA_DIR = configuredHome
   : process.platform === 'win32' ? join(homedir(), '.browser-attach')
     : join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'browser-attach');
 export const DEFAULT_CONFIG = join(DATA_DIR, 'config.json');
-export const VERSION = '0.16.0';
+export const VERSION = '0.17.0';
 
 export async function loadConfig(path = DEFAULT_CONFIG) {
   let config;
   try { config = JSON.parse(await readFile(path, 'utf8')); }
   catch (error) { throw new Error(`Cannot read pairing config ${path}${error.code ? ` (${error.code})` : ''}. Run browser-attach setup.`, { cause: error }); }
+  // Pre-0.17 pairings did not record the extension directory; their setup default
+  // was a sibling `extension` directory next to the pairing file.
+  if (config.extension_dir === undefined) config.extension_dir = join(dirname(resolve(path)), 'extension');
   if (typeof config.token !== 'string' || config.token.length < 32 ||
+      typeof config.extension_dir !== 'string' || !isAbsolute(config.extension_dir) ||
       !Number.isInteger(config.port) || config.port < 1024 || config.port > 65535 ||
       !/^[a-p]{32}$/.test(config.extension_id)) throw new Error('Invalid pairing config. Run browser-attach setup.');
   return config;

package/src/hub.mjs

@@ -3,6 +3,8 @@ import http from 'node:http';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { WebSocketServer, WebSocket } from 'ws';
 import { VERSION } from './config.mjs';
+import { syncExtension } from './setup.mjs';
+import { compareVersions } from '../extension/version.js';
 
 const MAX_MESSAGE = 24 * 1024 * 1024;
 const OPERATIONS = new Set(['release_tab', 'activate_tab', 'close_tab', 'snapshot', 'read_text', 'type', 'hover', 'drag', 'wait', 'select_option', 'click', 'fill', 'press_key', 'batch', 'scroll', 'navigate', 'screenshot', 'handle_dialog', 'upload_file', 'evaluate', 'logs']);
@@ -12,6 +14,8 @@ const send = (ws, data) => { if (ws.readyState === WebSocket.OPEN) ws.send(JSON.
 
 export async function startHub(config, { port = config.port, operationTimeout = HUB_OPERATION_TIMEOUT_MS } = {}) {
   const browsers = new Map(), clients = new Set(), claims = new Map(), tabClaims = new Map(), queues = new Map();
+  const cleanups = new Set();
+  let state = 'starting', upgradeError;
   const authorized = token => typeof token === 'string' && Buffer.byteLength(token) === Buffer.byteLength(config.token)
     && timingSafeEqual(Buffer.from(token), Buffer.from(config.token));
   const bearer = request => authorized(request.headers.authorization?.replace(/^Bearer /, ''));
@@ -28,13 +32,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
     result.then(done, done);
     return result;
   }
-  function requestBrowser(browser, owner, command, args) {
+  function requestBrowser(browser, owner, command, args, timeout = operationTimeout) {
     return new Promise((resolve, reject) => {
       const id = randomUUID();
       const timer = setTimeout(() => {
         browser.pending.delete(id);
         reject(new OperationTimeout('Browser operation timed out; outcome may be unknown. Connection will release its tabs. List and claim again.'));
-      }, operationTimeout);
+      }, timeout);
       browser.pending.set(id, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
       if (browser.ws.readyState !== WebSocket.OPEN) {
         clearTimeout(timer); browser.pending.delete(id); reject(new Error('Browser disconnected')); return;
@@ -44,12 +48,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
   }
   async function execute(owner, observed, method, args) {
     if (method === 'list_browsers') return {
-      browsers: [...browsers.values()].map(browser => ({ browser_id: browser.id, ...browser.info, capabilities: CAPABILITIES })),
+      browsers: [...browsers.values()].filter(browser => browser.ready).map(browser => ({ browser_id: browser.id, ...browser.info, capabilities: CAPABILITIES })),
+      upgrades: [...browsers.values()].filter(browser => !browser.ready).map(browser => ({ instance_id: browser.info.instance_id, version: browser.info.extension_version, error: browser.upgradeError })),
       hint: 'Load the paired extension in each Chrome/Edge profile if empty.',
     };
     if (method === 'list_tabs' || method === 'claim_tab' || method === 'open_tab' || method === 'fetch') {
       const browser = browsers.get(args.browser_id);
-      if (!browser) throw new Error('Browser is not connected; call browser_discover kind=browsers again');
+      if (!browser?.ready) throw new Error('Browser is not connected; call browser_discover kind=browsers again');
       if (method === 'open_tab' || method === 'fetch') return await requestBrowser(browser, owner, method, args);
       if (method === 'list_tabs') {
         const result = await requestBrowser(browser, owner, method, {});
@@ -93,10 +98,36 @@ export async function startHub(config, { port = config.port, operationTimeout =
   }
 
   let closing;
-  const server = http.createServer((request, response) => {
+  const server = http.createServer(async (request, response) => {
     if (request.headers.origin || !bearer(request)) { response.writeHead(403).end(); return; }
     response.setHeader('Content-Type', 'application/json');
-    if (request.url === '/health' && request.method === 'GET') response.end(JSON.stringify({ service: 'browser-attach', version: VERSION, browsers: browsers.size }));
+    if (request.url === '/health' && request.method === 'GET') response.end(JSON.stringify({ service: 'browser-attach', version: VERSION, state,
+      browsers: [...browsers.values()].filter(browser => browser.ready).length, clients: clients.size, upgrade_error: upgradeError,
+      extensions: [...browsers.values()].map(browser => ({ instance_id: browser.info.instance_id, version: browser.info.extension_version, ready: browser.ready, error: browser.upgradeError })) }));
+    else if (request.url === '/upgrade' && request.method === 'POST') {
+      try {
+        const target = request.headers['x-browser-attach-version'];
+        if (compareVersions(target, VERSION) <= 0) { response.writeHead(409).end(JSON.stringify({ error: 'Upgrade target must be newer than this Hub' })); return; }
+        if (state !== 'ready' || clients.size || cleanups.size || [...browsers.values()].some(browser => browser.pending.size)) {
+          response.writeHead(409).end(JSON.stringify({ error: 'Hub is in use; close other MCP connections and retry the upgrade' })); return;
+        }
+        state = 'upgrading';
+        upgradeError = undefined;
+        const connected = [...browsers.values()];
+        const outcomes = await Promise.allSettled(connected.map(async browser => {
+          const result = await requestBrowser(browser, null, 'prepare_upgrade', {}, 8000);
+          if (result.errors?.length || result.prepared !== true) throw new Error(result.errors?.join('; ') || 'Extension did not confirm cleanup');
+        }));
+        const failed = outcomes.find(item => item.status === 'rejected');
+        if (failed) {
+          await Promise.allSettled(connected.map(browser => requestBrowser(browser, null, 'resume', {}, 1000)));
+          upgradeError = `Extension cleanup failed: ${failed.reason.message}`;
+          state = 'ready'; throw new Error(upgradeError);
+        }
+        response.end(JSON.stringify({ stopping: true, extensions: connected.map(browser => browser.info.instance_id) }));
+        setImmediate(() => close());
+      } catch (error) { response.writeHead(409).end(JSON.stringify({ error: error.message })); }
+    }
     else if (request.url === '/shutdown' && request.method === 'POST') {
       response.end('{"stopping":true}'); setImmediate(() => close());
     } else response.writeHead(404).end();
@@ -105,8 +136,9 @@ export async function startHub(config, { port = config.port, operationTimeout =
   server.on('upgrade', (request, socket, head) => {
     const extension = request.url === '/extension';
     const valid = extension ? request.headers.origin === `chrome-extension://${config.extension_id}`
-      : request.url === '/client' && !request.headers.origin && bearer(request);
+      : request.url === '/client' && !request.headers.origin && bearer(request) && request.headers['x-browser-attach-version'] === VERSION;
     if (!valid) { socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); return; }
+    if (state !== 'ready') { socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n'); return; }
     wss.handleUpgrade(request, socket, head, ws => {
       ws.on('pong', () => { ws.isAlive = true; });
       if (extension) connectExtension(ws); else connectClient(ws);
@@ -120,18 +152,23 @@ export async function startHub(config, { port = config.port, operationTimeout =
       try {
         const data = JSON.parse(raw.toString());
         if (!browser) {
+          if (state !== 'ready') { ws.close(1013, 'Hub is preparing an upgrade'); return; }
           const info = data.browser;
-          if (data.type !== 'hello' || !authorized(data.token) || !info || info.extension_version !== VERSION || !['chrome', 'edge'].includes(info.family) ||
+          if (data.type !== 'hello' || !authorized(data.token) || !info || !['chrome', 'edge'].includes(info.family) ||
               !['instance_id', 'run_id', 'profile_name'].every(key => typeof info[key] === 'string' && info[key].length >= 1 && info[key].length <= 128))
             throw new Error('Invalid pairing or browser identity');
           const id = `${info.instance_id}:${info.run_id}`;
           if (browsers.has(id)) throw new Error('Browser instance is already connected');
-          browser = { id, ws, info, pending: new Map() };
+          const comparison = compareVersions(info.extension_version, VERSION);
+          if (comparison > 0) throw new Error('Extension is newer than this Hub');
+          browser = { id, ws, info, ready: comparison === 0, pending: new Map() };
           browsers.set(id, browser); clearTimeout(helloTimer);
-          send(ws, { type: 'connected', browser_id: id }); return;
+          if (browser.ready) send(ws, { type: 'connected', browser_id: id });
+          else requestBrowser(browser, null, 'reload_extension', { version: VERSION }).catch(error => { browser.upgradeError = error.message; });
+          return;
         }
         if (data.type === 'ping') send(ws, { type: 'pong' });
-        else if (data.type === 'detached') forget(tabClaims.get(keyFor(browser.id, data.tab_id)));
+        else if (browser.ready && data.type === 'detached') forget(tabClaims.get(keyFor(browser.id, data.tab_id)));
         else if (browser.pending.has(data.id)) {
           const pending = browser.pending.get(data.id); browser.pending.delete(data.id);
           if ('error' in data) pending.reject(new Error(String(data.error))); else pending.resolve(data.result || {});
@@ -168,10 +205,13 @@ export async function startHub(config, { port = config.port, operationTimeout =
     });
     ws.on('close', () => {
       disconnected = true; clients.delete(ws);
-      chain.finally(async () => {
-        await Promise.allSettled([...browsers.values()].map(browser => requestBrowser(browser, owner, 'release_owner', {})));
-        for (const [handle, claim] of claims) if (claim.owner === owner) forget(handle);
-      });
+      const cleanup = chain.then(async () => {
+        await Promise.allSettled([...browsers.values()].filter(browser => browser.ready).map(async browser => {
+          const result = await requestBrowser(browser, owner, 'release_owner', {});
+          if (!result.errors?.length) for (const [handle, claim] of claims) if (claim.owner === owner && claim.browser_id === browser.id) forget(handle);
+        }));
+      }).finally(() => cleanups.delete(cleanup));
+      cleanups.add(cleanup);
     });
   }
   const heartbeat = setInterval(() => {
@@ -183,6 +223,7 @@ export async function startHub(config, { port = config.port, operationTimeout =
   async function close() {
     if (closing) return closing;
     closing = (async () => {
+      state = 'stopping';
       clearInterval(heartbeat);
       for (const ws of wss.clients) ws.close(1001, 'Hub stopped');
       const timer = setTimeout(() => { for (const ws of wss.clients) ws.terminate(); }, 1000);
@@ -191,7 +232,11 @@ export async function startHub(config, { port = config.port, operationTimeout =
     })();
     return closing;
   }
-  try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); }); }
-  catch (error) { clearInterval(heartbeat); wss.close(); throw error; }
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+    config.port = server.address().port;
+    if (config.extension_dir) await syncExtension(config);
+    state = 'ready';
+  } catch (error) { await close(); throw error; }
   return { server, close, port: server.address().port, claims, browsers };
 }

package/src/mcp.mjs

@@ -194,6 +194,7 @@ export function createMcp(client) {
 
 export async function runMcp(configPath) {
   const client = new AttachClient(await ensureHub(configPath));
+  await client.connect();
   const server = createMcp(client);
   const transport = new StdioServerTransport();
   transport.onclose = () => client.close();

package/src/setup.mjs

@@ -1,9 +1,10 @@
 import { randomBytes, createHash } from 'node:crypto';
-import { cp, mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
+import { cp, copyFile, mkdir, mkdtemp, readFile, writeFile, chmod, rename, rm, rmdir, readdir, stat } from 'node:fs/promises';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { execFileSync } from 'node:child_process';
-import { ROOT, DEFAULT_CONFIG, loadConfig, writeJson } from './config.mjs';
+import { ROOT, DEFAULT_CONFIG, VERSION, loadConfig, writeJson } from './config.mjs';
+import { compareVersions } from '../extension/version.js';
 
 export const mcpSettings = (configPath = DEFAULT_CONFIG) => ({ command: process.execPath,
   args: [join(ROOT, 'bin/browser-attach.mjs'), 'mcp', '--config', resolve(configPath)],
@@ -19,33 +20,103 @@ async function privateDirectory(path) {
   } else await chmod(path, 0o700);
 }
 
-export async function setup({ configPath = DEFAULT_CONFIG, extensionDir, port = 47831 } = {}) {
+export async function setup({ configPath = DEFAULT_CONFIG, extensionDir, port } = {}) {
   configPath = resolve(configPath);
-  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('port must be 1024..65535');
   await privateDirectory(dirname(configPath));
-  extensionDir = resolve(extensionDir || join(dirname(configPath), 'extension'));
-  if (extensionDir !== resolve(ROOT, 'extension')) {
-    await cp(join(ROOT, 'extension'), extensionDir, { recursive: true, filter: source => !source.endsWith('config.generated.js') });
-  }
-  await privateDirectory(extensionDir);
-  const manifestPath = join(extensionDir, 'manifest.json');
-  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const manifest = JSON.parse(await readFile(join(ROOT, 'extension/manifest.json'), 'utf8'));
   const extensionId = [...createHash('sha256').update(Buffer.from(manifest.key, 'base64')).digest('hex').slice(0, 32)]
     .map(char => String.fromCharCode(97 + parseInt(char, 16))).join('');
   let config;
   try { config = await loadConfig(configPath); }
   catch (error) { if (error.cause?.code !== 'ENOENT') throw error; }
+  port ??= config?.port ?? 47831;
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('port must be 1024..65535');
+  extensionDir = resolve(extensionDir || config?.extension_dir || join(dirname(configPath), 'extension'));
+  const configRelative = relative(extensionDir, configPath);
+  if (dirname(extensionDir) === extensionDir || (!isAbsolute(configRelative) && configRelative !== '..' && !configRelative.startsWith('..' + sep)))
+    throw new Error('Choose a dedicated extension directory outside the pairing file');
   config ||= { port, token: randomBytes(48).toString('base64url'), extension_id: extensionId };
   if (config.port !== port || config.extension_id !== extensionId) throw new Error('Pairing differs from requested port/extension. Stop the hub and remove the pairing config before a fresh setup.');
+  if (config.extension_dir && resolve(config.extension_dir) !== extensionDir) throw new Error('Use the paired extension directory, or a separate pairing config for a different directory.');
   config.extension_dir = extensionDir;
-  manifest.content_security_policy = { extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${port}` };
-  await writeJson(manifestPath, manifest);
-  await writeFile(join(extensionDir, 'config.generated.js'), '// Machine-local pairing secret. Never publish.\nexport const CONNECTION = ' +
-    JSON.stringify({ url: `ws://127.0.0.1:${port}/extension`, token: config.token }) + ';\n', { mode: 0o600 });
   await writeJson(configPath, config);
   return { config, configPath, extensionDir };
 }
 
+// Only the Hub holding the listening port may replace the stable copy.
+export async function syncExtension(config) {
+  const source = resolve(ROOT, 'extension'), destination = resolve(config.extension_dir);
+  const manifest = JSON.parse(await readFile(join(source, 'manifest.json'), 'utf8'));
+  const backup = destination + '.previous';
+  async function installed(directory) {
+    try {
+      const value = JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8'));
+      if (value.key !== manifest.key) throw new Error(`Unrecognized extension directory: ${directory}`);
+      return value;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try { if ((await readdir(directory)).length) throw new Error(`Unrecognized extension directory: ${directory}`); }
+      catch (missing) { if (missing.code !== 'ENOENT') throw missing; }
+      return null;
+    }
+  }
+  async function files(directory) {
+    const entries = await readdir(directory, { recursive: true });
+    const kinds = await Promise.all(entries.map(path => stat(join(directory, path))));
+    return entries.filter((_, index) => kinds[index].isFile());
+  }
+  async function install(directory) {
+    await privateDirectory(destination);
+    const incoming = await files(directory), existing = await files(destination);
+    // Keep the loaded directory itself stable and commit its manifest last.
+    for (const path of incoming.filter(path => path !== 'manifest.json')) {
+      const target = join(destination, path);
+      await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+      await copyFile(join(directory, path), target + '.updating');
+      await rename(target + '.updating', target);
+    }
+    for (const path of existing) if (!incoming.includes(path)) await rm(join(destination, path));
+    await writeJson(join(destination, 'manifest.json'), JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8')));
+  }
+  let current = await installed(destination);
+  if (current && compareVersions(current.version, VERSION) > 0) throw new Error('Refusing to downgrade the installed extension');
+  const previous = destination === source ? null : await installed(backup);
+  if (previous) {
+    await install(backup);
+    current = previous;
+    await rm(backup, { recursive: true });
+  }
+  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+  const stage = destination === source ? source : await mkdtemp(destination + '.staging-');
+  try {
+    if (stage !== source) await cp(source, stage, { recursive: true, filter: path => !path.endsWith('config.generated.js') });
+    await privateDirectory(stage);
+    manifest.content_security_policy = { extension_pages: `script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:${config.port}` };
+    await writeJson(join(stage, 'manifest.json'), manifest);
+    await writeFile(join(stage, 'config.generated.js'), '// Machine-local pairing secret. Never publish.\nexport const CONNECTION = ' +
+      JSON.stringify({ url: `ws://127.0.0.1:${config.port}/extension`, token: config.token }) + ';\n', { mode: 0o600 });
+    if (stage !== source) {
+      if (current) {
+        await privateDirectory(stage + '.previous');
+        await cp(destination, stage + '.previous', { recursive: true });
+        await rename(stage + '.previous', backup);
+      } else {
+        try { await rmdir(destination); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        await rename(stage, destination);
+        return;
+      }
+      try { await install(stage); }
+      catch (error) { if (current) await install(backup); throw error; }
+      if (current) await rm(backup, { recursive: true });
+    }
+  } finally {
+    if (stage !== source) {
+      await rm(stage, { recursive: true, force: true });
+      await rm(stage + '.previous', { recursive: true, force: true });
+    }
+  }
+}
+
 export async function configureNosis(directory = join(homedir(), '.nosis'), { configPath = DEFAULT_CONFIG } = {}) {
   const path = join(directory, 'agent_config.json');
   const data = JSON.parse((await readFile(path, 'utf8')).replace(/^\uFEFF/, ''));