@evan_zhong/browser-attach 0.15.0 → 0.17.0

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

@@ -10,6 +10,8 @@ import { scrollOptions } from '../extension/scroll.js';
 import { selectOptions, typeOptions } from '../extension/input.js';
 import { targetOptions } from '../extension/locator.js';
 import { fetchOptions } from '../extension/fetch.js';
+import { clickOptions } from '../extension/click.js';
+import { offsetOption } from '../extension/motion.js';
 
 const text = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
 function integerRange(name, min, max) {
@@ -34,6 +36,10 @@ export function createMcp(client) {
   const target = { ...frameScope, ref: z.string().optional(), ...selector, frame_id: z.string().optional().describe('Selector scope; defaults to main frame.'),
     nth: integerRange('nth', 0, Number.MAX_SAFE_INTEGER).optional().describe('Zero-based selector match index in document order.') };
   const inputTimeout = { ...dialogPolicy, timeout_ms: integerRange('timeout_ms', 100, 30000).default(5000).describe('Covers preparation, dispatch and verification.') };
+  const timing = name => z.union([integerRange(name, 0, 1000), z.tuple([integerRange(name, 0, 1000), integerRange(name, 0, 1000)]).refine(([min, max]) => min <= max, 'Use an ordered [min, max] pair')]);
+  const offset = { offset: z.object({ x_ratio: z.number().min(0).max(1), y_ratio: z.number().min(0).max(1) }).strict().optional().describe('Native element only: ratios within its content quad; offscreen/covered points fail.') };
+  const settle = { settle_ms: timing('settle_ms').optional().describe('Pause after target preparation, before dispatch: fixed ms or uniform [min, max].') };
+  const typeDelay = timing('delay_ms').default(0).describe('Between characters: fixed ms or independently sampled uniform [min, max].');
   function tool(name, description, schema, method, transform) {
     server.registerTool(`browser_${name}`, { description, inputSchema: z.object(schema) }, async args => {
       try {
@@ -86,12 +92,14 @@ export function createMcp(client) {
     if (args.focus_window != null) throw new Error('focus_window is only valid for action=activate');
     return { tab_handle: args.tab_handle };
   });
-  tool('snapshot', 'Read an AX tree with refs and frame coverage. next_cursor continues the same observation with unchanged view options.', {
+  tool('snapshot', 'Read an AX tree with refs and frame coverage, or find nodes by query without returning the whole tree. A new observation replaces refs; next_cursor continues unchanged view options.', {
     ...handle, max_nodes: integerRange('max_nodes', 1, 3000).default(600),
     max_chars: integerRange('max_chars', 1, 2000000).default(24000), cursor: z.string().optional(),
     profile: z.enum(['full', 'interactive']).optional().describe('Default full; interactive keeps controls, focusable/editable nodes and ancestors.'),
     text: z.boolean().optional().describe('Default true; false hides prose, preserving control names and values.'),
     text_limit: integerRange('text_limit', 0, 10000).optional().describe('Prose preview length, marked with …; control names/values stay complete. Default 80 for interactive, unlimited for full.'),
+    query: z.string().min(1).max(2000).optional().describe('Case-insensitive literal substring of AX names/values in this view, before text previews. Returns matching lines and refs; zero matches is not an error. Uses normal budgets/cursor.'),
+    verbose: z.boolean().default(false).describe('Include viewport and snapshot_id.'),
   });
   tool('read_text', 'Read rendered page/frame text, optionally scoped to a selector. mode=value reads a field; mode=editor reads a Monaco/CodeMirror 5 model. complete_source reports completeness; next_offset continues live text, which may change.', {
     ...handle, ...selector, ...frameScope, mode: z.enum(['visible', 'text_content', 'value', 'editor']).default('visible'),
@@ -120,17 +128,21 @@ export function createMcp(client) {
     return args;
   });
   tool('click', 'Click one ref, selector or x/y; element targets auto-scroll. Native mode verifies the hit target; native select hits require select_option.', {
+    ...offset, ...settle,
     ...handle, ...inputTimeout, ...target, button: z.enum(['left', 'middle', 'right']).default('left'), click_count: z.union([z.literal(1), z.literal(2)]).default(1), modifiers: z.array(z.enum(['Alt', 'Control', 'Meta', 'Shift'])).default([]), x: z.number().optional(), y: z.number().optional(), coordinate_space: z.enum(['viewport', 'document']).optional().describe('Coordinates only; document scrolls the top-level page first.'), mode: z.enum(['native', 'dom']).default('native').describe('DOM click requires an element target and a left single click without modifiers.'),
   }, null, args => {
     targetOptions(args, { coordinates: true });
+    clickOptions(args);
     if (args.mode === 'dom' && !args.ref && !args.selector) throw new Error('DOM click requires ref or selector; coordinates are unsupported.');
     return args;
   });
   tool('hover', 'Move the native pointer to a ref, selector or x/y without clicking; verify trusted mousemove and leave it at the target.', {
+    ...offset,
     ...handle, ...inputTimeout, ...target, x: z.number().optional(), y: z.number().optional(), coordinate_space: z.enum(['viewport', 'document']).optional(),
-  }, null, args => { targetOptions(args, { coordinates: true }); return args; });
-  const dragTarget = z.object({ ...target, x: z.number().optional(), y: z.number().optional(), coordinate_space: z.enum(['viewport', 'document']).optional() }).strict();
+  }, null, args => { targetOptions(args, { coordinates: true }); offsetOption(args); return args; });
+  const dragTarget = z.object({ ...target, ...offset, x: z.number().optional(), y: z.number().optional(), coordinate_space: z.enum(['viewport', 'document']).optional() }).strict();
   tool('drag', 'Perform one native pointer or HTML5 drag; destination auto-scrolls into view while held.', {
+    ...settle, trajectory: z.object({ curve_px: z.number().min(-100).max(100), duration_ms: integerRange('duration_ms', 100, 5000) }).strict().optional().describe('Opt in to curved, variable-speed steps and varied intervals. Signed curve control-point offset in CSS px; duration covers interpolation waits only.'),
     ...handle, ...inputTimeout, source: dragTarget, destination: dragTarget, mode: z.enum(['pointer', 'html5']).default('pointer').describe('pointer for mouse-driven dragging; html5 for HTML drag-and-drop.'), steps: integerRange('steps', 2, 100).default(20),
   }, null, args => { dragOptions(args); return args; });
   tool('wait', 'Wait without scrolling or input. actionable requires a stable, visible, enabled, unobscured target in the viewport; network_idle uses observed page requests. Timeout includes the last observed state.', {
@@ -140,7 +152,7 @@ export function createMcp(client) {
   tool('select_option', 'Set one HTML select option without native UI, using synthetic input/change (events_trusted=false). Verifies retained selection only.', {
     ...handle, ...inputTimeout, ...target, value: z.string().optional().describe('Choose exactly one of value, label or zero-based index; value/label match exactly.'), label: z.string().optional(), index: integerRange('index', 0, Number.MAX_SAFE_INTEGER).optional(),
   }, null, args => { targetOptions(args); selectOptions(args); return args; });
-  tool('type', 'Type printable characters at the current selection using trusted key events, without clearing the field. Stops on lost focus or detachment.', { ...handle, ...inputTimeout, ...target, text: z.string().max(10000), delay_ms: integerRange('delay_ms', 0, 1000).default(0).describe('Pause between characters.') }, null, args => { targetOptions(args); typeOptions(args); return args; });
+  tool('type', 'Type printable characters at the current selection using trusted key events, without clearing the field. Stops on lost focus or detachment.', { ...handle, ...inputTimeout, ...target, text: z.string().max(10000), delay_ms: typeDelay }, null, args => { targetOptions(args); typeOptions(args); return args; });
   tool('fill', 'Replace input/textarea/contenteditable text. Native mode focuses/selects and inserts text without character keydown; DOM mode sets text without focus and emits input/change. Does not blur or commit dropdown selections.', { ...handle, ...inputTimeout, ...target, text: z.string(), mode: z.enum(['native', 'dom']).default('native') }, null, args => { targetOptions(args); return args; });
   const batchTarget = { ...selector, selector: z.string().min(1).max(10000), ...frameScope, nth: target.nth };
   const scrollFields = { until: z.object({ text: z.string().min(1).max(2000), selector: z.string().min(1).optional() }).strict().optional(), max_steps: integerRange('max_steps', 1, 500).default(100), mode: z.enum(['dom', 'wheel']).default('dom'), delta_y: z.number().optional().describe('Positive scrolls down.'), delta_x: z.number().default(0), x: z.number().optional(), y: z.number().optional() };
@@ -149,10 +161,11 @@ export function createMcp(client) {
     ...handle, ...dialogPolicy, start_at: integerRange('start_at', 0, 19).default(0).describe('Explicitly skip a reviewed completed prefix.'), timeout_ms: integerRange('timeout_ms', 100, 30000).default(15000),
     steps: z.array(z.discriminatedUnion('action', [
       z.object({ action: z.literal('click'), ...stepOptions, ...batchTarget, mode: z.enum(['native', 'dom']).default('native'),
+        ...offset, ...settle,
         button: z.enum(['left', 'middle', 'right']).default('left'), click_count: z.union([z.literal(1), z.literal(2)]).default(1), modifiers: z.array(z.enum(['Alt', 'Control', 'Meta', 'Shift'])).default([]) }).strict(),
       z.object({ action: z.literal('fill'), ...stepOptions, ...batchTarget, text: z.string(), mode: z.enum(['native', 'dom']).default('native') }).strict(),
-      z.object({ action: z.literal('type'), ...stepOptions, ...batchTarget, text: z.string().max(10000), delay_ms: integerRange('delay_ms', 0, 1000).default(0) }).strict(),
-      z.object({ action: z.literal('hover'), ...stepOptions, ...batchTarget }).strict(),
+      z.object({ action: z.literal('type'), ...stepOptions, ...batchTarget, text: z.string().max(10000), delay_ms: typeDelay }).strict(),
+      z.object({ action: z.literal('hover'), ...stepOptions, ...batchTarget, ...offset }).strict(),
       z.object({ action: z.literal('select_option'), ...stepOptions, ...batchTarget, value: z.string().optional(), label: z.string().optional(), index: integerRange('index', 0, Number.MAX_SAFE_INTEGER).optional() }).strict(),
       z.object({ action: z.literal('scroll'), ...stepOptions, ...selector, ...frameScope, nth: target.nth, ...scrollFields }).strict(),
       z.object({ action: z.literal('wait'), ...stepOptions, ...selector, ...frameScope, nth: target.nth, condition: z.enum(['attached', 'visible', 'actionable', 'text', 'url', 'network_idle']), expected: z.string().optional(), previous: z.string().optional(), idle_ms: integerRange('idle_ms', 100, 10000).default(500) }).strict(),
@@ -181,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/, ''));