browserzap 0.5.0 → 0.6.0

package/bridge-server/resolvers.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const { LIMITS } = require('./limits');
+
+/**
+ * Resolver engine — the registry (0.6.0, D-37).
+ *
+ * Pure: no I/O, no page access, no timers, no clocks. Given a failed (or
+ * ineffective) workflow step and the envelope the extension returned, say what
+ * the step is blocked on and what would clear it. The runner then waits for
+ * that condition as an ordinary `wait_for_state` call and retries the same
+ * step — so every wait and every retry still goes through the normal tool path
+ * and extension policy.
+ *
+ * Design: docs/NEXT_RELEASE_SCOPE_0.6.md (§3 of the 0.5 doc);
+ * the wait kinds it relies on: docs/ADR/ADR-007-waiting-and-timeouts.md.
+ *
+ * Adding a resolver is one entry here plus a fixture that fails without it.
+ * The validation rules at the bottom are checked by tests/resolvers.test.mjs.
+ */
+
+/** A change here that alters behaviour resets learned demotions (step profile). */
+const REGISTRY_VERSION = 1;
+
+/**
+ * Codes that are never auto-resolved: a person, a policy, or a unique target is
+ * needed. A resolver that claimed one of these would be guessing.
+ */
+const FORBIDDEN_CODES = Object.freeze([
+  'USER_CONFIRMATION_REQUIRED',
+  'USER_ACTION_REQUIRED',
+  'POLICY_BLOCKED',
+  'TARGET_AMBIGUOUS',
+]);
+
+/** Risks that must never be repeated in place (audit AU-08). */
+const CONSEQUENTIAL_RISKS = new Set(['external_side_effect', 'destructive', 'financial']);
+
+/** Tools a resolver may retry in place. A read-only tool is never a workflow step. */
+const RETRYABLE_TOOLS = new Set([
+  'browser_navigate', 'element_click', 'field_fill', 'select_option', 'wait_for_state', 'browser_press_key',
+]);
+
+/**
+ * Failures that prove the action never ran: the target was missing, unusable or
+ * a stale ref. Only these may be retried for a click or a key press; anything
+ * else may already have submitted something (AU-08).
+ */
+const ACTION_DID_NOT_RUN_CODES = new Set(['TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT']);
+
+/**
+ * Failures a resolver may act on: the page has not got there yet. Anything else
+ * — a bad argument, a Pro gate, a missing workflow, a cancelled run — is
+ * deterministic, and waiting for the page cannot change it (ADR-007: only
+ * failures that can clear up are waited on). A successful call that changed
+ * nothing has no code at all and is classified by its evidence.
+ */
+const TRANSIENT_CODES = Object.freeze([
+  'TIMEOUT', 'TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT',
+  'NAVIGATION_FAILED', 'BRIDGE_DISCONNECTED', 'POSTCONDITION_NOT_MET', 'SITE_ERROR',
+]);
+
+/** The wait kinds the extension understands (registered in doWaitFor). */
+const WAIT_KINDS = Object.freeze(['urlContains', 'text', 'target', 'targetGone', 'actionable', 'indicatorGone', 'networkQuiet', 'requestDone']);
+
+/**
+ * Ordered: the more specific answer wins. The condition hierarchy follows the
+ * design — the step's own expectation, then actionability, then a specific
+ * request, then a UI signal, then global network quiet (as a fallback only).
+ */
+const RESOLVERS = Object.freeze([
+  {
+    id: 'expectation_unmet',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    // About what the step produced, so it can never be a pre-wait: an
+    // expectation cannot be there before the step that produces it runs.
+    promotable: false,
+    budgetMs: { floor: 500, default: 5000, ceiling: 30000 },
+    matches: ({ evidence, step }) => Boolean(step.expect) && evidence.expectationMet === false,
+    wait: ({ step }) => waitForRecordedExpectation(step.expect),
+  },
+  {
+    id: 'click_no_effect',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 3000, ceiling: 10000 },
+    // The narrow AU-08 exception: reversible, nothing visible changed, and no
+    // request went out. A click that started a request is waited on instead.
+    matches: ({ evidence, step }) => step.tool === 'element_click'
+      && evidence.noObservableChange === true
+      && evidence.risk === 'reversible'
+      && Number(evidence.requestsStarted ?? 0) === 0,
+    wait: ({ step }) => ({ actionable: step.args.target, networkQuiet: true }),
+  },
+  {
+    id: 'target_not_ready',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 5000, ceiling: 20000 },
+    matches: ({ code }) => code === 'TARGET_NOT_INTERACTABLE',
+    wait: ({ step }) => ({ actionable: step.args.target }),
+  },
+  {
+    id: 'target_late',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 8000, ceiling: 30000 },
+    matches: ({ code, evidence }) => code === 'TARGET_NOT_FOUND'
+      && (Number(evidence.pendingRequests ?? 0) > 0 || Boolean(evidence.busyIndicator)),
+    wait: ({ step }) => ({ target: step.args.target }),
+  },
+  {
+    id: 'api_pending',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 1000, default: 15000, ceiling: 45000 },
+    matches: ({ evidence }) => evidence.likelyCause === 'server_slow'
+      || Number(evidence.pendingRequests ?? 0) > 0
+      || Boolean(evidence.slowestRequest),
+    // The step's own recorded request is the strongest signal; global quiet is
+    // only the capped fallback.
+    wait: ({ step }) => (step.expect && step.expect.request
+      ? { requestDone: step.expect.request }
+      : { networkQuiet: true }),
+  },
+  {
+    id: 'still_rendering',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 10000, ceiling: 30000 },
+    matches: ({ evidence }) => Boolean(evidence.busyIndicator) || evidence.likelyCause === 'still_rendering',
+    wait: () => ({ indicatorGone: true }),
+  },
+  {
+    id: 'site_error',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ code, evidence }) => code === 'SITE_ERROR' || evidence.likelyCause === 'site_error',
+    wait: () => null,
+  },
+  {
+    id: 'context_lost',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ evidence }) => evidence.contextLost === true,
+    wait: () => null,
+  },
+]);
+
+/** The wait args for a recorded expectation (`appears` and `request` can combine). */
+function waitForRecordedExpectation(expect) {
+  if (!expect) return null;
+  const args = {};
+  if (expect.appears) args.target = expect.appears;
+  if (expect.request && expect.request.pathContains) args.requestDone = expect.request;
+  return Object.keys(args).length > 0 ? args : null;
+}
+
+/**
+ * How long the recorded-expectation wait may look for its evidence: the
+ * person's `maxWaitMs` when set, otherwise the settle the recorder measured
+ * (the learned pace for that step), otherwise the default expectation timeout.
+ * It is the budget of a bounded poll that ends the moment the evidence is
+ * there — never a pause (A6-10). Clamped to the shared limits.
+ */
+function expectBudgetMs(expect, maxWaitMs = null) {
+  const asked = Number.isFinite(maxWaitMs) && maxWaitMs > 0 ? maxWaitMs : null;
+  const recorded = Number.isFinite(expect?.settleMs) && expect.settleMs > 0 ? expect.settleMs : null;
+  const ms = asked ?? recorded ?? LIMITS.DEFAULT_EXPECT_TIMEOUT_MS;
+  return Math.max(LIMITS.SETTLE_QUIET_MS, Math.min(ms, LIMITS.MAX_WAIT_MS));
+}
+
+/** The failure a classifier works from, normalised from either envelope shape. */
+function normalise(env) {
+  return {
+    code: env?.error?.code ?? env?.code ?? null,
+    evidence: env?.evidence ?? {},
+    state: env?.state ?? (env?.ok === false ? 'failed' : 'completed'),
+  };
+}
+
+/**
+ * What is this step blocked on? Returns `{ id, safety, then, wait, budgetMs }`,
+ * or null when nothing safe could clear it (a person, a policy, ambiguity, or
+ * an unknown failure). A resolver whose `wait` is null only selects the
+ * existing group-recovery path.
+ */
+function classify(env, step, options = {}) {
+  const failure = normalise(env);
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return null;
+  if (failure.code && FORBIDDEN_CODES.includes(failure.code)) return null;
+  if (failure.code && !TRANSIENT_CODES.includes(failure.code)) return null;
+  const demoted = Array.isArray(options.demoted) ? options.demoted : [];
+  for (const resolver of RESOLVERS) {
+    if (demoted.includes(resolver.id)) continue;
+    if (!resolver.matches({ ...failure, step })) continue;
+    const wait = resolver.wait({ step, evidence: failure.evidence });
+    if (resolver.then === 'retry_step' && !wait) return null;
+    return {
+      id: resolver.id,
+      safety: resolver.safety,
+      then: resolver.then,
+      wait,
+      budgetMs: resolveBudget(resolver, options),
+    };
+  }
+  return null;
+}
+
+/** One resolver by id, for a step profile that learned to pre-wait. */
+function resolverById(id) {
+  return RESOLVERS.find((resolver) => resolver.id === id && resolver.then === 'retry_step') ?? null;
+}
+
+/** The wait args for a resolver id applied to this step (promotion from the step profile). */
+function waitArgsFor(id, step) {
+  const resolver = resolverById(id);
+  return resolver ? resolver.wait({ step, evidence: {} }) : null;
+}
+
+/**
+ * May a step profile wait for this blocker *before* acting? Only a blocker about
+ * what the step is waiting on — never one about what it produces.
+ */
+function promotable(id) {
+  const resolver = resolverById(id);
+  return Boolean(resolver) && resolver.promotable !== false;
+}
+
+/**
+ * How long to wait for this resolver, in this order: the resolver's own default,
+ * the step's learned p95 × 1.5 (once it has ≥ 3 runs), the person's patience,
+ * an explicit cap, then the resolver's floor/ceiling.
+ */
+function resolveBudget(resolver, { learnedMs = null, patience = 'normal', maxWaitMs = null } = {}) {
+  const { floor, default: fallback, ceiling } = resolver.budgetMs;
+  let ms = fallback;
+  if (Number.isFinite(learnedMs) && learnedMs > 0) ms = Math.round(learnedMs * 1.5);
+  const factor = patience === 'fast' ? 0.5 : patience === 'patient' ? 3 : 1;
+  ms = Math.round(ms * factor);
+  if (Number.isFinite(maxWaitMs) && maxWaitMs > 0) ms = Math.min(ms, maxWaitMs);
+  return Math.max(floor, Math.min(ms, ceiling));
+}
+
+/**
+ * May this step be retried in place under AU-08?
+ *
+ * - the resolver must actually retry the step;
+ * - its tool must be one a workflow may repeat;
+ * - a consequential step is never repeated, whatever the failure code;
+ * - a click or key press is repeated only when the action provably did not run,
+ *   or under the click_no_effect resolver's own narrow rule;
+ * - everything else (fills, selects, navigations, waits) is safe to repeat.
+ */
+function mayRetryInPlace(resolver, env, step) {
+  if (!resolver || resolver.then !== 'retry_step') return false;
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return false;
+  const { code, evidence } = normalise(env);
+  if (CONSEQUENTIAL_RISKS.has(evidence.risk)) return false;
+  if (resolver.id === 'click_no_effect') return true;
+  if (step.tool === 'element_click' || step.tool === 'browser_press_key') {
+    return ACTION_DID_NOT_RUN_CODES.has(code);
+  }
+  return true;
+}
+
+module.exports = {
+  REGISTRY_VERSION,
+  FORBIDDEN_CODES,
+  CONSEQUENTIAL_RISKS,
+  RETRYABLE_TOOLS,
+  ACTION_DID_NOT_RUN_CODES,
+  TRANSIENT_CODES,
+  WAIT_KINDS,
+  RESOLVERS,
+  classify,
+  resolveBudget,
+  mayRetryInPlace,
+  resolverById,
+  promotable,
+  waitArgsFor,
+  waitForRecordedExpectation,
+  expectBudgetMs,
+};

package/bridge-server/server.js

@@ -73,7 +73,8 @@ const MAX_EXTENSION_MESSAGES_PER_SECOND = 500;
 const VALID_AGENT_ACTIONS = new Set([
   'status', 'inspect', 'navigate', 'click', 'fill', 'select_option', 'wait_for',
   'screenshot', 'press_key', 'scroll', 'pause', 'resume',
-  'new_tab', 'list_tabs', 'switch_tab', 'close_tab', 'notify',
+  'new_tab', 'list_tabs', 'switch_tab', 'close_tab', 'notify', 'upload',
+  'console', 'network',
 ]);
 
 const VALID_MESSAGE_TYPES = new Set([

package/bridge-server/setup.js

@@ -25,14 +25,23 @@ const { configDir } = require('./secret');
 const { isListening, helloProbe } = require('./probe');
 const { DEFAULT_PORT } = require('./server');
 const { readSecret } = require('./secret');
-const { EXTENSION_ID, HOST_NAME, extensionOrigin, extensionIdFromKey } = require('./extension-id');
+const { EXTENSION_ID, STORE_EXTENSION_ID, HOST_NAME, allowedOrigins, extensionIdFromKey } = require('./extension-id');
 
 const HOST_DIR_NAME = 'native-host';
 const NATIVE_HOST_SCRIPT = path.join(__dirname, 'native-host.js');
 const MCP_ENTRY = path.join(__dirname, 'index.js');
+/** The Chrome Web Store listing (STORE_EXTENSION_ID); it opens once the listing is published. */
+const STORE_URL = `https://chromewebstore.google.com/detail/${STORE_EXTENSION_ID}`;
 
 /** HKCU only: no administrator rights, and the key is per-user by design. */
 const REGISTRY_KEY = `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${HOST_NAME}`;
+/**
+ * Microsoft Edge reads its own key (ROADMAP 0.5.3). Edge installs Chrome Web Store
+ * extensions and loads the same unpacked folder, with the same extension id, so the
+ * one host manifest serves both browsers.
+ */
+const EDGE_REGISTRY_KEY = `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${HOST_NAME}`;
+const REGISTRY_KEYS = [REGISTRY_KEY, EDGE_REGISTRY_KEY];
 
 function hostDir(dir = configDir()) {
   return path.join(dir, HOST_DIR_NAME);
@@ -60,9 +69,16 @@ function hostManifestPath(dir = configDir()) {
 function manifestTargets({ platform = process.platform, home = os.homedir(), dir = configDir() } = {}) {
   if (platform === 'win32') return [hostManifestPath(dir)];
   if (platform === 'darwin') {
-    return [path.join(home, 'Library', 'Application Support', 'Google', 'Chrome', 'NativeMessagingHosts', `${HOST_NAME}.json`)];
+    const support = path.join(home, 'Library', 'Application Support');
+    return [
+      path.join(support, 'Google', 'Chrome', 'NativeMessagingHosts', `${HOST_NAME}.json`),
+      path.join(support, 'Microsoft Edge', 'NativeMessagingHosts', `${HOST_NAME}.json`),
+    ];
   }
-  return [path.join(home, '.config', 'google-chrome', 'NativeMessagingHosts', `${HOST_NAME}.json`)];
+  return [
+    path.join(home, '.config', 'google-chrome', 'NativeMessagingHosts', `${HOST_NAME}.json`),
+    path.join(home, '.config', 'microsoft-edge', 'NativeMessagingHosts', `${HOST_NAME}.json`),
+  ];
 }
 
 function launcherContents({ platform = process.platform, nodePath = process.execPath, hostScript = NATIVE_HOST_SCRIPT } = {}) {
@@ -81,7 +97,7 @@ function hostManifest({ dir = configDir(), platform = process.platform, nodePath
     description: 'BrowserZap bridge helper: starts the local bridge and hands this extension its pairing token.',
     path: launcherPath(dir, platform),
     type: 'stdio',
-    allowed_origins: [extensionOrigin()],
+    allowed_origins: allowedOrigins(),
   };
 }
 
@@ -113,9 +129,49 @@ function defaultRegistryRunner(argv) {
   };
 }
 
-/** Read the default (unnamed) value of the host's HKCU key, or null. */
-function readRegisteredManifest({ run = defaultRegistryRunner } = {}) {
-  const result = run(['query', REGISTRY_KEY, '/ve']);
+/**
+ * The Node binary and host script a launcher runs: the first two quoted paths
+ * in it (`"node" "native-host.js" %*` on Windows, `exec "node" "…" "$@"` elsewhere).
+ */
+function launcherTargets(text) {
+  const quoted = [...String(text).matchAll(/"([^"]+)"/g)].map((m) => m[1]).filter((p) => p !== '$@');
+  return { node: quoted[0] ?? null, script: quoted[1] ?? null };
+}
+
+const POLICY_ROOTS = ['HKLM\\SOFTWARE\\Policies\\Google\\Chrome', 'HKCU\\SOFTWARE\\Policies\\Google\\Chrome'];
+
+/** Values of one Chrome list policy (`reg query <root>\\<name>` prints `    1    REG_SZ    value`), across HKLM and HKCU. */
+function policyList(name, run) {
+  const values = [];
+  for (const root of POLICY_ROOTS) {
+    const result = run(['query', `${root}\\${name}`]);
+    if (result.status !== 0) continue;
+    for (const match of String(result.stdout ?? '').matchAll(/^\s+\S+\s+REG_SZ\s+(.+?)\s*$/gm)) values.push(match[1]);
+  }
+  return values;
+}
+
+/**
+ * Chrome enterprise policy that stops BrowserZap, in words, or null. Checks
+ * the native-messaging block/allow lists and the extension install lists.
+ */
+function blockingPolicy(run, { hostName = HOST_NAME, extensionId = EXTENSION_ID } = {}) {
+  const nmBlock = policyList('NativeMessagingBlocklist', run);
+  const nmAllow = policyList('NativeMessagingAllowlist', run);
+  if (nmBlock.includes(hostName) || (nmBlock.includes('*') && !nmAllow.includes(hostName))) {
+    return `Chrome policy NativeMessagingBlocklist blocks ${nmBlock.includes(hostName) ? hostName : 'all native helpers'}`;
+  }
+  const extBlock = policyList('ExtensionInstallBlocklist', run);
+  const extAllow = policyList('ExtensionInstallAllowlist', run);
+  if (extBlock.includes(extensionId) || (extBlock.includes('*') && !extAllow.includes(extensionId))) {
+    return `Chrome policy ExtensionInstallBlocklist blocks ${extBlock.includes(extensionId) ? 'the BrowserZap extension' : 'extensions that are not allow-listed'}`;
+  }
+  return null;
+}
+
+/** Read the default (unnamed) value of the host's HKCU key (Chrome's unless `key` is given), or null. */
+function readRegisteredManifest({ run = defaultRegistryRunner, key = REGISTRY_KEY } = {}) {
+  const result = run(['query', key, '/ve']);
   if (result.status !== 0) return null;
   // REG_SZ    C:\path\to\manifest.json
   const match = /REG_SZ\s+(.+?)\s*$/m.exec(result.stdout ?? '');
@@ -139,10 +195,10 @@ function registerNativeHost({
   const written = writeNativeHost({ dir, platform, nodePath, home });
   const registry = [];
   if (platform === 'win32' && register) {
-    registry.push({
-      command: ['add', REGISTRY_KEY, '/ve', '/t', 'REG_SZ', '/d', written.manifestPaths[0], '/f'],
-      result: run(['add', REGISTRY_KEY, '/ve', '/t', 'REG_SZ', '/d', written.manifestPaths[0], '/f']),
-    });
+    for (const key of REGISTRY_KEYS) {
+      const command = ['add', key, '/ve', '/t', 'REG_SZ', '/d', written.manifestPaths[0], '/f'];
+      registry.push({ command, result: run(command) });
+    }
   }
   return {
     ...written,
@@ -180,10 +236,8 @@ function unregisterNativeHost({
 
   const registry = [];
   if (platform === 'win32' && register) {
-    registry.push({
-      command: ['delete', REGISTRY_KEY, '/f'],
-      result: run(['delete', REGISTRY_KEY, '/f']),
-    });
+    // An install from before Edge support has no Edge key: that delete fails harmlessly.
+    for (const key of REGISTRY_KEYS) registry.push({ command: ['delete', key, '/f'], result: run(['delete', key, '/f']) });
   }
   for (const file of manifests) fs.rmSync(file, { force: true });
   fs.rmSync(launcherPath(dir, platform), { force: true });
@@ -320,6 +374,7 @@ async function doctor({
   register = true,
   port = DEFAULT_PORT,
   extensionManifest = extensionManifestPath(),
+  out = write,
 } = {}) {
   const results = [];
   const record = (name, ok, detail, nextAction) => results.push({ name, ok, detail, nextAction });
@@ -340,22 +395,46 @@ async function doctor({
   );
 
   const allowed = Array.isArray(manifest?.allowed_origins) ? manifest.allowed_origins : [];
+  const expected = allowedOrigins();
   record(
-    'Host allows this extension id',
-    allowed.includes(extensionOrigin()),
+    expected.length > 1 ? 'Host allows the unpacked and store extension ids' : 'Host allows this extension id',
+    expected.every((origin) => allowed.includes(origin)),
     allowed.length ? allowed.join(', ') : 'no allowed_origins',
-    `Run: browserzap setup (expected ${extensionOrigin()})`,
+    `Run: browserzap setup (expected ${expected.join(', ')})`,
   );
 
   const launcher = manifest?.path;
+  const launcherOk = typeof launcher === 'string' && fs.existsSync(launcher);
   record(
     'Host launcher exists',
-    typeof launcher === 'string' && fs.existsSync(launcher),
+    launcherOk,
     launcher ?? 'the manifest has no path',
     'Run: browserzap setup',
   );
+  if (launcherOk) {
+    // The launcher names Node and the host script by full path. A Node version
+    // switch (fnm, Volta, nvm) or a reinstall elsewhere leaves it pointing at
+    // nothing, and the side panel stays grey.
+    let text = '';
+    try { text = fs.readFileSync(launcher, 'utf8'); } catch { /* unreadable: reported below */ }
+    const targets = launcherTargets(text);
+    const missing = [targets.node, targets.script].filter((p) => !p || !fs.existsSync(p));
+    record(
+      'Launcher finds Node and the helper',
+      missing.length === 0,
+      missing.length === 0 ? targets.node : `missing: ${missing.map((p) => p ?? '(no path)').join(', ')}`,
+      'Node or BrowserZap moved (a Node version switch with fnm, Volta or nvm, or a reinstall). Run: browserzap setup',
+    );
+  }
 
   if (platform === 'win32' && register) {
+    const policy = blockingPolicy(run);
+    record(
+      'Not blocked by Chrome policy',
+      policy === null,
+      policy ?? 'no blocking policy found',
+      'This computer is managed. Ask IT to allow the native helper com.browserzap.bridge and the BrowserZap extension.',
+    );
     const registered = readRegisteredManifest({ run });
     record(
       'Registered with Chrome (HKCU)',
@@ -363,6 +442,13 @@ async function doctor({
       registered ?? `nothing at ${REGISTRY_KEY}`,
       'Run: browserzap setup',
     );
+    const edge = readRegisteredManifest({ run, key: EDGE_REGISTRY_KEY });
+    record(
+      'Registered with Edge (HKCU)',
+      edge !== null,
+      edge ?? `nothing at ${EDGE_REGISTRY_KEY}`,
+      'Run: browserzap setup (adds Microsoft Edge next to Chrome)',
+    );
     if (registered && path.resolve(registered) !== path.resolve(manifestFile)) {
       record(
         'Registry points at this manifest',
@@ -393,28 +479,83 @@ async function doctor({
     probe = await helloProbe({ port, token: secret, session: 'doctor', name: 'doctor', timeoutMs: 3000 });
     if (probe.ok) probe.ws.close();
   }
+  // 4003: something on the port speaks our protocol but holds a different
+  // secret: a bridge from another install, another BROWSERZAP_HOME, or a
+  // leftover test. The extension cannot pair until it is replaced.
+  const foreign = listening && !probe.ok && probe.code === 4003;
   record(
     'Bridge reachable',
     listening && probe.ok,
     listening
-      ? (probe.ok ? `authenticated handshake accepted on 127.0.0.1:${port}` : `listening, but ${probe.reason ?? 'the handshake failed'}`)
+      ? (probe.ok
+        ? `authenticated handshake accepted on 127.0.0.1:${port}`
+        : foreign
+          ? `a bridge with a different pairing secret holds 127.0.0.1:${port}`
+          : `listening, but ${probe.reason ?? 'the handshake failed'}`)
       : `nothing listening on 127.0.0.1:${port} (the native host starts it on demand)`,
-    'Open the BrowserZap side panel; the background service starts the bridge through the native host.',
+    foreign
+      ? 'Replace it: browserzap restart-bridge (stops the BrowserZap bridge on that port; the side panel starts the right one).'
+      : 'Open the BrowserZap side panel; the background service starts the bridge through the native host.',
   );
 
   let width = 0;
   for (const r of results) width = Math.max(width, r.name.length);
-  write('BrowserZap doctor');
+  out('BrowserZap doctor');
   for (const r of results) {
-    write(`  ${r.ok ? 'PASS' : 'FAIL'}  ${r.name.padEnd(width)}  ${r.detail}`);
-    if (!r.ok && r.nextAction) write(`        ${' '.repeat(width)}  → ${r.nextAction}`);
+    out(`  ${r.ok ? 'PASS' : 'FAIL'}  ${r.name.padEnd(width)}  ${r.detail}`);
+    if (!r.ok && r.nextAction) out(`        ${' '.repeat(width)}  → ${r.nextAction}`);
+  }
+  const asks = require('./downloads').asksWhereToSave({ dataDir: require('./chrome-launcher').userDataDir({ platform, home }) });
+  if (asks) {
+    out('  NOTE  Chrome asks where to save each download: a download an agent starts opens a "Save as" dialog it cannot answer.');
+    out('        → Turn off "Ask where to save each file before downloading" in chrome://settings/downloads');
   }
   const failed = results.filter((r) => !r.ok);
-  write('');
-  write(failed.length === 0 ? 'All checks passed.' : `${failed.length} check(s) failed.`);
+  out('');
+  out(failed.length === 0 ? 'All checks passed.' : `${failed.length} check(s) failed.`);
   return failed.length === 0 ? 0 : 1;
 }
 
+/**
+ * WSL (ROADMAP 0.5.3, docs/WSL.md): an agent inside WSL starts BrowserZap's
+ * Windows MCP server through interop (`cmd.exe /c …`), so the bridge stays on
+ * Windows loopback and nothing is exposed to the WSL network. True when this
+ * Windows machine has WSL.
+ */
+function hasWsl({ platform = process.platform, env = process.env, exists = fs.existsSync } = {}) {
+  if (platform !== 'win32') return false;
+  return exists(path.join(env.SystemRoot || env.windir || 'C:\\Windows', 'System32', 'wsl.exe'));
+}
+
+/** True inside WSL (a Linux kernel built by Microsoft), where BrowserZap must run on the Windows side. */
+function insideWsl({ platform = process.platform, env = process.env, readFile = (f) => fs.readFileSync(f, 'utf8') } = {}) {
+  if (platform !== 'linux') return false;
+  if (env.WSL_DISTRO_NAME) return true;
+  try {
+    // WSL2: "…-microsoft-standard-WSL2"; WSL1: "…-Microsoft". Not an Azure VM's "-azure" kernel.
+    return /microsoft-standard|wsl|-microsoft\b/i.test(readFile('/proc/version'));
+  } catch {
+    return false;
+  }
+}
+
+/** C:\Program Files\nodejs\node.exe → /mnt/c/Program Files/nodejs/node.exe (WSL's default mount). */
+function wslPath(winPath) {
+  const m = /^([A-Za-z]):[\\/](.*)$/.exec(winPath);
+  return m ? `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, '/')}` : winPath;
+}
+
+/**
+ * The command an agent inside WSL registers: the Windows MCP server, started
+ * through interop. A global install is on the Windows PATH (`cmd.exe /c browserzap`);
+ * otherwise Windows node.exe is run by its /mnt path, which needs no cmd quoting.
+ */
+function wslCommand({ nodePath = process.execPath, serverPath = MCP_ENTRY, globalInstall = !fromNpxCache() && !fs.existsSync(path.join(__dirname, '..', 'src')) } = {}) {
+  return globalInstall
+    ? 'claude mcp add browserzap -- cmd.exe /c browserzap'
+    : `claude mcp add browserzap -- '${wslPath(nodePath)}' '${serverPath}'`;
+}
+
 /**
  * `browserzap setup`. `args` is everything after the command word.
  * Returns the process exit code.
@@ -476,8 +617,17 @@ async function setupCommand(args = [], { extensionPath = null } = {}) {
     write('');
   }
 
+  if (hasWsl()) {
+    write('Using Claude Code (or another agent) inside WSL? Run this in WSL; BrowserZap still runs on Windows:');
+    write(`  ${wslCommand()}`);
+    write('  (other clients: command "cmd.exe", args ["/c", "browserzap"]; see docs/WSL.md)');
+    write('');
+  }
+
   write('Next:');
-  write(`  1. chrome://extensions → Developer mode → Load unpacked → ${extensionPath ?? 'the extension/ folder of this package'}`);
+  write(`  1. Add the extension: ${STORE_URL}`);
+  write('     (Chrome Web Store; the listing is in review. Until it opens there:');
+  write(`      chrome://extensions → Developer mode → Load unpacked → ${extensionPath ?? 'the extension/ folder of this package'})`);
   write('  2. Open the BrowserZap side panel. It connects automatically; no token to paste.');
   write('  3. Open your MCP client and start work. `browserzap doctor` re-checks this setup.');
   return result.ok || !result.registryKey ? 0 : 1;
@@ -500,10 +650,17 @@ function confirm(question) {
 }
 
 module.exports = {
+  launcherTargets,
+  blockingPolicy,
   fromNpxCache,
   REGISTRY_KEY,
+  EDGE_REGISTRY_KEY,
   HOST_NAME,
   MCP_ENTRY,
+  hasWsl,
+  insideWsl,
+  wslCommand,
+  wslPath,
   hostDir,
   hostManifestPath,
   launcherPath,