browserzap 0.6.1 → 0.8.0

package/bridge-server/feedback.js

@@ -96,10 +96,14 @@ function componentOf(c) {
   };
 }
 
-function pageOf(p) {
+function pageOf(p, { optional = false } = {}) {
   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.');
+  if (!url || !/^https?:\/\//i.test(url)) {
+    // A message typed in the side panel may come from a tab with no web page (chrome://, a new tab).
+    if (optional) return null;
+    throw new FeedbackError('Every comment needs the http(s) page it was made on.');
+  }
   return {
     url,
     title: str(page.title, 200),
@@ -140,11 +144,14 @@ function saveBatch(batch, { now = new Date() } = {}) {
     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) : [];
+    // kind "message": typed in the side panel's message box, not pinned to an element.
+    const message = c.kind === 'message';
     const entry = {
       n,
+      kind: message ? 'message' : 'comment',
       text,
-      page: pageOf(c.page),
-      element: elementOf(c.info),
+      page: pageOf(c.page, { optional: message }),
+      element: message ? null : elementOf(c.info),
       component: componentOf(c.component),
       screenshot: null,
       attachments: [],
@@ -167,7 +174,11 @@ function saveBatch(batch, { now = new Date() } = {}) {
 
   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 };
+  // The agent session this batch is for (the owner of the panel's tab); null means any agent may read it.
+  const session = typeof batch.session === 'string' && /^[\w-]{1,64}$/.test(batch.session) ? batch.session : null;
+  // The tab the person wrote from: whoever reads the batch answers there, even when no agent owned the tab.
+  const tabId = Number.isInteger(batch.tabId) && batch.tabId >= 0 ? batch.tabId : null;
+  const record = { id, createdAt: now.toISOString(), session, tabId, 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 };
@@ -190,25 +201,32 @@ function batchIds() {
   }
 }
 
-/** Newest first: { id, createdAt, count, pages, delivered }. */
-function list({ includeDelivered = false } = {}) {
-  return batchIds().reverse()
+/** A batch addressed to another agent session is not this session's to read. */
+function forSession(batch, session) {
+  return !session || !batch.session || batch.session === session;
+}
+
+/** Newest first (oldest first with `oldest`): { id, createdAt, count, pages, delivered, session }. */
+function list({ includeDelivered = false, session = null, oldest = false } = {}) {
+  const ids = batchIds();
+  return (oldest ? ids : ids.reverse())
     .map((id) => readBatch(id))
-    .filter((b) => b && (includeDelivered || !b.delivered))
+    .filter((b) => b && (includeDelivered || !b.delivered) && forSession(b, session))
     .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),
+      pages: [...new Set(b.comments.map((c) => c.page?.url).filter(Boolean))].slice(0, 5),
       delivered: b.delivered,
+      session: b.session ?? null,
     }));
 }
 
-/** One batch with absolute file paths, or the newest one not yet delivered. */
-function get(id) {
-  const chosen = id ?? list()[0]?.id;
+/** One batch with absolute file paths, or the newest (`oldest`: oldest) one not yet delivered to this session. */
+function get(id, { session = null, oldest = false } = {}) {
+  const chosen = id ?? list({ session, oldest })[0]?.id;
   const batch = chosen ? readBatch(chosen) : null;
-  if (!batch) return null;
+  if (!batch || !forSession(batch, session)) return null;
   const dir = path.join(feedbackDir(), batch.id);
   return {
     ...batch,
@@ -221,6 +239,26 @@ function get(id) {
   };
 }
 
+/**
+ * A message addressed to an agent that has gone must not stay unreadable. Every
+ * undelivered batch stamped with a session that is not live loses the stamp
+ * (null = any agent may read it). Called when an agent session ends, and once at
+ * bridge start, which sweeps whatever a killed bridge left behind.
+ */
+function releaseOrphans({ session = null, liveSessionIds = new Set() } = {}) {
+  let released = 0;
+  for (const id of batchIds()) {
+    const batch = readBatch(id);
+    if (!batch || batch.delivered || !batch.session) continue;
+    if (session && batch.session !== session) continue;
+    if (liveSessionIds.has(batch.session)) continue;
+    batch.session = null;
+    writePrivate(path.join(feedbackDir(), id, 'batch.json'), JSON.stringify(batch, null, 2));
+    released++;
+  }
+  return released;
+}
+
 function markDelivered(id, { now = new Date() } = {}) {
   const batch = readBatch(id);
   if (!batch || batch.delivered) return false;
@@ -230,8 +268,8 @@ function markDelivered(id, { now = new Date() } = {}) {
   return true;
 }
 
-function pendingCount() {
-  return list().length;
+function pendingCount({ session = null } = {}) {
+  return list({ session }).length;
 }
 
 /** Delete batches older than the retention, and the oldest beyond MAX_BATCHES. Never throws. */
@@ -252,4 +290,4 @@ function prune({ now = Date.now(), days = keepDays() } = {}) {
   return removed;
 }
 
-module.exports = { saveBatch, list, get, markDelivered, pendingCount, prune, feedbackDir, FeedbackError, MAX_COMMENTS };
+module.exports = { saveBatch, list, get, markDelivered, pendingCount, releaseOrphans, prune, feedbackDir, FeedbackError, MAX_COMMENTS };

package/bridge-server/index.js

@@ -4,9 +4,10 @@
  * BrowserZap — entry point.
  *
  * When used as an MCP server (the primary use case), this starts the MCP
- * server, which embeds the WebSocket bridge. The Chrome extension is installed
- * separately; pass --extension to plant a copy under the user's home directory
- * and print the path for a "Load unpacked" install.
+ * server, which embeds the WebSocket bridge. The Chrome extension comes from
+ * the Chrome Web Store and updates itself; a developer working from a source
+ * checkout can pass --extension to copy the built build under the user's home
+ * directory and print the path for a "Load unpacked" install.
  *
  * Derived from Open Browser Control (MIT, Copyright (c) 2026 smankoo) at commit
  * 4e6c262. BrowserZap drops the Firefox target and rebrands.
@@ -17,7 +18,7 @@
  * Standalone:
  *   node bridge-server/index.js                 # MCP mode (default)
  *   node bridge-server/index.js --bridge        # standalone WebSocket bridge
- *   node bridge-server/index.js --extension     # install + print the extension path
+ *   node bridge-server/index.js --extension     # copy + print the built extension (developer)
  *   node bridge-server/index.js --uninstall     # remove the installed extension copy
  *   node bridge-server/index.js --print-token   # print the pairing token
  */
@@ -28,6 +29,7 @@ const os = require('os');
 
 const { getOrCreateSecret, secretPath, configDir } = require('./secret');
 const { DEFAULT_PORT } = require('./server');
+const { STORE_URL } = require('./setup');
 
 const args = process.argv.slice(2);
 
@@ -82,18 +84,29 @@ function syncDir(src, dest) {
   prune(dest, dest);
 }
 
+/**
+ * The extension build inside this package, or null.
+ *
+ * npm ships the bridge only (D3), so an installed copy has neither folder and
+ * nothing to copy. A source checkout has extension/ after `npm run build`, or
+ * dist/chrome when webpack output is all that exists yet.
+ */
+function builtExtensionDir() {
+  for (const candidate of [path.join(__dirname, '..', 'extension'), path.join(__dirname, '..', 'dist', 'chrome')]) {
+    if (fs.existsSync(path.join(candidate, 'manifest.json'))) return candidate;
+  }
+  return null;
+}
+
 function installExtension({ quiet = false } = {}) {
   const say = quiet ? () => {} : log;
-  const bundled = path.join(__dirname, '..', 'extension');
-
-  if (!fs.existsSync(path.join(bundled, 'manifest.json'))) {
-    // Dev mode — fall back to the raw webpack output.
-    const devDist = path.join(__dirname, '..', 'dist', 'chrome');
-    if (fs.existsSync(path.join(devDist, 'manifest.json'))) {
-      syncDir(devDist, EXTENSION_HOME);
-      return true;
-    }
-    say('Pre-built extension not found. Run "npm run build" first.');
+  const bundled = builtExtensionDir();
+
+  if (!bundled) {
+    // The store is the install path for a user; this flag is a developer tool.
+    process.stdout.write('The extension is not part of the npm package. Install it from the Chrome Web Store:\n');
+    process.stdout.write(`  ${STORE_URL}\n`);
+    process.stdout.write('(Chrome keeps it updated. "browserzap --extension" only works from a source checkout.)\n');
     return false;
   }
 
@@ -119,8 +132,9 @@ function installExtension({ quiet = false } = {}) {
   say(`  4. Select: ${EXTENSION_HOME}`);
   say('');
   say('One-time setup (registers the native messaging host, so the extension');
-  say('connects automatically with no token to paste):');
-  say('  browserzap setup');
+  say('connects automatically with no token to paste; --dev lets this unpacked');
+  say('build in, which the store build does not need):');
+  say('  browserzap setup --dev');
   say('');
   return true;
 }
@@ -277,13 +291,10 @@ if (require('./setup').insideWsl() && !process.env.BROWSERZAP_ALLOW_LINUX) {
 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
-  // upgrade or an npm cache clean, so "Load unpacked" names a path that stays
-  // valid. A source checkout loads its own extension/ folder.
-  const checkout = fs.existsSync(path.join(__dirname, '..', 'src', 'manifest.json'));
-  const extensionPath = checkout
-    ? path.join(__dirname, '..', 'extension')
-    : installExtension({ quiet: true }) ? EXTENSION_HOME : null;
+  // A source checkout has a built extension to load unpacked; an npm install has
+  // none, and the store build is the extension there (D3). Nothing is copied:
+  // setup only names the path a developer already has.
+  const extensionPath = builtExtensionDir();
   require('./setup').setupCommand(args.slice(1), { extensionPath })
     .then((code) => process.exit(code))
     .catch((err) => {
@@ -493,6 +504,7 @@ browserzap — let an AI agent act on the browser tab you already have open.
 Usage:
   browserzap setup                      One-time setup: register the native messaging host and
                                         optionally add the MCP server to detected clients
+  browserzap setup --dev                Allow the unpacked developer build to connect (store-only otherwise)
   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
@@ -501,7 +513,7 @@ Usage:
                                         more than one). Exit code 0 when every run completed
   browserzap                            Start the MCP server (default)
   browserzap --bridge                   Start the standalone WebSocket bridge
-  browserzap --extension                Install + print the extension path
+  browserzap --extension                Developer: copy the built extension to the install folder (source checkout only)
   browserzap --uninstall                Remove the installed extension copy (keeps your data)
   browserzap --uninstall --purge
                                         Also remove the config folder (pairing token,

package/bridge-server/limits.js

@@ -22,6 +22,13 @@ const LIMITS = Object.freeze({
   APPROVAL_HOLD_MS: 20000,
   /** A click or key press without `expect` watches this long for the page to react. */
   DEFAULT_SETTLE_MS: 1500,
+  /**
+   * After a click started a request, how long to keep watching for a navigation
+   * once the page has settled. A form POST in a background tab can navigate a
+   * moment after the visible change, and the evidence must not say `navigated:
+   * false` (B-02). A bounded poll, never a fixed sleep.
+   */
+  NAVIGATION_FOLLOW_MS: 1200,
   /** Before acting, the page must have had no tracked request in flight for this long. */
   SETTLE_QUIET_MS: 500,
   /** How long that settle waits for a busy page (it costs nothing on a quiet one). */
@@ -36,7 +43,7 @@ const LIMITS = Object.freeze({
   /** 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,
+  DEBUGGER_IDLE_MS: 300000,
   /** 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. */
@@ -93,7 +100,8 @@ function callDeadlineMs(tool, args = {}) {
     case 'element_click':
       // find the target, maybe hold for an approval, then watch the result
       waits = (asked ?? LIMITS.DEFAULT_TARGET_WAIT_MS) + LIMITS.APPROVAL_HOLD_MS
-        + (asked ?? (args?.expect ? LIMITS.DEFAULT_EXPECT_TIMEOUT_MS : LIMITS.DEFAULT_SETTLE_MS));
+        + (asked ?? (args?.expect ? LIMITS.DEFAULT_EXPECT_TIMEOUT_MS : LIMITS.DEFAULT_SETTLE_MS))
+        + LIMITS.NAVIGATION_FOLLOW_MS;
       break;
     case 'browser_press_key':
       waits = LIMITS.APPROVAL_HOLD_MS + LIMITS.DEFAULT_SETTLE_MS;
@@ -114,9 +122,20 @@ function callDeadlineMs(tool, args = {}) {
   return Math.max(CALL_DEADLINE_MS, waits + DEADLINE_MARGIN_MS);
 }
 
+/**
+ * feedback_wait (the chat listener): how long one call waits for the person by default and at most, and how often
+ * it looks. A bounded poll of the local feedback folder (ADR-007); progress keeps the client from timing out.
+ */
+const FEEDBACK_WAIT_DEFAULT_MS = 60_000;
+const FEEDBACK_WAIT_MAX_MS = 300_000;
+const FEEDBACK_POLL_MS = 500;
+
 module.exports = {
   LIMITS,
   CALL_DEADLINE_MS,
+  FEEDBACK_WAIT_DEFAULT_MS,
+  FEEDBACK_WAIT_MAX_MS,
+  FEEDBACK_POLL_MS,
   STATUS_DEADLINE_MS,
   RUN_DEADLINE_MS,
   MAX_STEP_RESOLVE_MS,

package/bridge-server/mcp-server.js

@@ -30,8 +30,9 @@ const path = require('path');
 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');
+const { LIMITS, CALL_DEADLINE_MS, STATUS_DEADLINE_MS, FEEDBACK_WAIT_DEFAULT_MS, FEEDBACK_WAIT_MAX_MS, FEEDBACK_POLL_MS } = require('./limits');
 const chromeLauncher = require('./chrome-launcher');
+const { MIN_EXTENSION_VERSION, isOlderThan } = require('./extension-version');
 const { MCP_TOOLS, LOCAL_TOOLS, validateArguments } = require('./tools');
 const { currentPlan, hasFeature } = require('./entitlements');
 const { envelope, errorEnvelope, executeStep, createActionClient } = require('./executor');
@@ -160,6 +161,12 @@ function connectToBridge() {
       }
       return;
     }
+    // The person sent a message or notes from the side panel: a waiting feedback_wait reads it now (feedbackWait).
+    if (msg.type === 'event' && msg.event === 'feedback_new') {
+      if (feedbackWaiters.size) log('feedback_nudged', { waiting: feedbackWaiters.size });
+      feedbackWaiters.forEach((wake) => wake());
+      return;
+    }
     // The person pressed Stop on the page (or took control in the side panel):
     // a background batch stops with the step in flight.
     if (msg.type === 'event' && msg.event === 'user_handoff') {
@@ -223,6 +230,26 @@ function updateSessionName(name) {
   }
 }
 
+/** Running feedback_wait calls, woken by the bridge's feedback_new event; the folder poll stays as the fallback. */
+const feedbackWaiters = new Set();
+
+/** The side panel shows "listening" while feedback_wait runs. */
+function updateListening(listening) {
+  if (sessionStarted && ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ type: 'session_update', session: SESSION_ID, listening }));
+  }
+}
+
+/**
+ * The tab the last batch came from: the extension shows this session's replies there. Needed when the person
+ * writes from a tab no agent owned — the batch is unaddressed, but the answer still belongs in that tab.
+ */
+function updateChatTab(tabId) {
+  if (sessionStarted && ws?.readyState === WebSocket.OPEN && Number.isInteger(tabId) && tabId >= 0) {
+    ws.send(JSON.stringify({ type: 'session_update', session: SESSION_ID, chatTabId: tabId }));
+  }
+}
+
 /** Requests answered by the bridge itself (Chrome profiles), matched by id. */
 const bridgeReplies = new Map();
 let bridgeSeq = 0;
@@ -482,6 +509,12 @@ async function callToolWith(progress, requestId, toolName, args) {
   const started = Date.now();
   const traceId = `${SESSION_ID}-t${++traceSeq}`;
   const finish = (env, extraContent) => {
+    // The person can message the agent from the side panel at any time; the
+    // agent learns of it on its next call. browser_status says it itself.
+    if (toolName !== 'browser_status' && !toolName.startsWith('feedback_') && typeof env.summary === 'string') {
+      const waiting = feedback.pendingCount({ session: SESSION_ID });
+      if (waiting) env.summary = `${env.summary} ${unreadFeedbackNote(waiting)}`;
+    }
     log('tool_call', {
       tool: toolName,
       traceId: env.traceId,
@@ -519,6 +552,11 @@ async function callToolWith(progress, requestId, toolName, args) {
     return finish(env, extra);
   }
 
+  if (toolName === 'feedback_wait') {
+    const { env, extra } = await feedbackWait(requestId, traceId, args, progress);
+    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();
@@ -557,6 +595,24 @@ async function callToolWith(progress, requestId, toolName, args) {
   }
 }
 
+/**
+ * An action the connected build does not know (an extension older than the tool
+ * surface, src/actions/browser-actions.ts) comes back as `Unknown action: …`
+ * with INVALID_ARGUMENT. Report that as `needs_user` naming the build, so the
+ * person is told to update instead of the agent retrying a call that cannot
+ * work. Same code, same `ok`, the call itself is not refused here.
+ */
+async function nameUnsupportedAction(env) {
+  if (env.ok !== false || env.error?.code !== 'INVALID_ARGUMENT') return;
+  if (typeof env.error.message !== 'string' || !env.error.message.startsWith('Unknown action:')) return;
+  const version = await connectedExtensionVersion();
+  env.state = 'needs_user';
+  env.summary = version
+    ? `The BrowserZap extension (${version}) does not support this action; update it from chrome://extensions → Update.`
+    : 'The BrowserZap extension does not support this action and did not report its version, which means it is older than 0.7.0; update it from chrome://extensions → Update.';
+  env.nextAction = 'Ask the user to update the BrowserZap extension. Chrome updates store extensions by itself; to update now open chrome://extensions → Update.';
+}
+
 /**
  * Run one browser tool through the extension and build its envelope. Live
  * calls and workflow steps both come through here, so a replayed step gets
@@ -565,6 +621,7 @@ async function callToolWith(progress, requestId, toolName, args) {
  */
 async function executeTool(toolName, args, { allowedOrigins = ALLOWED_ORIGINS, onStart } = {}) {
   const env = await executeStep(startAction, toolName, args, { allowedOrigins, onStart });
+  await nameUnsupportedAction(env);
   const extra = [];
   if (typeof env.screenshot === 'string') {
     const format = env.format || 'jpeg';
@@ -677,14 +734,19 @@ function checkUpload(traceId, args) {
 
 // ─── Comment mode batches (docs/COMMENT_MODE.md) ─────────────────────────────
 
+/** The sentence that tells the agent the person is waiting for it to read something. */
+function unreadFeedbackNote(waiting) {
+  return `The person sent ${waiting} comment batch(es) or message(s) from the BrowserZap side panel: call feedback_get now and act on them.`;
+}
+
 /** 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) {
+function feedbackTool(traceId, toolName, args, options = {}) {
   if (toolName === 'feedback_list') {
-    const batches = feedback.list({ includeDelivered: args.includeDelivered === true });
+    const batches = feedback.list({ includeDelivered: args.includeDelivered === true, session: SESSION_ID });
     const pending = batches.filter((b) => !b.delivered).length;
     return {
       env: okEnvelope(traceId, batches.length
@@ -693,7 +755,7 @@ function feedbackTool(traceId, toolName, args) {
       extra: [],
     };
   }
-  const batch = feedback.get(args.id);
+  const batch = feedback.get(args.id, { session: SESSION_ID, oldest: options.oldest === true });
   if (!batch) {
     return {
       env: args.id
@@ -703,6 +765,8 @@ function feedbackTool(traceId, toolName, args) {
     };
   }
   if (args.markDelivered !== false) feedback.markDelivered(batch.id);
+  // Whoever read it answers in the tab it was written from (a reply with no tab would show in no panel at all).
+  if (Number.isInteger(batch.tabId)) updateChatTab(batch.tabId);
   const extra = [];
   let bytes = 0;
   if (args.images !== false) {
@@ -719,14 +783,58 @@ function feedbackTool(traceId, toolName, args) {
       }
     }
   }
-  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,
-  };
+  const pages = [...new Set(batch.comments.map((c) => c.page?.url).filter(Boolean))];
+  const messages = batch.comments.filter((c) => c.kind === 'message').length;
+  const pinned = batch.comments.length - messages;
+  const what = [messages ? `${messages} message(s)` : '', pinned ? `${pinned} comment(s)` : ''].filter(Boolean).join(' and ');
+  const where = pages.length === 0 ? '' : ` on ${pages.length === 1 ? pages[0] : `${pages.length} pages`}`;
+  const env = okEnvelope(traceId, `${what} from the person${where}.`, { batch }, {});
+  // The person reads the side panel, not the agent's terminal: an answer written anywhere else never reaches them.
+  if (messages) {
+    env.nextAction = 'The person is waiting in the BrowserZap side panel: put your answer there with chat_reply (Markdown is '
+      + 'shown). Text you write in your own chat is not shown to them.';
+  }
+  return { env, extra };
+}
+
+/**
+ * feedback_wait, the chat listener: returns the person's next message or note batch for this session (oldest
+ * first, like feedback_get), or says nothing came within waitMs. A bounded poll of the local folder; the panel
+ * shows "listening" meanwhile; a cancelled request stops at once.
+ */
+async function feedbackWait(requestId, traceId, args, progress) {
+  const waitMs = Math.min(Math.max(Number.isInteger(args.waitMs) ? args.waitMs : FEEDBACK_WAIT_DEFAULT_MS, 1000), FEEDBACK_WAIT_MAX_MS);
+  const deadline = Date.now() + waitMs;
+  let cancelled = false;
+  let wake = null;
+  inflightByRequest.set(requestId, { cancel() { cancelled = true; wake?.(); } });
+  const nudge = () => wake?.();
+  feedbackWaiters.add(nudge);
+  updateListening(true);
+  progress.heartbeat(() => 'Listening for the person in the BrowserZap side panel');
+  try {
+    while (!cancelled) {
+      if (feedback.pendingCount({ session: SESSION_ID }) > 0) {
+        return feedbackTool(traceId, 'feedback_get', { images: args.images }, { oldest: true });
+      }
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await new Promise((resolve) => {
+        wake = resolve;
+        setTimeout(resolve, Math.min(FEEDBACK_POLL_MS, left));
+      });
+    }
+    const seconds = Math.round(waitMs / 1000);
+    const env = okEnvelope(traceId,
+      cancelled ? 'Stopped listening.' : `No message from the person in ${seconds} s.`,
+      { batch: null, timedOut: !cancelled });
+    if (!cancelled) env.nextAction = 'Call feedback_wait again to keep listening, or stop when the person is done.';
+    return { env, extra: [] };
+  } finally {
+    inflightByRequest.delete(requestId);
+    feedbackWaiters.delete(nudge);
+    updateListening(false);
+  }
 }
 
 // ─── Workflows and plan (docs/WORKFLOWS.md, docs/PRO.md) ─────────────────────
@@ -1014,7 +1122,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', 'page_console', 'page_network', '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', 'chat_reply']);
 
 /**
  * "5 of 5 done" / "3 of 5 done, 2 need attention" as a Chrome notification
@@ -1100,6 +1208,38 @@ function planEvidence() {
   return { plan, licenseStatus, features, limits, expiresAt, notice, proPackage: Boolean(pro), recording: recorder ? recorder.name : null };
 }
 
+/** The profile a status/report should speak about: the selected one, else the first. */
+function relevantProfile(profiles) {
+  if (!Array.isArray(profiles) || profiles.length === 0) return null;
+  return profiles.find((p) => p.selected) ?? profiles[0];
+}
+
+/** The version the connected extension reported, or null when it is older than 0.7.0 (WP5). */
+async function connectedExtensionVersion() {
+  try {
+    const reply = await bridgeRequest('profiles_list', {}, 1500);
+    if (reply?.ok !== true) return null;
+    const profile = relevantProfile(reply.data?.profiles);
+    return typeof profile?.extensionVersion === 'string' ? profile.extensionVersion : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What browser_status says about a store build that lags this bridge (WP5, F4).
+ * A notice only: `ok` never changes and no call is ever refused for it.
+ */
+function extensionVersionNotice(version) {
+  if (version === null) {
+    return 'The BrowserZap extension did not report its version, which means it is older than 0.7.0. Chrome updates store extensions automatically; to update now open chrome://extensions → Update.';
+  }
+  if (isOlderThan(version, MIN_EXTENSION_VERSION)) {
+    return `The BrowserZap extension is older than this bridge (${version} < ${MIN_EXTENSION_VERSION}). Chrome updates store extensions automatically; to update now open chrome://extensions → Update.`;
+  }
+  return null;
+}
+
 async function statusTool(traceId, args) {
   const evidence = {
     bridge: sessionStarted ? 'connected' : lastCloseCode === 4003 ? 'unauthorized' : lastCloseCode === 4005 ? 'version_mismatch' : 'unreachable',
@@ -1117,6 +1257,7 @@ async function statusTool(traceId, args) {
     sessionLog: process.env.BROWSERZAP_LOG === 'off' ? null : sessionLog.file(),
     screenshots: { folder: screenshots.screenshotDir(), keepDays: screenshots.keepDays() },
     profiles: null,
+    extensionVersion: null,
   };
   if (!sessionStarted) {
     try {
@@ -1131,12 +1272,17 @@ async function statusTool(traceId, args) {
     const reply = await bridgeRequest('profiles_list', {}, 1500);
     evidence.profiles = reply.data?.profiles ?? null;
   } catch { /* an older bridge: no profile list */ }
+  evidence.extensionVersion = relevantProfile(evidence.profiles)?.extensionVersion ?? null;
   if (Array.isArray(evidence.profiles) && evidence.profiles.length > 1 && !evidence.profiles.some((p) => p.selected)) {
+    // The extension did answer (with its profile list), so the version notice
+    // belongs here too; the error itself is unchanged.
+    const notice = extensionVersionNotice(evidence.extensionVersion);
     return {
       ...errorEnvelope(traceId, 'PROFILE_REQUIRED',
         `${evidence.profiles.length} Chrome profiles are connected (${evidence.profiles.map((p) => `"${p.label}"`).join(', ')}). Choose one first.`,
         'Call browser_select_profile with the profile the user means.'),
       evidence: { ...evidence, extension: 'connected' },
+      ...(notice ? { notice } : {}),
     };
   }
   const call = startAction('status', { includeTab: args.includeTab === true }, STATUS_DEADLINE_MS);
@@ -1144,9 +1290,11 @@ 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();
+    const notice = extensionVersionNotice(evidence.extensionVersion);
+    if (notice) env.notice = notice;
+    const waiting = feedback.pendingCount({ session: SESSION_ID });
     if (waiting && typeof env.summary === 'string') {
-      env.summary = `${env.summary} The person sent ${waiting} comment batch(es) from Comment mode: call feedback_get.`;
+      env.summary = `${env.summary} ${unreadFeedbackNote(waiting)}`;
     }
     return env;
   } catch {
@@ -1211,7 +1359,9 @@ async function handleRequest(request) {
           '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. ' +
           '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, ' +
+          'made on page elements in Comment mode, with components, source files and screenshots. The user can also type ' +
+          'to you in the side panel: answer with chat_reply. When they ask you to listen to them in BrowserZap, call ' +
+          'feedback_wait, act or answer, and call it again until they are done. 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.',
       });