poltertab 1.8.0-beta.1 → 1.8.0-beta.2

package/README.md

@@ -250,6 +250,16 @@ limit). A secondary refused for capacity is told why and retries with backoff
 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.
+
 **Changing the WebSocket Port:**
 Only needed when something that *isn't* PolterTab already holds `7822` —
 PolterTab servers share that port by design (see above). Both sides must move:

package/mcp-server/bridge.js

@@ -28,6 +28,10 @@ const {
   PROMOTION_BACKOFF_MAX_MS,
   PROMOTION_BACKOFF_JITTER,
   MAX_SECONDARIES,
+  IDLE_EVICTION_MS,
+  MAX_EXTENSION_CONCURRENCY,
+  PER_SECONDARY_QUEUE_DEPTH,
+  QUEUE_TIMEOUT_MS,
   POLTERTAB_HOME,
 } = require("./config.js");
 const updates = require("./update-check.js");
@@ -50,6 +54,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
 
 // Secondary-side retry state. One counter for the whole reconnect/probe/promote
 // cycle, reset only by a Primary's secondary_accepted; `refusal` and
@@ -60,6 +65,104 @@ let retryTimer = null;
 let refusal = null;
 let unreachable = false;
 
+// Idle eviction, Secondary side. A 4001 from the Primary parks this node: no
+// reconnect, no probe, no promotion. The next sendCommand dials again, and
+// `reconnect` is that dial while it is in flight, shared by every caller that
+// arrives meanwhile so they cost one connection, not one each (R-S3).
+let isEvicted = false;
+let reconnect = null; // { promise, resolve, reject, timer }
+
+// 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
+// secondaries and the primary itself. Legacy commands bypass the queue.
+//
+// queuedBySource maps sourceId → [{id, action, ackSentAt, callerWs, onDispatch,
+// onTimeout}]. sourceId is the secondary ws for proxy commands, or the symbol
+// PRIMARY_SOURCE for the primary's own commands. roundRobinOrder is the list of
+// active sources in round-robin order; rrCursor is the next position to serve.
+// waitHistory holds completed wait-times (ms) for /status percentiles.
+let extensionInFlight = 0;
+const PRIMARY_SOURCE = Symbol("primary");
+const queuedBySource = new Map();
+const roundRobinOrder = [];
+let rrCursor = 0;
+const waitHistory = [];
+
+// Enqueue an item for a source. If the source has no queue yet, append it to
+// the round-robin order so it gets served on the next dequeue.
+function _rrEnqueue(sourceId, item) {
+  if (!queuedBySource.has(sourceId)) {
+    queuedBySource.set(sourceId, []);
+    roundRobinOrder.push(sourceId);
+  }
+  queuedBySource.get(sourceId).push(item);
+}
+
+// Pop the next item according to the round-robin order. After taking from a
+// source, advance the cursor: if the source is now empty, remove it and leave
+// the cursor where it is (the next source slid into that slot); otherwise move
+// the cursor to the next source.
+function _rrDequeue() {
+  if (roundRobinOrder.length === 0) return null;
+  if (rrCursor >= roundRobinOrder.length) rrCursor = 0;
+  const sourceId = roundRobinOrder[rrCursor];
+  const items = queuedBySource.get(sourceId);
+  const item = items.shift();
+  if (items.length === 0) {
+    queuedBySource.delete(sourceId);
+    roundRobinOrder.splice(rrCursor, 1);
+    if (rrCursor >= roundRobinOrder.length) rrCursor = 0;
+  } else {
+    rrCursor = (rrCursor + 1) % roundRobinOrder.length;
+  }
+  return item;
+}
+
+// Try to dispatch as many queued items as the in-flight cap allows. Skips items
+// whose caller disconnected or whose deadline has passed (both are dropped
+// without consuming a slot).
+function _tryDequeue() {
+  while (extensionInFlight < MAX_EXTENSION_CONCURRENCY) {
+    if (roundRobinOrder.length === 0) break;
+    const item = _rrDequeue();
+    if (!item) break;
+
+    // Deadline check: ackSentAt + budget − 2 s. The −2 s keeps the secondary's
+    // own timeout from firing *after* the drop (the secondary re-arms to budget
+    // on the queued frame, so the margin is budget − (budget − 2 s) = 2 s).
+    if (Date.now() > item.ackSentAt + COMMAND_TIMEOUT_MS - 2000) {
+      item.onTimeout();
+      continue;
+    }
+    // Caller gone: drop silently.
+    if (item.callerWs && item.callerWs.readyState !== WebSocket.OPEN) {
+      continue;
+    }
+    // Extension disconnected since the item was enqueued: reject to caller
+    // without consuming a slot. This is the guard against the MUST-1 crash:
+    // _dispatchProxyNow calls extensionSocket.send() synchronously, so a null
+    // socket inside a timer callback becomes an uncaughtException that kills
+    // the Primary and every Secondary with it.
+    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." }),
+        );
+      }
+      continue;
+    }
+
+    extensionInFlight++;
+    const waitMs = Date.now() - item.ackSentAt;
+    waitHistory.push(waitMs);
+    if (waitHistory.length > 1000) waitHistory.shift();
+    item.onDispatch();
+    // onDispatch may or may not keep extensionInFlight++ live (it fires the
+    // extension send); the loop re-checks the cap after each dispatch.
+  }
+}
+
 function broadcastSessionState() {
   if (extensionSocket && extensionSocket.readyState === WebSocket.OPEN) {
     const sessions = [];
@@ -113,7 +216,47 @@ function allowOrigin(info, cb) {
 
 function setupPrimaryServer() {
   const http = require("http");
-  httpServer = http.createServer();
+  const handleRequest = (req, res) => {
+    if (req.method === "GET" && req.url === "/status") {
+      const now = Date.now();
+      const secondaries = [];
+      for (const [nid, ws] of secondaryClients.entries()) {
+        const srcQueue = queuedBySource.get(ws);
+        secondaries.push({
+          nodeId: nid,
+          version: ws.version || null,
+          protocol: ws.supportsNewCloseCodes ? "v2" : "legacy",
+          pid: ws.pid || null,
+          idle_ms: Math.floor(now - ws.lastCommandAt),
+          queued_commands: srcQueue ? srcQueue.length : 0,
+        });
+      }
+      let totalQueued = 0;
+      for (const items of queuedBySource.values()) totalQueued += items.length;
+      const sorted = waitHistory.slice().sort((a, b) => a - b);
+      const pct = (p) => sorted.length ? sorted[Math.floor((sorted.length - 1) * p)] : 0;
+      const body = JSON.stringify({
+        role: "primary",
+        pid: process.pid,
+        port: WS_PORT,
+        version: OWN_VERSION,
+        secondaries,
+        queue: {
+          in_flight: extensionInFlight,
+          max_in_flight: MAX_EXTENSION_CONCURRENCY,
+          queued: totalQueued,
+          max_queued_per_secondary: PER_SECONDARY_QUEUE_DEPTH,
+          wait_percentiles_ms: { p50: pct(0.5), p95: pct(0.95), p99: pct(0.99) },
+        },
+      });
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(body);
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  };
+  httpServer = http.createServer(handleRequest);
 
   httpServer.on("error", (e) => {
     if (e.code === "EADDRINUSE") {
@@ -125,15 +268,37 @@ 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}`);
     }
   });
 
-  httpServer.listen(WS_PORT, () => {
-    console.error(
-      `[PolterTab MCP] Primary WebSocket server listening on ws://localhost:${WS_PORT}`,
-    );
+  // 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.
+  probePrimary().then((alive) => {
+    if (alive) {
+      console.error(
+        `[PolterTab MCP] Port ${WS_PORT} in use, switching to Secondary Mode...`,
+      );
+      httpServer.close();
+      httpServer = null;
+      startSecondaryMode();
+      return;
+    }
+    httpServer.listen(WS_PORT, "127.0.0.1", () => {
     wss = new WebSocket.WebSocketServer({
       server: httpServer,
       verifyClient: allowOrigin,
@@ -168,8 +333,65 @@ function setupPrimaryServer() {
       });
     }, HEARTBEAT_MS);
 
+    // Idle eviction (4001) for v2 Secondaries silent for IDLE_EVICTION_MS. An
+    // old Secondary is never evicted: it answers any close by trying to
+    // promote. One with a command in flight is skipped (R-S2) — its clock
+    // restarts when the reply goes back. The check runs at half the idle
+    // period, capped at the heartbeat, so an eviction lands at most that late.
+    const evictionInterval = setInterval(() => {
+      const now = Date.now();
+      for (const ws of secondaryClients.values()) {
+        if (!ws.supportsNewCloseCodes || ws.readyState !== WebSocket.OPEN) {
+          continue;
+        }
+        const idleMs = now - ws.lastCommandAt;
+        if (idleMs < IDLE_EVICTION_MS) continue;
+        // NICE-1: also skip eviction when commands are queued for this source
+        // (spec §3.3: "zero in-flight AND zero queued").
+        const busy =
+          [...pendingCommands.values()].some((c) => c.isProxy && c.sourceWs === ws) ||
+          queuedBySource.has(ws);
+        if (busy) continue;
+        console.error(
+          `[PolterTab MCP] Evicting idle secondary ${ws.nodeId} (idle ${idleMs} ms)`,
+        );
+        ws.close(
+          4001,
+          JSON.stringify({ reason: "idle_evicted", idle_ms: idleMs }),
+        );
+      }
+    }, Math.max(100, Math.min(HEARTBEAT_MS, Math.floor(IDLE_EVICTION_MS / 2))));
+
+    // GC: drop queued commands that have outlived QUEUE_TIMEOUT_MS. The
+    // deadline check at dequeue handles most cases; this is a safety net for
+    // commands in a source that never gets dequeued (e.g. its slot is always
+    // occupied by a slow extension command). It fires the same onTimeout
+    // handler, which sends [queue_timeout] to the caller and removes the item.
+    const queueGcInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [sourceId, items] of queuedBySource.entries()) {
+        for (let i = items.length - 1; i >= 0; i--) {
+          if (now - items[i].ackSentAt > QUEUE_TIMEOUT_MS) {
+            const [expired] = items.splice(i, 1);
+            expired.onTimeout();
+          }
+        }
+        if (items.length === 0) {
+          queuedBySource.delete(sourceId);
+          const idx = roundRobinOrder.indexOf(sourceId);
+          if (idx !== -1) {
+            roundRobinOrder.splice(idx, 1);
+            if (rrCursor > idx) rrCursor--;
+            if (rrCursor >= roundRobinOrder.length) rrCursor = 0;
+          }
+        }
+      }
+    }, Math.min(QUEUE_TIMEOUT_MS, 10000));
+
     wss.on("close", () => {
       clearInterval(interval);
+      clearInterval(evictionInterval);
+      clearInterval(queueGcInterval);
     });
 
     // Network State Garbage Collector (TTL: 5 minutes)
@@ -186,6 +408,37 @@ function setupPrimaryServer() {
     }, NETWORK_GC_INTERVAL_MS);
 
     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");
+    });
   });
 }
 
@@ -219,12 +472,55 @@ function scheduleRetry(fn, delay) {
   retryTimer = setTimeout(fn, delay);
 }
 
+// Dial the Primary again after an eviction. Settles on secondary_accepted, not
+// on the socket opening: a command sent before the ACK can land on a Primary
+// that is about to refuse this node. A failed dial rejects at once with the
+// cause (the close handler calls finishReconnect) and leaves the node on PR-1's
+// ordinary schedule — backoff, probe, promote — so the caller is not held for
+// the full command timeout and the port is still taken over if it is free.
+// isEvicted is cleared here rather than on the ACK: from now on the node is
+// reconnecting, and a node that promotes itself must not dial its own port.
+function lazyReconnect() {
+  if (reconnect) return reconnect.promise;
+  isEvicted = false;
+  let settle;
+  const promise = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  reconnect = {
+    promise,
+    ...settle,
+    timer: setTimeout(
+      () => finishReconnect(new Error(reconnectFailed())),
+      COMMAND_TIMEOUT_MS,
+    ),
+  };
+  connectToPrimary();
+  return promise;
+}
+
+function finishReconnect(err) {
+  if (!reconnect) return;
+  const r = reconnect;
+  reconnect = null;
+  clearTimeout(r.timer);
+  if (err) r.reject(err);
+  else r.resolve();
+}
+
+function reconnectFailed() {
+  return `[reconnect_failed port=${WS_PORT}] Could not reconnect to primary.`;
+}
+
 // Is anything listening on the port? Binding to find out is what leaked a
 // server per attempt; a refused TCP connect is the only answer that means the
 // Primary is gone.
 function probePrimary() {
   return new Promise((resolve) => {
-    const sock = net.connect(WS_PORT, "localhost");
+    // Dial 127.0.0.1 explicitly; 'localhost' resolves to ::1 first on Node 18
+    // (no happy-eyeballs), which would give a false ECONNREFUSED when our own
+    // Primary is listening on 127.0.0.1.
+    const sock = net.connect(WS_PORT, "127.0.0.1");
     // A listener with a full accept backlog answers with neither connect nor
     // error, which would park this node with no retry scheduled. Treat silence
     // as "something is there": connectToPrimary's handshake timeout then sorts
@@ -251,7 +547,9 @@ async function promoteOrRejoin() {
 }
 
 function connectToPrimary() {
-  const ws = new WebSocket(`ws://localhost:${WS_PORT}`, {
+  // Dial 127.0.0.1 explicitly so Node 18 (which resolves 'localhost' to ::1
+  // first with no fallback) does not get ECONNREFUSED against the IPv4 Primary.
+  const ws = new WebSocket(`ws://127.0.0.1:${WS_PORT}`, {
     perMessageDeflate: true,
     // A Primary that accepts TCP but never answers the upgrade (event loop
     // blocked, SIGSTOP) would otherwise hold this node forever.
@@ -287,6 +585,18 @@ function connectToPrimary() {
         backoffAttempt = 0;
         refusal = null;
         unreachable = false;
+        finishReconnect();
+        return;
+      }
+      // `queued` and `dispatched` frames re-arm the awaitReply timer (U11)
+      // but never settle the command — the reply does that.
+      if (
+        (msg.type === "queued" || msg.type === "dispatched") &&
+        msg.id &&
+        pendingCommands.has(msg.id)
+      ) {
+        const entry = pendingCommands.get(msg.id);
+        if (entry && entry.resetTimer) entry.resetTimer();
         return;
       }
       if (msg.id && pendingCommands.has(msg.id)) {
@@ -323,6 +633,36 @@ function connectToPrimary() {
       } catch (_) {}
     }
 
+    // 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 (!accepted) {
+      finishReconnect(
+        new Error(
+          info.reason === "capacity_rejected"
+            ? `[capacity_rejected limit=${info.limit}] Primary (pid ${info.pid}) has ${info.limit} secondaries. Retry later.`
+            : reconnectFailed(),
+        ),
+      );
+    }
+
+    // 4001 = idle_evicted. Park: no reconnect, no probe, no promotion — the
+    // next sendCommand dials. A command already on the wire when the Primary
+    // closed is lost, and retrying it could run it twice, so say so (R-S2).
+    if (code === 4001) {
+      isEvicted = true;
+      for (const [, { reject, timer, action }] of pendingCommands) {
+        clearTimeout(timer);
+        reject(
+          new Error(
+            `[evicted_mid_command action=${action || "unknown"}] Session evicted while command was in progress. Not auto-retried.`,
+          ),
+        );
+      }
+      pendingCommands.clear();
+      return;
+    }
+
     // Reject all pending commands
     const aborted =
       info.reason === "capacity_rejected"
@@ -401,6 +741,43 @@ async function readNetworkState(params = {}) {
   return { tabId, capturedRequests: data.length, data };
 }
 
+// Dispatch a proxy command to the extension. Must be called AFTER
+// extensionInFlight has already been incremented by the caller. Arms the
+// command timeout; on either a reply or a timeout, decrements extensionInFlight
+// and drains the queue so the next waiting command gets its turn.
+function _dispatchProxyNow(callerWs, id, action, params) {
+  const timer = setTimeout(() => {
+    pendingCommands.delete(id);
+    extensionInFlight--;
+    _tryDequeue();
+    if (callerWs.readyState === WebSocket.OPEN) {
+      callerWs.send(
+        JSON.stringify({ id, success: false, error: `Command '${action}' timed out.` }),
+      );
+    }
+  }, COMMAND_TIMEOUT_MS);
+  pendingCommands.set(id, { isProxy: true, sourceWs: callerWs, timer });
+  // Belt-and-braces: _tryDequeue's open-check guards the common case; this
+  // catches the narrow race where the extension socket closes between that
+  // check and the actual send (both are synchronous, but the close event is
+  // delivered between event-loop ticks, so the race is real on high-load paths).
+  try {
+    extensionSocket.send(
+      JSON.stringify({ ..._buildEnvelope(action, params, callerWs.nodeId), id }),
+    );
+  } catch (err) {
+    clearTimeout(timer);
+    pendingCommands.delete(id);
+    extensionInFlight--;
+    _tryDequeue();
+    if (callerWs.readyState === WebSocket.OPEN) {
+      callerWs.send(
+        JSON.stringify({ id, success: false, error: "Browser extension not connected to Primary." }),
+      );
+    }
+  }
+}
+
 function setupPrimaryWss(wss) {
   wss.on("connection", (ws) => {
     ws.isAlive = true;
@@ -451,6 +828,7 @@ function setupPrimaryWss(wss) {
           ws.version = msg.version || null;
           ws.pid = msg.pid || null;
           ws.parentPid = msg.parentPid || null;
+          ws.lastCommandAt = Date.now();
           console.error(
             `[PolterTab MCP] Secondary node connected: ${msg.nodeId}. Total secondaries: ${secondaryClients.size}`,
           );
@@ -491,6 +869,8 @@ function setupPrimaryWss(wss) {
             }
             return;
           }
+          // Each command restarts this Secondary's idle clock.
+          ws.lastCommandAt = Date.now();
           // Stamp which agent is asking, from the socket rather than the
           // message, so the extension keeps this Secondary's current tab apart
           // from the Primary's and every other Secondary's.
@@ -534,29 +914,73 @@ function setupPrimaryWss(wss) {
             return;
           }
 
-          const timer = setTimeout(() => {
-            pendingCommands.delete(id);
-            if (ws.readyState === WebSocket.OPEN) {
-              ws.send(
-                JSON.stringify({
+          // Legacy secondaries bypass the queue: they cannot receive `queued`
+          // or `dispatched` frames, so they go straight to the extension and
+          // keep today's timing contract. They still count toward extensionInFlight
+          // so v2 commands behind them wait their turn.
+          if (!ws.supportsNewCloseCodes) {
+            extensionInFlight++;
+            const timer = setTimeout(() => {
+              pendingCommands.delete(id);
+              extensionInFlight--;
+              _tryDequeue();
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({ id, success: false, error: `Command '${action}' timed out.` }));
+              }
+            }, COMMAND_TIMEOUT_MS);
+            pendingCommands.set(id, { isProxy: true, sourceWs: ws, timer });
+            extensionSocket.send(JSON.stringify({ ..._buildEnvelope(action, msg.params, ws.nodeId), id }));
+            return;
+          }
+
+          // v2 Secondary: use the concurrency cap and queue.
+          if (extensionInFlight < MAX_EXTENSION_CONCURRENCY) {
+            // Free slot: dispatch immediately. No queued frame.
+            extensionInFlight++;
+            _dispatchProxyNow(ws, id, action, msg.params);
+          } else {
+            // Slot full: enqueue if there is room in this secondary's queue.
+            const srcQueue = queuedBySource.get(ws);
+            const depth = srcQueue ? srcQueue.length : 0;
+            if (depth >= PER_SECONDARY_QUEUE_DEPTH) {
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({
                   id,
                   success: false,
-                  error: `Command '${action}' timed out.`,
-                }),
-              );
+                  error: `[queue_full action=${action}] Per-secondary queue depth (${PER_SECONDARY_QUEUE_DEPTH}) reached. Try again shortly.`,
+                }));
+              }
+              return;
+            }
+            const ackSentAt = Date.now();
+            const position = depth + 1;
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({ type: "queued", id, position }));
             }
-          }, COMMAND_TIMEOUT_MS);
-
-          pendingCommands.set(id, { isProxy: true, sourceWs: ws, timer });
-          // Same envelope construction as the direct path, so a tool argument
-          // named id or action cannot override the routing here either. The
-          // Primary's own id is kept last: pendingCommands is keyed on it.
-          extensionSocket.send(
-            JSON.stringify({
-              ..._buildEnvelope(action, msg.params, ws.nodeId),
+            _rrEnqueue(ws, {
               id,
-            }),
-          );
+              action,
+              params: msg.params,
+              nodeId: ws.nodeId,
+              ackSentAt,
+              callerWs: ws,
+              onDispatch() {
+                if (ws.readyState === WebSocket.OPEN) {
+                  ws.send(JSON.stringify({ type: "dispatched", id }));
+                }
+                _dispatchProxyNow(ws, id, action, msg.params);
+              },
+              onTimeout() {
+                if (ws.readyState === WebSocket.OPEN) {
+                  ws.send(JSON.stringify({
+                    id,
+                    success: false,
+                    error: `[queue_timeout action=${action}] Command queued too long; dropped to prevent ghost execution.`,
+                  }));
+                }
+              },
+            });
+          }
           return;
         }
 
@@ -650,7 +1074,16 @@ function setupPrimaryWss(wss) {
           clearTimeout(cmd.timer);
           pendingCommands.delete(msg.id);
 
+          // Every reply frees a slot; try to drain the queue before doing
+          // anything else so the next command lands on the extension with
+          // minimum latency.
+          extensionInFlight--;
+          _tryDequeue();
+
           if (cmd.isProxy) {
+            // Idle time counts from the reply, so a long command cannot leave
+            // its Secondary already due for eviction the moment it finishes.
+            cmd.sourceWs.lastCommandAt = Date.now();
             if (cmd.sourceWs.readyState === WebSocket.OPEN) {
               cmd.sourceWs.send(JSON.stringify(msg));
             }
@@ -692,6 +1125,7 @@ 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
@@ -714,14 +1148,27 @@ async function waitForConnection(timeoutMs = 5000) {
 // over a socket instead of settling a promise, so it stays where it is and
 // shares only the constant.
 function awaitReply(envelope, { timedOut, sendFailed }) {
-  const { id } = envelope;
+  const { id, action } = envelope;
   return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
+    let timer = setTimeout(() => {
       pendingCommands.delete(id);
       reject(new Error(timedOut));
     }, COMMAND_TIMEOUT_MS);
 
-    pendingCommands.set(id, { resolve, reject, timer });
+    // Re-arm the timer when the Primary sends a `queued` or `dispatched`
+    // frame (U11). The frame means the Primary is actively working on this
+    // command and extends the budget by a full COMMAND_TIMEOUT_MS from now.
+    const resetTimer = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        pendingCommands.delete(id);
+        reject(new Error(timedOut));
+      }, COMMAND_TIMEOUT_MS);
+      const entry = pendingCommands.get(id);
+      if (entry) entry.timer = timer;
+    };
+
+    pendingCommands.set(id, { resolve, reject, timer, action, resetTimer });
 
     try {
       extensionSocket.send(JSON.stringify(envelope));
@@ -749,7 +1196,18 @@ function _buildEnvelope(action, params, activeNodeId) {
 
 // Helper to send command to the extension
 async function sendCommand(action, params) {
-  const isConnected = await waitForConnection(5000);
+  // 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();
+
+  let isConnected = await waitForConnection(5000);
+
+  // During the wait the Primary may have evicted us (4001) or a concurrent
+  // dial may have started; take the lazy path rather than erroring immediately.
+  if (!isConnected && (isEvicted || reconnect)) {
+    await lazyReconnect();
+    isConnected = await waitForConnection(5000);
+  }
 
   if (isSecondary) {
     if (!isConnected) {
@@ -789,13 +1247,57 @@ async function sendCommand(action, params) {
     );
   }
 
-  return awaitReply(
-    _buildEnvelope(action, params, nodeId),
-    {
-      timedOut: `Command '${action}' timed out after ${COMMAND_TIMEOUT_MS / 1000} seconds.`,
-      sendFailed: (e) => `Failed to send command over WebSocket: ${e.message}`,
-    },
-  );
+  const envelope = _buildEnvelope(action, params, nodeId);
+  const timedOut = `Command '${action}' timed out after ${COMMAND_TIMEOUT_MS / 1000} seconds.`;
+  const sendFailed = (e) => `Failed to send command over WebSocket: ${e.message}`;
+
+  // Primary's own commands share the concurrency cap and the round-robin
+  // queue with proxy commands. The timer is armed at dispatch, not enqueue,
+  // so the budget does not shrink while the command waits for a free slot.
+  if (extensionInFlight < MAX_EXTENSION_CONCURRENCY) {
+    extensionInFlight++;
+    return _awaitPrimaryReply(envelope, { timedOut, sendFailed });
+  }
+  return new Promise((resolve, reject) => {
+    const ackSentAt = Date.now();
+    _rrEnqueue(PRIMARY_SOURCE, {
+      id: envelope.id,
+      action: envelope.action,
+      ackSentAt,
+      callerWs: null, // no secondary WS — primary commands have no caller socket
+      onDispatch() {
+        // extensionInFlight already incremented by _tryDequeue
+        _awaitPrimaryReply(envelope, { timedOut, sendFailed }).then(resolve, reject);
+      },
+      onTimeout() {
+        reject(new Error(timedOut));
+      },
+    });
+  });
+}
+
+// Register, arm, send, and settle one primary-mode command. Called after
+// extensionInFlight has already been incremented.
+function _awaitPrimaryReply(envelope, { timedOut, sendFailed }) {
+  const { id, action } = envelope;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(id);
+      extensionInFlight--;
+      _tryDequeue();
+      reject(new Error(timedOut));
+    }, COMMAND_TIMEOUT_MS);
+    pendingCommands.set(id, { resolve, reject, timer, action });
+    try {
+      extensionSocket.send(JSON.stringify(envelope));
+    } catch (err) {
+      clearTimeout(timer);
+      pendingCommands.delete(id);
+      extensionInFlight--;
+      _tryDequeue();
+      reject(new Error(sendFailed(err)));
+    }
+  });
 }
 
 // The Primary's view of which tab the agent is working in, shown in the
@@ -820,6 +1322,7 @@ module.exports = {
   readNetworkState,
   noteActiveTab,
   isSecondary: () => isSecondary,
+  isEvicted: () => isEvicted,
   extensionVersion: () => extensionVersion,
   _buildEnvelope,
   _backoffDelay,

package/mcp-server/config.js

@@ -58,6 +58,58 @@ function resolveMaxSecondaries(env = process.env) {
   return Number.isInteger(n) && n >= 0 ? n : DEFAULT_MAX_SECONDARIES;
 }
 
+// How long a v2 Secondary may sit idle (no commands) before the Primary sends
+// close code 4001. Only whole-number milliseconds > 0 are accepted; anything
+// else falls back to the default. 0 would mean "evict immediately", which is
+// not a meaningful setting, so it is treated as invalid.
+const DEFAULT_IDLE_EVICTION_MS = 5 * 60 * 1000; // 5 minutes
+function resolveIdleEvictionMs(env = process.env) {
+  const raw = env.POLTERTAB_IDLE_EVICTION_MS;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_IDLE_EVICTION_MS;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_IDLE_EVICTION_MS;
+}
+
+// The 35 s command budget. Exposed as an env override so tests can shrink it
+// without waiting for real timeouts. Junk or zero fall back to the default.
+const DEFAULT_COMMAND_TIMEOUT_MS = 35000;
+function resolveCommandTimeoutMs(env = process.env) {
+  const raw = env.POLTERTAB_COMMAND_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_COMMAND_TIMEOUT_MS;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_COMMAND_TIMEOUT_MS;
+}
+
+// How many commands the primary may have in flight to the extension at once.
+// 0 would refuse every command; junk falls back to the default.
+const DEFAULT_MAX_EXTENSION_CONCURRENCY = 6;
+function resolveMaxConcurrency(env = process.env) {
+  const raw = env.POLTERTAB_MAX_CONCURRENCY;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_MAX_EXTENSION_CONCURRENCY;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 ? n : DEFAULT_MAX_EXTENSION_CONCURRENCY;
+}
+
+// Per-secondary command queue depth. A command beyond this is refused at once.
+// 0 would refuse every queue attempt; junk falls back.
+const DEFAULT_PER_SECONDARY_QUEUE_DEPTH = 3;
+function resolveQueueDepth(env = process.env) {
+  const raw = env.POLTERTAB_QUEUE_DEPTH;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_PER_SECONDARY_QUEUE_DEPTH;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 ? n : DEFAULT_PER_SECONDARY_QUEUE_DEPTH;
+}
+
+// How long a command may sit in the server-side queue before being GC'd.
+// 0 / negative / junk fall back to the default.
+const DEFAULT_QUEUE_TIMEOUT_MS = 60000;
+function resolveQueueTimeoutMs(env = process.env) {
+  const raw = env.POLTERTAB_QUEUE_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") return DEFAULT_QUEUE_TIMEOUT_MS;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_QUEUE_TIMEOUT_MS;
+}
+
 module.exports = {
   POLTERTAB_HOME,
   MEMORY_DIR: path.join(POLTERTAB_HOME, "navigation_memory"),
@@ -66,9 +118,14 @@ module.exports = {
   DEFAULT_WS_PORT,
   resolvePort,
   resolveMaxSecondaries,
+  resolveIdleEvictionMs,
+  resolveCommandTimeoutMs,
+  resolveMaxConcurrency,
+  resolveQueueDepth,
+  resolveQueueTimeoutMs,
 
   // See the budget above before changing this.
-  COMMAND_TIMEOUT_MS: 35000,
+  COMMAND_TIMEOUT_MS: resolveCommandTimeoutMs(),
 
   // Dead-connection detection. A socket that misses a ping/pong round is
   // terminated so the extension's own reconnect can take over.
@@ -102,6 +159,16 @@ module.exports = {
   // promote.
   MAX_SECONDARIES: resolveMaxSecondaries(),
 
+  // How long a v2 Secondary may sit idle before the Primary evicts it with
+  // close code 4001. Configurable so tests can use a short value (e.g. 300 ms)
+  // without slowing the suite.
+  IDLE_EVICTION_MS: resolveIdleEvictionMs(),
+
+  // Command queue (PR-3).
+  MAX_EXTENSION_CONCURRENCY: resolveMaxConcurrency(),
+  PER_SECONDARY_QUEUE_DEPTH: resolveQueueDepth(),
+  QUEUE_TIMEOUT_MS: resolveQueueTimeoutMs(),
+
   // Lazy-loaded content arrives after the scroll returns. Long enough for the
   // XHR it triggered to land in the capture buffer, short enough that a
   // scroll-and-read loop is not dominated by waiting.

package/package.json

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