browserzap 0.5.0 → 0.5.5

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/mcp-server.js

@@ -24,8 +24,10 @@
 const { WebSocket } = require('ws');
 const readline = require('readline');
 const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
 
-const { getOrCreateSecret } = require('./secret');
+const { getOrCreateSecret, configDir } = require('./secret');
 const { BIND_HOST, DEFAULT_PORT, PROTOCOL_VERSION, sanitizeSessionName } = require('./server');
 const { ensureBridge: ensureBridgeListening } = require('./ensure-bridge');
 const { LIMITS, CALL_DEADLINE_MS, STATUS_DEADLINE_MS } = require('./limits');
@@ -37,6 +39,8 @@ const { createWorkflowService, checkStep, stepLogEntry } = require('./workflow-s
 const { createSessionLog, describeArgs, describeResult } = require('./session-log');
 const workflows = require('./workflows');
 const screenshots = require('./screenshots');
+const feedback = require('./feedback');
+const downloads = require('./downloads');
 const { createRunRegistry, compactBatch, RunError } = require('./background-runs');
 
 const { WorkflowError, Recorder } = workflows;
@@ -189,12 +193,12 @@ function connectToBridge() {
 
 function describeBridgeProblem() {
   if (lastCloseCode === 4003) {
-    return 'The bridge rejected this server\'s pairing token. Run "npm run health" for details.';
+    return 'The bridge rejected this server\'s pairing token. Run "browserzap doctor" for details; "browserzap restart-bridge" replaces a bridge from another install.';
   }
   if (lastCloseCode === 4005) {
     return `${lastCloseReason || 'The bridge speaks a different protocol version.'} Restart the bridge and this MCP server after rebuilding.`;
   }
-  return 'The local BrowserZap bridge is not reachable. Run "npm run health" and check that the extension is loaded in Chrome.';
+  return 'The local BrowserZap bridge is not reachable. Run "browserzap doctor" and check that the extension is loaded in Chrome.';
 }
 
 function ensureSession(timeoutMs = 3000) {
@@ -227,7 +231,7 @@ function bridgeRequest(type, payload = {}, timeoutMs = 3000) {
     const id = `${SESSION_ID}-b${++bridgeSeq}`;
     const timer = setTimeout(() => {
       bridgeReplies.delete(id);
-      reject(Object.assign(new Error('The bridge did not answer. It may be an older version: run "npm run bridge:restart".'), { code: 'BRIDGE_DISCONNECTED' }));
+      reject(Object.assign(new Error('The bridge did not answer. It may be an older version: run "browserzap restart-bridge".'), { code: 'BRIDGE_DISCONNECTED' }));
     }, timeoutMs);
     bridgeReplies.set(id, (msg) => { clearTimeout(timer); resolve(msg); });
     ws.send(JSON.stringify({ type, id, ...payload }));
@@ -508,6 +512,13 @@ async function callToolWith(progress, requestId, toolName, args) {
 
   if (toolName === 'browser_list_profiles' || toolName === 'browser_select_profile') return finish(await profileTool(traceId, toolName, args));
 
+  if (toolName === 'browser_downloads') return finish(await downloadsTool(traceId, args));
+
+  if (toolName === 'feedback_list' || toolName === 'feedback_get') {
+    const { env, extra } = feedbackTool(traceId, toolName, args);
+    return finish(env, extra);
+  }
+
   if (LOCAL_TOOLS.has(toolName)) return finish(await workflowTool(requestId, traceId, toolName, args, progress));
   // A background run is driving this session's tab: reading is fine, acting would interleave with its steps.
   const running = backgroundRuns.active();
@@ -526,7 +537,19 @@ async function callToolWith(progress, requestId, toolName, args) {
     const notReady = await ensureBrowserForCall(traceId, progress, () => call.cancelled);
     if (notReady) return finish(notReady);
     if (call.cancelled) return finish(errorEnvelope(traceId, 'CANCELLED', 'Cancelled by the client.'));
-    const { env, extra } = await executeTool(toolName, args, { onStart: (c) => { call.cancel = c.cancel; } });
+    let toolArgs = args;
+    if (toolName === 'file_upload') {
+      const checked = checkUpload(traceId, args);
+      if (checked.error) return finish(checked.error);
+      toolArgs = checked.args;
+    }
+    // A download the agent starts is saved here, with no "Save as" dialog (dialogs.ts).
+    if (toolName === 'element_click' || toolName === 'browser_press_key') toolArgs = { ...toolArgs, downloadDir: downloadFolder() };
+    // A click or Enter may start a download: note the folder's names first (one directory read).
+    const watchDownloads = toolName === 'element_click' || toolName === 'browser_press_key';
+    const downloadsBefore = watchDownloads ? downloads.names(downloadFolder()) : null;
+    const { env, extra } = await executeTool(toolName, toolArgs, { onStart: (c) => { call.cancel = c.cancel; } });
+    if (downloadsBefore && env.ok) noteDownloads(env, downloadsBefore);
     if (recorder) recorder.observe(toolName, args, env);
     return finish(env, extra);
   } finally {
@@ -552,6 +575,160 @@ async function executeTool(toolName, args, { allowedOrigins = ALLOWED_ORIGINS, o
   return { env, extra };
 }
 
+// ─── Downloads (ROADMAP 0.5.4) ───────────────────────────────────────────────
+
+/** When this MCP server started: browser_downloads lists what arrived since then by default. */
+const SESSION_STARTED_AT = Date.now();
+let downloadDirCache = null;
+const downloadFolder = () => (downloadDirCache ??= downloads.downloadDir());
+
+/** A file that appeared in the Downloads folder during a click is said in its result. */
+function noteDownloads(env, before) {
+  const started = downloads.arrived(before, downloadFolder());
+  if (started.length === 0) return;
+  env.evidence = { ...(env.evidence ?? {}), downloads: started };
+  if (typeof env.summary === 'string') {
+    env.summary = `${env.summary} It started a download: ${started.map(downloads.describe).join(', ')}.`;
+  }
+  if (started.some((d) => d.state === 'in_progress') && !env.nextAction) {
+    env.nextAction = 'Call browser_downloads with waitForMs to wait until the download finishes.';
+  }
+}
+
+async function downloadsTool(traceId, args) {
+  const dir = downloadFolder();
+  let sinceMs = SESSION_STARTED_AT;
+  if (typeof args.since === 'string') {
+    const parsed = Date.parse(args.since);
+    if (Number.isNaN(parsed)) return errorEnvelope(traceId, 'INVALID_ARGUMENT', 'since must be an ISO date and time, e.g. 2026-10-29T10:00:00Z.');
+    sinceMs = parsed;
+  }
+  const waitMs = Number.isInteger(args.waitForMs) ? args.waitForMs : 0;
+  const { entries, timedOut } = waitMs > 0
+    ? await downloads.waitFor(dir, sinceMs, waitMs)
+    : { entries: downloads.since(dir, sinceMs), timedOut: false };
+  const running = entries.filter((e) => e.state === 'in_progress').length;
+  let summary = entries.length === 0
+    ? `No downloads in ${dir} since ${new Date(sinceMs).toISOString()}${timedOut ? ` (waited ${waitMs} ms)` : ''}.`
+    : `${entries.length} download(s)${running ? `, ${running} still in progress` : ', all complete'}: ${entries.slice(-5).map(downloads.describe).join(', ')}.`;
+  // Nothing arrived and Chrome asks where to save: the person is probably looking at a "Save as" dialog.
+  const asks = entries.length === 0 ? downloads.asksWhereToSave({ dataDir: chromeLauncher.userDataDir() }) : null;
+  if (asks) summary = `${summary} ${downloads.ASK_HINT}`;
+  return okEnvelope(traceId, summary, { downloads: entries, folder: dir }, { timedOut, ...(asks ? { chromeAsksWhereToSave: true } : {}) });
+}
+
+// ─── File upload (ROADMAP 0.5.4) ─────────────────────────────────────────────
+
+const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+
+/** What a file looks like when it must never leave the machine through file_upload, or null. */
+function secretLooking(file) {
+  const lower = file.toLowerCase().replace(/\\/g, '/');
+  const name = path.basename(lower);
+  const config = configDir().toLowerCase().replace(/\\/g, '/');
+  if (lower.startsWith(`${config}/`)) return 'BrowserZap\'s own data (pairing secret, licence, workflows)';
+  if (/\/\.(ssh|gnupg|aws|azure|kube|docker|config\/gcloud)\//.test(lower)) return 'a credentials folder';
+  if (/\/(google\/chrome|microsoft\/edge|bravesoftware|mozilla\/firefox)\/(user data|profiles?)\//.test(lower)) return 'a browser profile (cookies, saved passwords)';
+  if (/^(id_(rsa|dsa|ecdsa|ed25519)(\.pub)?|known_hosts|authorized_keys|\.netrc|\.npmrc|\.pypirc|\.git-credentials|credentials(\.json)?|\.env(\..+)?)$/.test(name)) return 'a key or credentials file';
+  if (/\.(pem|key|p12|pfx|jks|keystore|kdbx|ppk|ovpn)$/.test(name)) return 'a private key or password store';
+  return null;
+}
+
+/**
+ * Check a file_upload path before anything reaches the browser: absolute, an
+ * existing regular file, ≤ 50 MB, and inside BROWSERZAP_UPLOAD_DIR when that is
+ * set. The extension gets the resolved path plus the name and size it shows in
+ * the approval. The file's content is never read here.
+ */
+function checkUpload(traceId, args) {
+  const raw = String(args.path ?? '');
+  if (!path.isAbsolute(raw)) {
+    return { error: errorEnvelope(traceId, 'INVALID_ARGUMENT', 'path must be an absolute path on this computer.') };
+  }
+  let real;
+  let stat;
+  try {
+    real = fs.realpathSync(raw);
+    stat = fs.statSync(real);
+  } catch {
+    return { error: errorEnvelope(traceId, 'INVALID_ARGUMENT', `No file at ${raw}.`) };
+  }
+  if (!stat.isFile()) return { error: errorEnvelope(traceId, 'INVALID_ARGUMENT', `${raw} is not a file.`) };
+  // A page can try to talk the agent into uploading secrets (prompt injection).
+  // The person approves every file, and these are refused even then.
+  const secret = secretLooking(real);
+  if (secret) {
+    return { error: errorEnvelope(traceId, 'POLICY_BLOCKED', `${path.basename(real)} looks like ${secret}; file_upload never sends it.`, 'Choose the document the task needs, or ask the user to attach it themselves.') };
+  }
+  if (stat.size > MAX_UPLOAD_BYTES) {
+    return { error: errorEnvelope(traceId, 'INVALID_ARGUMENT', `${path.basename(real)} is ${Math.round(stat.size / 1048576)} MB; file_upload takes files up to 50 MB.`) };
+  }
+  const dir = process.env.BROWSERZAP_UPLOAD_DIR;
+  if (dir) {
+    let allowed;
+    try { allowed = fs.realpathSync(dir); } catch { allowed = path.resolve(dir); }
+    const rel = path.relative(allowed, real);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      return { error: errorEnvelope(traceId, 'POLICY_BLOCKED', `Uploads are limited to ${allowed} (BROWSERZAP_UPLOAD_DIR).`) };
+    }
+  }
+  return { args: { ...args, path: real, fileName: path.basename(real), sizeBytes: stat.size } };
+}
+
+// ─── Comment mode batches (docs/COMMENT_MODE.md) ─────────────────────────────
+
+/** Inline images per feedback_get: enough to see every comment, small enough for any client. */
+const FEEDBACK_INLINE_IMAGES = 12;
+const FEEDBACK_INLINE_BYTES = 6 * 1024 * 1024;
+const MIME_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' };
+
+function feedbackTool(traceId, toolName, args) {
+  if (toolName === 'feedback_list') {
+    const batches = feedback.list({ includeDelivered: args.includeDelivered === true });
+    const pending = batches.filter((b) => !b.delivered).length;
+    return {
+      env: okEnvelope(traceId, batches.length
+        ? `${batches.length} comment batch(es)${pending ? `, ${pending} not yet read` : ''}.`
+        : 'No comments from the person. They add them with Comment mode in the BrowserZap side panel.', { batches }),
+      extra: [],
+    };
+  }
+  const batch = feedback.get(args.id);
+  if (!batch) {
+    return {
+      env: args.id
+        ? errorEnvelope(traceId, 'INVALID_ARGUMENT', `No comment batch "${args.id}".`, 'Call feedback_list to see the batches.')
+        : okEnvelope(traceId, 'No unread comments from the person. They add them with Comment mode in the BrowserZap side panel, then press Send.', { batch: null }),
+      extra: [],
+    };
+  }
+  if (args.markDelivered !== false) feedback.markDelivered(batch.id);
+  const extra = [];
+  let bytes = 0;
+  if (args.images !== false) {
+    for (const c of batch.comments) {
+      for (const file of [c.screenshot, ...c.attachments].filter(Boolean)) {
+        if (extra.length >= FEEDBACK_INLINE_IMAGES) break;
+        try {
+          const data = fs.readFileSync(file);
+          if (bytes + data.length > FEEDBACK_INLINE_BYTES) continue;
+          bytes += data.length;
+          extra.push({ type: 'text', text: `Comment ${c.n}: ${file === c.screenshot ? 'the element' : 'image the person attached'}` });
+          extra.push({ type: 'image', data: data.toString('base64'), mimeType: MIME_BY_EXT[path.extname(file).slice(1)] ?? 'image/png' });
+        } catch { /* pruned meanwhile: the path is still listed */ }
+      }
+    }
+  }
+  const pages = [...new Set(batch.comments.map((c) => c.page.url))];
+  return {
+    env: okEnvelope(traceId,
+      `${batch.comments.length} comment(s) from the person on ${pages.length === 1 ? pages[0] : `${pages.length} pages`}.`,
+      { batch },
+      {}),
+    extra,
+  };
+}
+
 // ─── Workflows and plan (docs/WORKFLOWS.md, docs/PRO.md) ─────────────────────
 
 /** The active recording for this MCP session, if any. In memory only. */
@@ -823,7 +1000,7 @@ const backgroundRuns = createRunRegistry({
 });
 
 /** Tools that only read, allowed while a background run drives the tab. */
-const READ_WHILE_RUNNING = new Set(['browser_status', 'page_inspect', 'screenshot_capture', 'browser_list_tabs', 'browser_list_profiles']);
+const READ_WHILE_RUNNING = new Set(['browser_status', 'page_inspect', 'screenshot_capture', 'page_console', 'page_network', 'browser_list_tabs', 'browser_list_profiles']);
 
 /**
  * "5 of 5 done" / "3 of 5 done, 2 need attention" as a Chrome notification
@@ -882,7 +1059,7 @@ async function profileTool(traceId, toolName, args) {
       ? await bridgeRequest('profiles_list')
       : await bridgeRequest('profile_select', { profile: args.profile });
   } catch (err) {
-    return errorEnvelope(traceId, err.code || 'BRIDGE_DISCONNECTED', err.message, 'Run "npm run health".');
+    return errorEnvelope(traceId, err.code || 'BRIDGE_DISCONNECTED', err.message, 'Ask the user to run "browserzap doctor".');
   }
   const profiles = reply.data?.profiles ?? [];
   if (!reply.ok) {
@@ -931,7 +1108,7 @@ async function statusTool(traceId, args) {
       evidence.bridge = 'connected';
     } catch {
       return { ...errorEnvelope(traceId, 'BRIDGE_DISCONNECTED', describeBridgeProblem(),
-        'Ask the user to run "npm run health" in the BrowserZap folder.'), evidence };
+        'Ask the user to run "browserzap doctor"; every failed line says what to do.'), evidence };
     }
   }
   try {
@@ -951,6 +1128,10 @@ async function statusTool(traceId, args) {
     const result = await call.promise;
     const env = envelope(call.id, result);
     env.evidence = { ...evidence, extension: 'connected' };
+    const waiting = feedback.pendingCount();
+    if (waiting && typeof env.summary === 'string') {
+      env.summary = `${env.summary} The person sent ${waiting} comment batch(es) from Comment mode: call feedback_get.`;
+    }
     return env;
   } catch {
     evidence.extension = 'not_connected';
@@ -1012,7 +1193,11 @@ async function handleRequest(request) {
           'For a task the user repeats, record it once with workflow_record and replay it with workflow_run. ' +
           'Tabs: work in the session\'s main tab and navigate it for each new task. Open a helper with ' +
           'browser_new_tab only for a side trip (research, a comparison) and close it with browser_close_tab when done, ' +
-          'which takes you back to the main tab. A session keeps at most 3 tabs between tasks; its tabs close when it ends.',
+          'which takes you back to the main tab. A session keeps at most 3 tabs between tasks; its tabs close when it ends. ' +
+          'When the user mentions their BrowserZap feedback or comments, call feedback_get: it returns the notes they ' +
+          'made on page elements in Comment mode, with components, source files and screenshots. When debugging a page, ' +
+          'page_console and page_network show what it logged and requested. A click that downloads a file says so; ' +
+          'browser_downloads lists and waits for downloads. file_upload always needs the user\'s approval per file.',
       });
       break;
     }

package/bridge-server/native-host.js

@@ -26,7 +26,7 @@ const { getOrCreateSecret } = require('./secret');
 const { DEFAULT_PORT, PROTOCOL_VERSION, fileLogger } = require('./server');
 const { ensureBridge } = require('./ensure-bridge');
 const { helloProbe } = require('./probe');
-const { HOST_NAME, extensionOrigin } = require('./extension-id');
+const { HOST_NAME, allowedOrigins } = require('./extension-id');
 
 /** Inbound frames above this are rejected before parsing. Chrome's own host→Chrome cap is 1 MiB. */
 const MAX_MESSAGE_BYTES = 1024 * 1024;
@@ -130,7 +130,9 @@ async function handleRequest(request, options = {}) {
   });
   if (!verified.ok) {
     logLine('bridge_not_verified', { port, code: verified.code });
-    return { type: 'error', error: 'bridge_unavailable' };
+    // 4003: a BrowserZap bridge is listening but holds another install's secret
+    // (D-39). The extension shows the fix instead of staying grey.
+    return { type: 'error', error: verified.code === 4003 ? 'bridge_foreign' : 'bridge_unavailable' };
   }
   verified.ws.close();
   logLine('hello_served', { port });
@@ -141,7 +143,7 @@ function main() {
   // Defense in depth: allowed_origins is the real control, but refuse a caller
   // that is not the BrowserZap extension if Chrome tells us who it is.
   const origin = process.argv[2];
-  if (typeof origin === 'string' && origin.startsWith('chrome-extension://') && origin !== extensionOrigin()) {
+  if (typeof origin === 'string' && origin.startsWith('chrome-extension://') && !allowedOrigins().includes(origin)) {
     logLine('wrong_origin');
     process.exit(1);
   }

package/bridge-server/panel.js

@@ -39,6 +39,7 @@ const { createWorkflowService, checkStep, stepLogEntry } = require('./workflow-s
 const { createSessionLog, describeResult } = require('./session-log');
 const { parseParamSets } = require('./param-sets');
 const screenshots = require('./screenshots');
+const feedback = require('./feedback');
 
 const PANEL_SESSION = 'panel';
 const PANEL_SESSION_NAME = 'BrowserZap workflows';
@@ -424,6 +425,12 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
         case 'delete':
           workflows.remove(String(args.name));
           return { ok: true, data: {} };
+        case 'feedback_submit': {
+          // Comment mode (docs/COMMENT_MODE.md): stored on this device for the agent's feedback_get.
+          const saved = feedback.saveBatch(args.batch);
+          log('feedback_saved', { batch: saved.id, comments: saved.count });
+          return { ok: true, data: { batchId: saved.id, count: saved.count } };
+        }
         default:
           return { ok: false, error: { code: 'INVALID_ARGUMENT', message: `Unknown panel request "${op}".` } };
       }

package/bridge-server/probe.js

@@ -101,7 +101,8 @@ function nodePidsOnPort(port) {
       return [...pids].filter((pid) => /node\.exe/i.test(execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], { encoding: 'utf8', windowsHide: true })));
     }
     for (const pid of execFileSync('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8' }).split(/\s+/).filter(Boolean)) {
-      if (/node/i.test(execFileSync('ps', ['-p', pid, '-o', 'comm='], { encoding: 'utf8' }))) pids.add(pid);
+      // `comm` can be Node's thread name ("MainThread") on Linux; the command line names node.
+      if (/(^|\/)node(\.exe)?(\s|$)/i.test(execFileSync('ps', ['-p', pid, '-o', 'args='], { encoding: 'utf8' }).trim())) pids.add(pid);
     }
   } catch { /* netstat/lsof missing or nothing found */ }
   return [...pids];