poltertab 1.8.0-beta.2 → 1.8.0

package/README.md

@@ -244,21 +244,82 @@ themselves into **secondary** mode, proxying their commands through the primary,
 so concurrent agents share one browser with no extra configuration. The
 primary tags each secondary's commands with its id, and the extension keeps a
 separate current tab per agent, so agents get their own tabs. Up to
-50 secondaries are accepted (set `POLTERTAB_MAX_SECONDARIES` to change the
-limit). A secondary refused for capacity is told why and retries with backoff
-(2s doubling to 60s) instead of looping. If the primary exits, exactly one
-secondary promotes itself to replace it and the others reconnect to it. The
-extension popup lists whichever agents are connected.
-
-A secondary that sends no command for 5 minutes gives up its slot and
-reconnects on its next tool call (`POLTERTAB_IDLE_EVICTION_MS`). The primary
-sends at most 6 commands to the extension at once
-(`POLTERTAB_MAX_CONCURRENCY`) and queues up to 3 more per secondary
-(`POLTERTAB_QUEUE_DEPTH`), taking turns between secondaries. A command beyond
-that fails at once with `[queue_full]`; one that waits longer than 60s fails
-with `[queue_timeout]` and never runs (`POLTERTAB_QUEUE_TIMEOUT_MS`).
-`curl http://127.0.0.1:7822/status` shows the primary's secondaries and queue.
-It answers on this machine only.
+`POLTERTAB_MAX_SECONDARIES` v2 secondaries are accepted (default 50); if the
+primary exits, one secondary promotes itself to replace it. The extension popup
+lists whichever agents are connected.
+
+**How many agents can share one browser:**
+Up to 50 v2 secondaries (one process each) plus the primary can share one
+browser. Raise or lower the ceiling with `POLTERTAB_MAX_SECONDARIES`. An agent
+that is idle for `POLTERTAB_IDLE_EVICTION_MS` (default 5 minutes) is evicted
+with close code 4001 to free the slot; it reconnects automatically the next time
+it sends a command, so eviction is transparent to the agent. An agent whose
+major version does not match the primary's is refused with close code 4002 —
+see [Upgrade path](#upgrade-path-1x--18) below.
+
+**Command queue:**
+The primary limits how many commands it sends to the extension at once
+(`POLTERTAB_MAX_CONCURRENCY`, default 6). When that limit is reached, a v2
+secondary's command is queued per-secondary (up to `POLTERTAB_QUEUE_DEPTH`
+slots, default 3). The queued command is acknowledged immediately with
+`{"type":"queued","id":"...","position":N}` so the caller knows its command is
+pending, not lost. A v2 secondary re-arms its 35 s timeout on this
+acknowledgement and again on `{"type":"dispatched","id":"..."}` when the command
+leaves the queue, so queue wait never consumes the execution budget. A command
+that arrives when the per-secondary queue is already full is refused immediately
+with `[queue_full action=X]`. The primary itself queues its own direct commands
+under the same ceiling. A queued command is dropped with `[queue_timeout action=X]`
+when the caller's 35 s budget is nearly spent (a 2 s margin keeps the drop ahead
+of the caller's own timer). `POLTERTAB_QUEUE_TIMEOUT_MS` (default 60 s) is a
+separate GC backstop for commands in a queue that never gets dequeued; it does
+not extend queue wait time.
+
+**`/status` endpoint:**
+`GET http://127.0.0.1:7822/status` returns a JSON snapshot of the primary's
+queue state, connected agents, and wait-time percentiles (p50/p95/p99). It is
+restricted to loopback callers (`127.0.0.1`, `::1`, or `::ffff:127.0.0.1`) and
+to requests whose `Host` header names `localhost` or a loopback address; all
+others receive 404.
+
+**Extension reconnection:**
+The Chrome extension reconnects automatically when the bridge server restarts or
+the WebSocket drops. It dials immediately on disconnect, then backs off 1 s,
+2 s, 4 s … up to 30 s, with an alarm that wakes the service worker if it was
+suspended mid-schedule. While reconnecting, commands return:
+
+- `[extension_reconnecting port=7822 elapsed=Xs]` — the extension disconnected
+  and is on its way back. Retry shortly.
+- `[extension_never_connected port=7822]` — the extension has never connected to
+  this server instance. Check that the extension is installed, enabled, and
+  pointed at the right port.
+
+**Close codes:**
+
+| Code | Meaning | Agent behaviour |
+|------|---------|-----------------|
+| 4001 | Idle eviction — the agent was silent for `POLTERTAB_IDLE_EVICTION_MS` | Secondary dials again lazily on next command; no action needed |
+| 4002 | Version mismatch — major version incompatible with the primary | Secondary stops retrying until restarted; update the npm package so every session runs the same major |
+
+**Upgrade path (1.x → 1.8):**
+PolterTab 1.8 introduces a version handshake. A secondary whose major version
+does not match the primary's receives close code 4002 and stops retrying; updating
+the npm package (so all sessions run the same major) resolves it. The Chrome
+extension should also be updated at the same time to get the PR-4 reconnect
+behaviour. Run `poltertab doctor` to check for skew before upgrading. A 1.7.x
+secondary that has not upgraded does not receive 4002 (it does not speak the
+handshake) and continues to work as an unversioned legacy secondary; it bypasses
+the command queue and is never idle-evicted.
+
+**Env vars:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `POLTERTAB_MAX_SECONDARIES` | `50` | Maximum v2 secondaries accepted |
+| `POLTERTAB_IDLE_EVICTION_MS` | `300000` (5 min) | Idle before a v2 secondary is evicted with 4001 |
+| `POLTERTAB_MAX_CONCURRENCY` | `6` | Extension command concurrency limit |
+| `POLTERTAB_QUEUE_DEPTH` | `3` | Per-secondary queue depth before `[queue_full]` |
+| `POLTERTAB_QUEUE_TIMEOUT_MS` | `60000` (60 s) | GC backstop for stuck queued commands (does not extend queue wait) |
+| `POLTERTAB_COMMAND_TIMEOUT_MS` | `35000` (35 s) | Per-command budget. Must exceed the extension's 30 s navigation wait + 500 ms settle; tune for tests only |
 
 **Changing the WebSocket Port:**
 Only needed when something that *isn't* PolterTab already holds `7822` —

package/mcp-server/bridge.js

@@ -15,7 +15,6 @@ const crypto = require("crypto");
 const net = require("net");
 const {
   resolvePort,
-  DEFAULT_WS_PORT,
   COMMAND_TIMEOUT_MS,
   HEARTBEAT_MS,
   NETWORK_TTL_MS,
@@ -45,6 +44,11 @@ let extensionVersion = null;
 
 // Global state
 let extensionSocket = null;
+// When the extension last left this Primary; null if it never connected. A
+// missing extension is either on its way back (a Primary handover, a worker
+// restart: retry shortly) or was never here (Chrome closed, extension off,
+// wrong port: go and look). The agent needs to know which.
+let extensionLostAt = null;
 const pendingCommands = new Map();
 const networkState = new Map(); // tabId -> { lastUpdated: number, requests: array }
 const secondaryClients = new Map();
@@ -54,7 +58,7 @@ let isSecondary = false;
 let nodeId = null;
 let wss = null;
 let httpServer = null;
-let httpServer6 = null; // IPv6 loopback companion; null if host has no IPv6
+// (httpServer6 removed — wildcard bind covers ::1; see fix/legacy-bind)
 
 // Secondary-side retry state. One counter for the whole reconnect/probe/promote
 // cycle, reset only by a Primary's secondary_accepted; `refusal` and
@@ -72,6 +76,17 @@ let unreachable = false;
 let isEvicted = false;
 let reconnect = null; // { promise, resolve, reject, timer }
 
+// Set once a Primary has accepted this node. If it later promotes, the
+// extension was almost certainly on the Primary that died and is on its way
+// here, so "reconnecting" is the honest answer, not "never connected". A node
+// never accepted has no reason to believe an extension exists.
+let everAccepted = false;
+
+// A 4002 from the Primary: this node's major version cannot talk to it.
+// Retrying cannot help until one side is upgraded, which means a restart, so
+// the node stops here — no redial, no promotion — and every command says why.
+let incompatible = null; // the Primary's close reason
+
 // Command queue, Primary side (PR-3). At most MAX_EXTENSION_CONCURRENCY
 // commands may be in flight to the extension at once. v2 Secondary commands
 // beyond that wait in a per-secondary FIFO, served round-robin across
@@ -147,7 +162,7 @@ function _tryDequeue() {
     if (!extensionSocket || extensionSocket.readyState !== WebSocket.OPEN) {
       if (item.callerWs && item.callerWs.readyState === WebSocket.OPEN) {
         item.callerWs.send(
-          JSON.stringify({ id: item.id, success: false, error: "Browser extension not connected to Primary." }),
+          JSON.stringify({ id: item.id, success: false, error: extensionMissing() }),
         );
       }
       continue;
@@ -163,6 +178,46 @@ function _tryDequeue() {
   }
 }
 
+function extensionMissing() {
+  if (extensionLostAt === null) {
+    return (
+      `[extension_never_connected port=${WS_PORT}] Browser extension not connected: it has never connected to this server. ` +
+      `Check that Chrome is open and the PolterTab extension is installed, enabled, and set to port ${WS_PORT}.`
+    );
+  }
+  const s = Math.round((Date.now() - extensionLostAt) / 1000);
+  return (
+    `[extension_reconnecting port=${WS_PORT} elapsed=${s}s] Browser extension not connected: ` +
+    `it disconnected ${s}s ago and reconnects on its own. Retry shortly.`
+  );
+}
+
+function incompatibleError() {
+  return (
+    `[version_incompatible] The Primary on port ${WS_PORT} requires PolterTab ${incompatible.required || "another major version"}; ` +
+    `this server is ${incompatible.got || OWN_VERSION}. Run: npm update -g poltertab, then restart every session using this browser.`
+  );
+}
+
+// The 4002 close reason. RFC 6455 caps it at 123 bytes and ws throws past
+// that — which used to leave the peer unclosed and retrying forever. `got`
+// is peer-supplied, so it is cut to printable ASCII and shortened until the
+// encoded reason fits.
+function versionReason(ours, theirs) {
+  let got = String(theirs).replace(/[^\x20-\x7e]/g, "?").slice(0, 32);
+  const build = () =>
+    JSON.stringify({ reason: "version_incompatible", required: `${ours}.x`, got });
+  while (Buffer.byteLength(build()) > 123) got = got.slice(0, -1);
+  return build();
+}
+
+// "1.7.0" -> 1. Anything else (a label like "test", a missing field) has no
+// major to disagree with, so it never triggers a 4002.
+function majorOf(version) {
+  const m = /^(\d+)\./.exec(String(version));
+  return m ? Number(m[1]) : null;
+}
+
 function broadcastSessionState() {
   if (extensionSocket && extensionSocket.readyState === WebSocket.OPEN) {
     const sessions = [];
@@ -216,8 +271,22 @@ function allowOrigin(info, cb) {
 
 function setupPrimaryServer() {
   const http = require("http");
+  const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+  // The source address alone does not stop DNS rebinding: a page at
+  // http://evil.example:P whose name then resolves to 127.0.0.1 fetches
+  // /status same-origin, from loopback. Its Host header still names
+  // evil.example, so only a loopback name (any port, or none) is answered.
+  const LOOPBACK_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
   const handleRequest = (req, res) => {
     if (req.method === "GET" && req.url === "/status") {
+      if (
+        !LOOPBACK.has(req.socket.remoteAddress) ||
+        !LOOPBACK_HOST.test(req.headers.host || "")
+      ) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
       const now = Date.now();
       const secondaries = [];
       for (const [nid, ws] of secondaryClients.entries()) {
@@ -268,26 +337,25 @@ function setupPrimaryServer() {
       httpServer.close();
       httpServer = null;
       startSecondaryMode();
-      // NICE-2 residual race: a legacy (wildcard-binding) PolterTab that starts
-      // in the ms between a successful probe and our listen() call will bind
-      // undetected on macOS — SO_REUSEADDR lets 127.0.0.1 bind over 0.0.0.0,
-      // so the new loopback Primary dual-binds silently.  That window is
-      // milliseconds and requires two simultaneous starts; not worth a retry
-      // loop, but do not remove the probe and rely on this handler alone.
     } else {
       console.error(`[PolterTab MCP] HTTP server error: ${e.message}`);
     }
   });
 
-  // Why probe-first (SHOULD-1 narrative, real reason for this change):
-  // PR-3 routes /status to loopback only, so the whole Primary now binds
-  // 127.0.0.1 instead of 0.0.0.0.  On macOS, libuv sets SO_REUSEADDR, and
-  // BSD/macOS lets a specific-address bind succeed silently over a live
-  // wildcard listener — so the new loopback-binding Primary would start beside
-  // a pre-1.8 (wildcard) PolterTab without getting EADDRINUSE, then steal all
-  // loopback traffic.  S11 is the regression test: it places a wildcard fixture
-  // and asserts the bridge-under-test demotes instead of dual-binding.  The
-  // EADDRINUSE handler above remains as the fallback for same-host races.
+  // Why probe-first (SHOULD-1 narrative):
+  // We bind :: (IPv6 wildcard, dual-stack) so a second wildcard bind from a
+  // legacy 1.7.x/beta.1 server gets EADDRINUSE on every platform.  But on
+  // macOS SO_REUSEADDR, a wildcard bind does NOT give EADDRINUSE when the
+  // existing listener is a specific-address bind (127.0.0.1/::1) — the old
+  // regression this PR fixes.  The probe detects a real primary already
+  // serving 127.0.0.1 and demotes us before we call listen(), avoiding a
+  // race in the milliseconds between a successful probe and our own bind.
+  // The EADDRINUSE handler above covers the symmetric case.
+  // The one window left: on macOS, a beta.2-style server binding 127.0.0.1/::1
+  // specifically *between* our probe and our listen. Our wildcard listen then
+  // succeeds beside it and its specific bind wins loopback traffic, leaving us
+  // a silent Primary. It needs two starts within milliseconds, one of them
+  // the superseded beta.2, whose own probe-first makes it lose that race.
   probePrimary().then((alive) => {
     if (alive) {
       console.error(
@@ -298,7 +366,7 @@ function setupPrimaryServer() {
       startSecondaryMode();
       return;
     }
-    httpServer.listen(WS_PORT, "127.0.0.1", () => {
+    httpServer.listen(WS_PORT, () => {
     wss = new WebSocket.WebSocketServer({
       server: httpServer,
       verifyClient: allowOrigin,
@@ -409,35 +477,13 @@ function setupPrimaryServer() {
 
     setupPrimaryWss(wss);
 
-    // Also listen on ::1 (IPv6 loopback) so Node 18 clients work: Node 18
-    // resolves 'localhost' to ::1 first with no happy-eyeballs fallback.
-    // Skip cleanly when the host has no IPv6 stack (EADDRNOTAVAIL/EAFNOSUPPORT).
-    // On macOS, SO_REUSEADDR lets a specific-address ::1 bind succeed silently
-    // over a live :: wildcard listener — but we only set up httpServer6 AFTER
-    // probing 127.0.0.1, so a false-primary that owns :: would be caught by that
-    // probe (it also owns 127.0.0.1) and we would have gone Secondary already.
-    //
-    // The "listening" log is delayed until ::1 is ready (or skipped) so that
-    // any client connecting on the log signal can reach both addresses.
-    const SKIP_IPV6 = new Set(["EADDRNOTAVAIL", "EAFNOSUPPORT", "EPROTONOSUPPORT"]);
-    const logListening = () =>
-      console.error(
-        `[PolterTab MCP] Primary WebSocket server listening on ws://localhost:${WS_PORT}`,
-      );
-    httpServer6 = http.createServer(handleRequest);
-    httpServer6.on("error", (e) => {
-      if (SKIP_IPV6.has(e.code)) {
-        httpServer6 = null;
-      } else {
-        console.error(`[PolterTab MCP] IPv6 loopback error: ${e.message}`);
-      }
-      logListening();
-    });
-    httpServer6.once("listening", logListening);
-    httpServer6.on("upgrade", (req, socket, head) => {
-      wss.handleUpgrade(req, socket, head, (client) => wss.emit("connection", client, req));
-    });
-    httpServer6.listen(WS_PORT, "::1");
+    // Wildcard bind (:: dual-stack) covers both 127.0.0.1 and ::1, so Node 18
+    // clients that resolve localhost → ::1 reach the primary without a separate
+    // httpServer6.  A legacy server attempting listen(port) with no host gets
+    // EADDRINUSE because two wildcard binds on the same port always collide.
+    console.error(
+      `[PolterTab MCP] Primary WebSocket server listening on ws://localhost:${WS_PORT}`,
+    );
     });
   });
 }
@@ -543,6 +589,7 @@ async function promoteOrRejoin() {
     return;
   }
   isSecondary = false;
+  if (everAccepted && extensionLostAt === null) extensionLostAt = Date.now();
   setupPrimaryServer();
 }
 
@@ -582,6 +629,7 @@ function connectToPrimary() {
       // are handled before the id branch so none can settle a pending command.
       if (msg.type === "secondary_accepted") {
         accepted = true;
+        everAccepted = true;
         backoffAttempt = 0;
         refusal = null;
         unreachable = false;
@@ -636,12 +684,21 @@ function connectToPrimary() {
     // A lazy reconnect whose dial ended before the ACK fails now, with the
     // reason when the Primary gave one. The branches below still run, so the
     // node retries or promotes exactly as it would have without the caller.
+    if (code === 4002) {
+      incompatible = { required: info.required, got: info.got };
+      console.error(
+        `[PolterTab MCP] Primary refused this node: version ${incompatible.got || OWN_VERSION} is incompatible (requires ${incompatible.required || "unknown"}). Not retrying.`,
+      );
+    }
+
     if (!accepted) {
       finishReconnect(
         new Error(
           info.reason === "capacity_rejected"
             ? `[capacity_rejected limit=${info.limit}] Primary (pid ${info.pid}) has ${info.limit} secondaries. Retry later.`
-            : reconnectFailed(),
+            : incompatible
+              ? incompatibleError()
+              : reconnectFailed(),
         ),
       );
     }
@@ -667,13 +724,18 @@ function connectToPrimary() {
     const aborted =
       info.reason === "capacity_rejected"
         ? `[capacity_rejected limit=${info.limit}] Primary (pid ${info.pid}) refused this node. Command aborted.`
-        : "Primary node disconnected. Command aborted.";
+        : incompatible
+          ? incompatibleError()
+          : "Primary node disconnected. Command aborted.";
     for (const [id, { reject, timer }] of pendingCommands) {
       clearTimeout(timer);
       reject(new Error(aborted));
       pendingCommands.delete(id);
     }
 
+    // Stop: neither a retry nor a promotion can fix a version mismatch.
+    if (incompatible) return;
+
     // Refused by a live Primary: it is not dying, so promoting can only fail.
     if (refused) {
       const delay = _backoffDelay(backoffAttempt++);
@@ -772,7 +834,7 @@ function _dispatchProxyNow(callerWs, id, action, params) {
     _tryDequeue();
     if (callerWs.readyState === WebSocket.OPEN) {
       callerWs.send(
-        JSON.stringify({ id, success: false, error: "Browser extension not connected to Primary." }),
+        JSON.stringify({ id, success: false, error: extensionMissing() }),
       );
     }
   }
@@ -796,6 +858,18 @@ function setupPrimaryWss(wss) {
           // limit used to trigger — so it is never refused and never counted.
           ws.supportsNewCloseCodes =
             typeof msg.version === "string" && msg.version !== "";
+          // A different major speaks a different protocol; a v2 node is told
+          // so with 4002 and stops. Only a node that sent a version gets this,
+          // like every other 4xxx (§3.2).
+          const theirs = ws.supportsNewCloseCodes ? majorOf(msg.version) : null;
+          const ours = majorOf(OWN_VERSION);
+          if (theirs !== null && ours !== null && theirs !== ours) {
+            console.error(
+              `[PolterTab MCP] Rejecting secondary node ${msg.nodeId} - version ${msg.version} is incompatible with ${OWN_VERSION}.`,
+            );
+            ws.close(4002, versionReason(ours, msg.version));
+            return;
+          }
           if (ws.supportsNewCloseCodes) {
             let v2 = 0;
             for (const [id, c] of secondaryClients) {
@@ -907,7 +981,7 @@ function setupPrimaryWss(wss) {
                 JSON.stringify({
                   id,
                   success: false,
-                  error: "Browser extension not connected to Primary.",
+                  error: extensionMissing(),
                 }),
               );
             }
@@ -1112,6 +1186,7 @@ function setupPrimaryWss(wss) {
       } else if (extensionSocket === ws) {
         console.error("[PolterTab MCP] Chrome extension disconnected.");
         extensionSocket = null;
+        extensionLostAt = Date.now();
       }
     });
 
@@ -1125,7 +1200,6 @@ function shutdown() {
   console.error("[PolterTab MCP] Shutting down...");
   if (wss) wss.close();
   if (httpServer) httpServer.close();
-  if (httpServer6) httpServer6.close();
   process.exit(0);
 }
 // Helper to wait for WebSocket connection
@@ -1196,6 +1270,7 @@ function _buildEnvelope(action, params, activeNodeId) {
 
 // Helper to send command to the extension
 async function sendCommand(action, params) {
+  if (incompatible) throw new Error(incompatibleError());
   // Evicted, or a caller ahead of this one is already reconnecting: wait for
   // that one dial rather than racing it.
   if (isEvicted || reconnect) await lazyReconnect();
@@ -1242,9 +1317,7 @@ async function sendCommand(action, params) {
   }
 
   if (!isConnected) {
-    throw new Error(
-      `Browser extension not connected. Please ensure the extension is installed, enabled, and pointing to the correct port (default: ${DEFAULT_WS_PORT}).`,
-    );
+    throw new Error(extensionMissing());
   }
 
   const envelope = _buildEnvelope(action, params, nodeId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.8.0-beta.2",
+  "version": "1.8.0",
   "description": "Let any AI assistant drive and scrape your existing Chrome profile — no headless browser, no complex setup.",
   "bin": {
     "poltertab": "./bin/poltertab.js"

package/skills/browser-navigation-strategy/SKILL.md

@@ -195,6 +195,21 @@ lookups do not miss.
 A note saying "this page is tricky" helps nobody. Save what you would need to
 skip the discovery entirely next time.
 
+## Extension reconnection
+
+The Chrome extension reconnects automatically when the bridge server restarts.
+While it is reconnecting, commands return one of two error strings:
+
+- `[extension_reconnecting port=7822 elapsed=Xs]` — the extension disconnected
+  and is on its way back. **Retry the command after a short pause** (1–5 s).
+  The elapsed time tells you how long it has been gone; if it keeps climbing
+  past 30 s, check that the extension is loaded and the port matches.
+- `[extension_never_connected port=7822]` — the extension has never connected to
+  this server instance at all. Check that the extension is installed, enabled,
+  and pointed at the correct port.
+
+Never treat these as final failures without retrying at least once.
+
 ## Multiple tabs
 
 You have a **current tab**; every page-facing tool without `tabId`/`session`