browserzap 0.4.0 → 0.5.5

package/bridge-server/executor.js

@@ -1,148 +1,148 @@
-/**
- * BrowserZap — one way to run a browser tool and describe its result.
- *
- * Shared by the MCP server (agent calls, agent-started workflow runs) and the
- * bridge's panel runner (workflows started from the side panel with no agent).
- * Both send the same action to the extension and get the same envelope back,
- * so a step behaves identically whoever started it: approvals, sensitive
- * fields, ambiguity and origin checks all live in the extension.
- */
-
-'use strict';
-
-const { TOOL_TO_ACTION, PAGE_TOOLS } = require('./tools');
-const { callDeadlineMs } = require('./limits');
-
-const ENVELOPE_KEYS = new Set(['state', 'summary', 'evidence', 'nextAction']);
-
-/**
- * The standard response envelope (docs/TOOL_CONTRACT.md §2):
- * { ok, traceId, state, summary, evidence, nextAction, error, ...payload }
- */
-function envelope(traceId, result) {
-  const data = result.data || {};
-  const ok = result.success === true;
-  const out = {
-    ok,
-    traceId,
-    state: data.state || (ok ? 'completed' : 'failed'),
-    summary: data.summary || (ok ? 'Done.' : result.error || 'Failed.'),
-    evidence: data.evidence || {},
-    nextAction: data.nextAction ?? null,
-    error: ok ? null : { code: result.code || 'INTERNAL', message: result.error || 'Unknown error' },
-  };
-  for (const [key, value] of Object.entries(data)) {
-    if (!ENVELOPE_KEYS.has(key)) out[key] = value;
-  }
-  if (result.pageState) out.page = { url: result.pageState.url, title: result.pageState.title };
-  return out;
-}
-
-function errorEnvelope(traceId, code, message, nextAction = null, state = 'failed') {
-  return { ok: false, traceId, state, summary: message, evidence: {}, nextAction, error: { code, message } };
-}
-
-/**
- * Run one browser tool through the extension.
- *
- *   startAction(action, params, deadlineMs) → { id, promise, cancel }
- *
- * The deadline covers every wait the call itself may do (limits.js callDeadlineMs).
- * `allowedOrigins` narrows (never widens) what the page actions may touch.
- * Never throws: a lost bridge, a timeout or a cancel come back as envelopes.
- */
-async function executeStep(startAction, toolName, args, { allowedOrigins = null, onStart } = {}) {
-  const action = TOOL_TO_ACTION[toolName];
-  const params = { ...args };
-  if (allowedOrigins && PAGE_TOOLS.has(toolName)) params.allowedOrigins = allowedOrigins;
-
-  const call = startAction(action, params, callDeadlineMs(toolName, args));
-  onStart?.(call);
-  try {
-    return envelope(call.id, await call.promise);
-  } catch (err) {
-    const code = err.code || 'INTERNAL';
-    const next = code === 'BRIDGE_DISCONNECTED'
-      ? 'Check that the BrowserZap extension is loaded and paired ("npm run health").'
-      : code === 'TIMEOUT'
-        ? 'Check the page with page_inspect before repeating anything.'
-        : null;
-    return errorEnvelope(call.id, code, err.message, next);
-  }
-}
-
-/**
- * Send actions to the extension and match their results, for one session.
- * Used by the MCP server (an agent) and the panel runner (the side panel), so
- * both time out, cancel and fail on a lost connection the same way.
- *
- *   send(msg)          → false when the message could not be sent
- *   ready()            → resolves when sending is possible (default: at once)
- *   cancelMessage      → the error text for a caller-side cancel
- *
- * start(action, params, deadlineMs) returns { id, promise, cancel }: the
- * promise resolves with the extension's result message, or rejects with an
- * error whose `code` is TIMEOUT, CANCELLED or BRIDGE_DISCONNECTED.
- */
-function createActionClient({ session, send, ready = () => Promise.resolve(), deadlineMs, cancelMessage = 'Cancelled.' }) {
-  const pending = new Map();
-  let nextId = 0;
-
-  const failure = (code, message) => Object.assign(new Error(message), { code });
-
-  function start(action, params, callDeadlineMs = deadlineMs) {
-    const id = `${session}-${++nextId}`;
-    // A cancel can arrive before the call is sent (while waiting for the bridge
-    // session); it must stop the call from being sent at all (audit AU-14).
-    let cancelledEarly = false;
-    let cancel = () => { cancelledEarly = true; };
-    const promise = ready().then(() => new Promise((resolve, reject) => {
-      if (cancelledEarly) {
-        reject(failure('CANCELLED', cancelMessage));
-        return;
-      }
-      const timer = setTimeout(() => {
-        if (!pending.delete(id)) return;
-        send({ type: 'cancel', id, session });
-        reject(failure('TIMEOUT', `No result from the browser within ${Math.round(callDeadlineMs / 1000)} s.`));
-      }, callDeadlineMs);
-      pending.set(id, {
-        resolve: (msg) => { clearTimeout(timer); resolve(msg); },
-        reject: (err) => { clearTimeout(timer); reject(err); },
-      });
-      cancel = () => {
-        if (!pending.delete(id)) return;
-        clearTimeout(timer);
-        send({ type: 'cancel', id, session });
-        reject(failure('CANCELLED', cancelMessage));
-      };
-      if (!send({ type: 'action', action, id, session, params })) {
-        pending.delete(id);
-        clearTimeout(timer);
-        reject(failure('BRIDGE_DISCONNECTED', 'The BrowserZap extension is not connected to the bridge.'));
-      }
-    }));
-    return { id, promise, cancel: () => cancel() };
-  }
-
-  /** Hand a result message to its waiting call. False when no call waits for it. */
-  function deliver(msg) {
-    const entry = msg?.type === 'result' ? pending.get(msg.id) : undefined;
-    if (!entry) return false;
-    pending.delete(msg.id);
-    entry.resolve(msg);
-    return true;
-  }
-
-  /** Fail every waiting call (the connection is gone). */
-  function failAll(code, message, detail) {
-    for (const [id, { reject }] of pending) {
-      pending.delete(id);
-      reject(Object.assign(failure(code, message), detail ? { detail } : {}));
-    }
-  }
-
-  return { start, deliver, failAll };
-}
-
-module.exports = { envelope, errorEnvelope, executeStep, createActionClient };
+/**
+ * BrowserZap — one way to run a browser tool and describe its result.
+ *
+ * Shared by the MCP server (agent calls, agent-started workflow runs) and the
+ * bridge's panel runner (workflows started from the side panel with no agent).
+ * Both send the same action to the extension and get the same envelope back,
+ * so a step behaves identically whoever started it: approvals, sensitive
+ * fields, ambiguity and origin checks all live in the extension.
+ */
+
+'use strict';
+
+const { TOOL_TO_ACTION, PAGE_TOOLS } = require('./tools');
+const { callDeadlineMs } = require('./limits');
+
+const ENVELOPE_KEYS = new Set(['state', 'summary', 'evidence', 'nextAction']);
+
+/**
+ * The standard response envelope (docs/TOOL_CONTRACT.md §2):
+ * { ok, traceId, state, summary, evidence, nextAction, error, ...payload }
+ */
+function envelope(traceId, result) {
+  const data = result.data || {};
+  const ok = result.success === true;
+  const out = {
+    ok,
+    traceId,
+    state: data.state || (ok ? 'completed' : 'failed'),
+    summary: data.summary || (ok ? 'Done.' : result.error || 'Failed.'),
+    evidence: data.evidence || {},
+    nextAction: data.nextAction ?? null,
+    error: ok ? null : { code: result.code || 'INTERNAL', message: result.error || 'Unknown error' },
+  };
+  for (const [key, value] of Object.entries(data)) {
+    if (!ENVELOPE_KEYS.has(key)) out[key] = value;
+  }
+  if (result.pageState) out.page = { url: result.pageState.url, title: result.pageState.title };
+  return out;
+}
+
+function errorEnvelope(traceId, code, message, nextAction = null, state = 'failed') {
+  return { ok: false, traceId, state, summary: message, evidence: {}, nextAction, error: { code, message } };
+}
+
+/**
+ * Run one browser tool through the extension.
+ *
+ *   startAction(action, params, deadlineMs) → { id, promise, cancel }
+ *
+ * The deadline covers every wait the call itself may do (limits.js callDeadlineMs).
+ * `allowedOrigins` narrows (never widens) what the page actions may touch.
+ * Never throws: a lost bridge, a timeout or a cancel come back as envelopes.
+ */
+async function executeStep(startAction, toolName, args, { allowedOrigins = null, onStart } = {}) {
+  const action = TOOL_TO_ACTION[toolName];
+  const params = { ...args };
+  if (allowedOrigins && PAGE_TOOLS.has(toolName)) params.allowedOrigins = allowedOrigins;
+
+  const call = startAction(action, params, callDeadlineMs(toolName, args));
+  onStart?.(call);
+  try {
+    return envelope(call.id, await call.promise);
+  } catch (err) {
+    const code = err.code || 'INTERNAL';
+    const next = code === 'BRIDGE_DISCONNECTED'
+      ? 'Check that the BrowserZap extension is loaded and paired ("browserzap doctor").'
+      : code === 'TIMEOUT'
+        ? 'Check the page with page_inspect before repeating anything.'
+        : null;
+    return errorEnvelope(call.id, code, err.message, next);
+  }
+}
+
+/**
+ * Send actions to the extension and match their results, for one session.
+ * Used by the MCP server (an agent) and the panel runner (the side panel), so
+ * both time out, cancel and fail on a lost connection the same way.
+ *
+ *   send(msg)          → false when the message could not be sent
+ *   ready()            → resolves when sending is possible (default: at once)
+ *   cancelMessage      → the error text for a caller-side cancel
+ *
+ * start(action, params, deadlineMs) returns { id, promise, cancel }: the
+ * promise resolves with the extension's result message, or rejects with an
+ * error whose `code` is TIMEOUT, CANCELLED or BRIDGE_DISCONNECTED.
+ */
+function createActionClient({ session, send, ready = () => Promise.resolve(), deadlineMs, cancelMessage = 'Cancelled.' }) {
+  const pending = new Map();
+  let nextId = 0;
+
+  const failure = (code, message) => Object.assign(new Error(message), { code });
+
+  function start(action, params, callDeadlineMs = deadlineMs) {
+    const id = `${session}-${++nextId}`;
+    // A cancel can arrive before the call is sent (while waiting for the bridge
+    // session); it must stop the call from being sent at all (audit AU-14).
+    let cancelledEarly = false;
+    let cancel = () => { cancelledEarly = true; };
+    const promise = ready().then(() => new Promise((resolve, reject) => {
+      if (cancelledEarly) {
+        reject(failure('CANCELLED', cancelMessage));
+        return;
+      }
+      const timer = setTimeout(() => {
+        if (!pending.delete(id)) return;
+        send({ type: 'cancel', id, session });
+        reject(failure('TIMEOUT', `No result from the browser within ${Math.round(callDeadlineMs / 1000)} s.`));
+      }, callDeadlineMs);
+      pending.set(id, {
+        resolve: (msg) => { clearTimeout(timer); resolve(msg); },
+        reject: (err) => { clearTimeout(timer); reject(err); },
+      });
+      cancel = () => {
+        if (!pending.delete(id)) return;
+        clearTimeout(timer);
+        send({ type: 'cancel', id, session });
+        reject(failure('CANCELLED', cancelMessage));
+      };
+      if (!send({ type: 'action', action, id, session, params })) {
+        pending.delete(id);
+        clearTimeout(timer);
+        reject(failure('BRIDGE_DISCONNECTED', 'The BrowserZap extension is not connected to the bridge.'));
+      }
+    }));
+    return { id, promise, cancel: () => cancel() };
+  }
+
+  /** Hand a result message to its waiting call. False when no call waits for it. */
+  function deliver(msg) {
+    const entry = msg?.type === 'result' ? pending.get(msg.id) : undefined;
+    if (!entry) return false;
+    pending.delete(msg.id);
+    entry.resolve(msg);
+    return true;
+  }
+
+  /** Fail every waiting call (the connection is gone). */
+  function failAll(code, message, detail) {
+    for (const [id, { reject }] of pending) {
+      pending.delete(id);
+      reject(Object.assign(failure(code, message), detail ? { detail } : {}));
+    }
+  }
+
+  return { start, deliver, failAll };
+}
+
+module.exports = { envelope, errorEnvelope, executeStep, createActionClient };

package/bridge-server/extension-id.js

@@ -7,6 +7,11 @@
  * extension id. The private half lives outside the repository at
  * %USERPROFILE%\.browserzap-extension\key.pem and is never committed.
  *
+ * The Chrome Web Store signs its own build and does not accept a manifest
+ * `key`, so the store build may get a different id. Fill in
+ * STORE_EXTENSION_ID from the developer dashboard after the first upload; the
+ * native host then lets both builds in (docs/RELEASE.md §3b).
+ *
  * Everything that has to name the extension — the native messaging host
  * manifest's allowed_origins, `browserzap doctor`, the tests — reads the id
  * from here. `extensionIdFromKey` derives it again from the manifest key, so a
@@ -22,6 +27,12 @@ const crypto = require('crypto');
 /** chrome-extension://gienkaoaimdjmcjdejjanmbkpfakmkno/ */
 const EXTENSION_ID = 'gienkaoaimdjmcjdejjanmbkpfakmkno';
 
+/** The Chrome Web Store build's id (assigned on the first upload, 2026-10-29). */
+const STORE_EXTENSION_ID = 'bbnmhaonicbmljhbahimpgfafbjoijpe';
+
+/** Every build the native host lets in: the unpacked build first, then the store build. */
+const ALLOWED_EXTENSION_IDS = Object.freeze([EXTENSION_ID, STORE_EXTENSION_ID].filter(Boolean));
+
 /** Name Chrome uses for the native messaging host; also the registry key's leaf. */
 const HOST_NAME = 'com.browserzap.bridge';
 
@@ -29,6 +40,11 @@ function extensionOrigin(id = EXTENSION_ID) {
   return `chrome-extension://${id}/`;
 }
 
+/** allowed_origins for the native host manifest, one per allowed build. */
+function allowedOrigins(ids = ALLOWED_EXTENSION_IDS) {
+  return ids.map((id) => extensionOrigin(id));
+}
+
 /**
  * Chrome's extension id for a manifest `key` value (base64 SPKI DER).
  * Returns null when the key is missing or is not a valid public key.
@@ -51,4 +67,12 @@ function extensionIdFromKey(key) {
     .join('');
 }
 
-module.exports = { EXTENSION_ID, HOST_NAME, extensionOrigin, extensionIdFromKey };
+module.exports = {
+  EXTENSION_ID,
+  STORE_EXTENSION_ID,
+  ALLOWED_EXTENSION_IDS,
+  HOST_NAME,
+  extensionOrigin,
+  allowedOrigins,
+  extensionIdFromKey,
+};

package/bridge-server/feedback.js

@@ -0,0 +1,255 @@
+/**
+ * BrowserZap — Comment mode batches kept on this device (docs/COMMENT_MODE.md).
+ *
+ * The person's comments arrive from the side panel in one `feedback_submit`
+ * panel request and are written here for the agent's `feedback_get`:
+ *
+ *   <config dir>/feedback/<batch id>/batch.json   comments, element details, component, page
+ *   <config dir>/feedback/<batch id>/c<n>.png      the element screenshot (sensitive fields covered)
+ *   <config dir>/feedback/<batch id>/c<n>-a<k>.*   images the person attached
+ *
+ * Folders are 0700 and files 0600. Nothing is uploaded anywhere. A batch is
+ * kept BROWSERZAP_FEEDBACK_DAYS days (default 7) and at most MAX_BATCHES
+ * batches; the oldest go first. Comments never contain form values: the
+ * extension sends labels and element details only.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { configDir } = require('./secret');
+
+const DEFAULT_KEEP_DAYS = 7;
+const MAX_BATCHES = 50;
+const MAX_COMMENTS = 30;
+const MAX_ATTACHMENTS = 3;
+const MAX_IMAGE_CHARS = 6 * 1024 * 1024;
+const ID_RE = /^fb-\d{14}-[0-9a-f]{6}$/;
+const IMAGE_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' };
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+class FeedbackError extends Error {
+  constructor(message) {
+    super(message);
+    this.code = 'INVALID_ARGUMENT';
+  }
+}
+
+const feedbackDir = () => path.join(configDir(), 'feedback');
+
+function keepDays() {
+  const raw = process.env.BROWSERZAP_FEEDBACK_DAYS;
+  if (raw === undefined || raw === '') return DEFAULT_KEEP_DAYS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 365 ? n : DEFAULT_KEEP_DAYS;
+}
+
+const str = (v, max) => (typeof v === 'string' ? v.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '').slice(0, max) : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? Math.round(v) : null);
+
+function rectOf(r) {
+  if (!r || typeof r !== 'object') return null;
+  return { x: num(r.x), y: num(r.y), width: num(r.width), height: num(r.height) };
+}
+
+/** Plain JSON of bounded size: target objects are small; anything deeper or larger is dropped. */
+function smallJson(value, maxChars = 2000) {
+  try {
+    const text = JSON.stringify(value);
+    return text && text.length <= maxChars ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}
+
+function elementOf(info) {
+  const i = info && typeof info === 'object' ? info : {};
+  return {
+    role: str(i.role, 60),
+    name: str(i.name, 300),
+    target: smallJson(i.target),
+    targetUnique: i.targetUnique === true,
+    tag: str(i.tag, 40),
+    id: str(i.id, 200),
+    testId: str(i.testId, 200),
+    classes: Array.isArray(i.classes) ? i.classes.map((c) => str(c, 100)).filter(Boolean).slice(0, 6) : [],
+    domPath: str(i.domPath, 600),
+    text: str(i.text, 200),
+    sensitive: i.sensitive === true ? true : undefined,
+    rect: rectOf(i.rect),
+  };
+}
+
+function componentOf(c) {
+  if (!c || typeof c !== 'object') return null;
+  const source = c.source && typeof c.source === 'object' && typeof c.source.file === 'string'
+    ? { file: str(c.source.file, 400), line: num(c.source.line), column: num(c.source.column) }
+    : null;
+  return {
+    framework: str(c.framework, 20),
+    component: str(c.component, 100),
+    chain: Array.isArray(c.chain) ? c.chain.map((n) => str(n, 100)).filter(Boolean).slice(0, 5) : [],
+    source,
+  };
+}
+
+function pageOf(p) {
+  const page = p && typeof p === 'object' ? p : {};
+  const url = str(page.url, 2000);
+  if (!url || !/^https?:\/\//i.test(url)) throw new FeedbackError('Every comment needs the http(s) page it was made on.');
+  return {
+    url,
+    title: str(page.title, 200),
+    viewport: page.viewport && typeof page.viewport === 'object' ? { width: num(page.viewport.width), height: num(page.viewport.height) } : null,
+  };
+}
+
+function imageData(data, what) {
+  if (typeof data !== 'string' || !data) return null;
+  if (data.length > MAX_IMAGE_CHARS) throw new FeedbackError(`${what} is too large.`);
+  if (!BASE64_RE.test(data)) throw new FeedbackError(`${what} is not a valid image.`);
+  return Buffer.from(data, 'base64');
+}
+
+function newId(now = new Date()) {
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  const stamp = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+  return `fb-${stamp}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function writePrivate(file, content) {
+  fs.writeFileSync(file, content, { mode: 0o600 });
+}
+
+/** Check and store one batch. Returns { id, dir, count }. Throws FeedbackError on bad input. */
+function saveBatch(batch, { now = new Date() } = {}) {
+  const comments = batch && Array.isArray(batch.comments) ? batch.comments : null;
+  if (!comments || comments.length === 0) throw new FeedbackError('The batch has no comments.');
+  if (comments.length > MAX_COMMENTS) throw new FeedbackError(`A batch holds at most ${MAX_COMMENTS} comments.`);
+
+  const id = newId(now);
+  const dir = path.join(feedbackDir(), id);
+  const files = [];
+  const stored = comments.map((c, index) => {
+    if (!c || typeof c !== 'object') throw new FeedbackError(`Comment ${index + 1} is not an object.`);
+    const text = str(c.text, 2000)?.trim();
+    if (!text) throw new FeedbackError(`Comment ${index + 1} has no text.`);
+    const n = Number.isInteger(c.n) && c.n > 0 && c.n < 1000 ? c.n : index + 1;
+    const shot = imageData(c.screenshot, `The screenshot of comment ${n}`);
+    const attachments = Array.isArray(c.attachments) ? c.attachments.slice(0, MAX_ATTACHMENTS) : [];
+    const entry = {
+      n,
+      text,
+      page: pageOf(c.page),
+      element: elementOf(c.info),
+      component: componentOf(c.component),
+      screenshot: null,
+      attachments: [],
+      createdAt: num(c.createdAt),
+    };
+    if (shot) {
+      entry.screenshot = `c${n}.png`;
+      files.push([entry.screenshot, shot]);
+    }
+    attachments.forEach((a, k) => {
+      const ext = a && IMAGE_TYPES[a.mimeType];
+      const data = ext ? imageData(a.data, `Image ${k + 1} of comment ${n}`) : null;
+      if (!data) return;
+      const name = `c${n}-a${k + 1}.${ext}`;
+      entry.attachments.push(name);
+      files.push([name, data]);
+    });
+    return entry;
+  });
+
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (const [name, data] of files) writePrivate(path.join(dir, name), data);
+  const record = { id, createdAt: now.toISOString(), delivered: false, deliveredAt: null, comments: stored };
+  writePrivate(path.join(dir, 'batch.json'), JSON.stringify(record, null, 2));
+  prune({ now: now.getTime() });
+  return { id, dir, count: stored.length };
+}
+
+function readBatch(id) {
+  if (!ID_RE.test(id)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(feedbackDir(), id, 'batch.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function batchIds() {
+  try {
+    return fs.readdirSync(feedbackDir()).filter((d) => ID_RE.test(d)).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Newest first: { id, createdAt, count, pages, delivered }. */
+function list({ includeDelivered = false } = {}) {
+  return batchIds().reverse()
+    .map((id) => readBatch(id))
+    .filter((b) => b && (includeDelivered || !b.delivered))
+    .map((b) => ({
+      id: b.id,
+      createdAt: b.createdAt,
+      count: b.comments.length,
+      pages: [...new Set(b.comments.map((c) => c.page.url))].slice(0, 5),
+      delivered: b.delivered,
+    }));
+}
+
+/** One batch with absolute file paths, or the newest one not yet delivered. */
+function get(id) {
+  const chosen = id ?? list()[0]?.id;
+  const batch = chosen ? readBatch(chosen) : null;
+  if (!batch) return null;
+  const dir = path.join(feedbackDir(), batch.id);
+  return {
+    ...batch,
+    dir,
+    comments: batch.comments.map((c) => ({
+      ...c,
+      screenshot: c.screenshot ? path.join(dir, c.screenshot) : null,
+      attachments: c.attachments.map((a) => path.join(dir, a)),
+    })),
+  };
+}
+
+function markDelivered(id, { now = new Date() } = {}) {
+  const batch = readBatch(id);
+  if (!batch || batch.delivered) return false;
+  batch.delivered = true;
+  batch.deliveredAt = now.toISOString();
+  writePrivate(path.join(feedbackDir(), id, 'batch.json'), JSON.stringify(batch, null, 2));
+  return true;
+}
+
+function pendingCount() {
+  return list().length;
+}
+
+/** Delete batches older than the retention, and the oldest beyond MAX_BATCHES. Never throws. */
+function prune({ now = Date.now(), days = keepDays() } = {}) {
+  const cutoff = now - days * 86_400_000;
+  const ids = batchIds();
+  let removed = 0;
+  ids.forEach((id, index) => {
+    const batch = readBatch(id);
+    const created = batch ? Date.parse(batch.createdAt) : 0;
+    if (created < cutoff || index < ids.length - MAX_BATCHES) {
+      try {
+        fs.rmSync(path.join(feedbackDir(), id), { recursive: true, force: true });
+        removed++;
+      } catch { /* in use: next time */ }
+    }
+  });
+  return removed;
+}
+
+module.exports = { saveBatch, list, get, markDelivered, pendingCount, prune, feedbackDir, FeedbackError, MAX_COMMENTS };

package/bridge-server/index.js

@@ -265,7 +265,16 @@ function uninstallExtension(purge, { register = true } = {}) {
  */
 const command = args[0] && !args[0].startsWith('-') ? args[0] : null;
 
-const SUBCOMMANDS = new Set(['setup', 'doctor', 'uninstall', 'run']);
+// Inside WSL there is no Chrome to pair with and no Windows registry: BrowserZap
+// runs on the Windows side and the agent in WSL starts it through interop.
+if (require('./setup').insideWsl() && !process.env.BROWSERZAP_ALLOW_LINUX) {
+  process.stderr.write('BrowserZap runs on Windows, next to Chrome. From WSL, start it through Windows:\n' +
+    '  claude mcp add browserzap -- cmd.exe /c browserzap\n' +
+    '(install it on Windows first: npm install -g browserzap, then browserzap setup). See docs/WSL.md.\n');
+  process.exit(2);
+}
+
+const SUBCOMMANDS = new Set(['setup', 'doctor', 'uninstall', 'run', 'restart-bridge']);
 
 if (command === 'setup') {
   // From an installed package, copy the extension to a folder that outlives an
@@ -298,12 +307,29 @@ if (command === 'setup') {
 `);
       process.exit(1);
     });
+} else if (command === 'restart-bridge') {
+  // A bridge that will not pair (another secret, an old version) holds the
+  // port. Stop the node process holding it (never anything that is not node);
+  // the extension's native host starts the current one with this install's secret.
+  const { stopBridgeOnPort, isListening } = require('./probe');
+  const portIdx = args.indexOf('--port');
+  const port = portIdx !== -1 && args[portIdx + 1] ? parseInt(args[portIdx + 1], 10) : DEFAULT_PORT;
+  stopBridgeOnPort(port).then(async (pids) => {
+    const still = await isListening(port);
+    process.stdout.write(pids.length
+      ? `Stopped the bridge on 127.0.0.1:${port} (pid ${pids.join(', ')}). Open the BrowserZap side panel (or press Reconnect) to start the current one.\n`
+      : `No BrowserZap bridge was holding 127.0.0.1:${port}.${still ? ' Something else listens there; it was left alone.' : ''}\n`);
+    process.exit(still ? 1 : 0);
+  }).catch((err) => {
+    process.stderr.write(`[browserzap] restart-bridge failed: ${err.message}\n`);
+    process.exit(1);
+  });
 } else if (command === 'uninstall') {
   uninstallExtension(args.includes('--purge'), { register: !args.includes('--no-registry') });
 } else if (command === 'help') {
   args.push('--help');
 } else if (command) {
-  process.stderr.write(`Unknown command "${command}". Use: setup, doctor, run, uninstall, or --help.\n`);
+  process.stderr.write(`Unknown command "${command}". Use: setup, doctor, restart-bridge, run, uninstall, or --help.\n`);
   process.exit(2);
 }
 
@@ -468,6 +494,7 @@ Usage:
   browserzap setup                      One-time setup: register the native messaging host and
                                         optionally add the MCP server to detected clients
   browserzap doctor                     Check the host manifest, registry, extension id and bridge
+  browserzap restart-bridge             Replace a bridge that will not pair (another secret or version)
   browserzap uninstall [--purge]        Remove the host registration and installed extension copy
   browserzap run <workflow> [--params <file.csv|file.json>] [--stop-on-error]
                                         Run a saved workflow with no agent; one run per row (Pro for

package/bridge-server/limits.js

@@ -28,6 +28,16 @@ const LIMITS = Object.freeze({
   SETTLE_MAX_MS: 5000,
   /** Longest per-step pacing a person may set on a saved workflow step. */
   MAX_STEP_PACING_MS: 30000,
+  /** A tab with no agent action for this long is detached, so Chrome's "debugging" bar goes away (D-35). */
+  DEBUGGER_IDLE_MS: 60000,
+  /** Tabs a session may have while it works (main + helpers); one more closes the least recently used helper (D-38). */
+  MAX_SESSION_TABS: 5,
+  /** Tabs a session keeps once it has been idle for TAB_TRIM_IDLE_MS. */
+  MAX_IDLE_TABS: 3,
+  /** No agent action for this long counts as "the task is done": helpers are trimmed to MAX_IDLE_TABS. */
+  TAB_TRIM_IDLE_MS: 120000,
+  /** A session whose connection dropped keeps its tabs this long, in case the same session reconnects. */
+  SESSION_GRACE_MS: 30000,
   /**
    * How long the MCP server waits for the extension after opening Chrome itself
    * (docs/AUTO_LAUNCH.md). Polled, never a fixed sleep.