poltertab 1.10.0-beta.1 → 1.10.0

package/bin/pair-flow.js

@@ -0,0 +1,320 @@
+"use strict";
+
+// Shared pairing-flow primitives used by both `poltertab setup` and
+// `poltertab uploads pair`. These handle the code-exchange protocol but
+// never print command-specific headers — callers print those.
+
+const { addTrustedExtensionId } = require("../mcp-server/uploads-config.js");
+
+// ── port resolution ────────────────────────────────────────────────────────
+
+function resolveWsPort() {
+  try {
+    return require("../mcp-server/config.js").resolvePort();
+  } catch (_) {
+    return 7822;
+  }
+}
+
+// ── server connection ──────────────────────────────────────────────────────
+
+// Resolves with the open socket; rejects with err.code === "ECONNREFUSED"
+// if nothing is listening, or err.code === "ETIMEDOUT" on timeout.
+function tryConnectToServer(port, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    let WebSocket;
+    try { WebSocket = require("ws"); } catch (_) {
+      reject(new Error("ws module not available")); return;
+    }
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(Object.assign(new Error("connection timed out"), { code: "ETIMEDOUT" }));
+    }, timeoutMs);
+    ws.on("open", () => { clearTimeout(timer); resolve(ws); });
+    ws.on("error", (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+// ── pair via running Primary server ────────────────────────────────────────
+
+// Uses the running server as the pair host. The server manages codes and
+// sends uploads_pair_result when the user submits a code.
+//
+// rl — an already-open readline.Interface (shared with the wizard).
+//
+// Returns:
+//   { ok: true, extensionId }              — success
+//   { ok: false, reason: 'skipped' }       — user pressed Enter with no code
+//   { ok: false, reason: 'locked' }        — 5-attempt lockout triggered
+//   { ok: false, reason: 'error'|... }     — connection or server error
+function pairViaRunningServer(serverWs, rl) {
+  return new Promise((resolve) => {
+    let done = false;
+
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      try { serverWs.close(); } catch (_) {}
+      resolve(result);
+    };
+
+    const sigintHandler = () => { finish({ ok: false, reason: "skipped" }); process.exit(0); };
+    process.once("SIGINT", sigintHandler);
+
+    serverWs.on("error", (err) => finish({ ok: false, reason: "error", error: err }));
+    serverWs.on("close", () => {
+      if (!done) finish({ ok: false, reason: "server_disconnected" });
+    });
+
+    serverWs.on("message", (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw); } catch (_) { return; }
+      if (msg.type !== "uploads_pair_result") return;
+
+      if (msg.ok) {
+        finish({ ok: true, extensionId: msg.extensionId });
+      } else if (msg.reason === "locked_out") {
+        const mins = msg.secsLeft ? Math.ceil(msg.secsLeft / 60) : 15;
+        process.stderr.write(
+          `\n  Too many wrong codes. Pairing is locked for ${mins} minutes.\n` +
+          "  (You can still pair during the lockout with: poltertab uploads pair --id <extension-id>)\n",
+        );
+        finish({ ok: false, reason: "locked" });
+      } else if (msg.reason === "expired") {
+        process.stderr.write(
+          "  That code expired — the popup is showing a fresh one. Try again.\n",
+        );
+        askCode();
+      } else if (msg.reason === "config_write_failed") {
+        process.stderr.write(
+          "  Pairing failed — could not save the extension ID to config.json.\n" +
+          "  Check that the file is writable, then try again.\n",
+        );
+        finish({ ok: false, reason: "config_write_failed" });
+      } else {
+        const triesLeft =
+          msg.triesLeft !== undefined ? ` ${msg.triesLeft} tries left.` : "";
+        process.stderr.write(`  That code didn’t match.${triesLeft}\n`);
+        askCode();
+      }
+    });
+
+    function askCode() {
+      rl.question("  Code (Enter to skip): ", (ans) => {
+        const code = (ans || "").trim().toUpperCase().replace(/\s+/g, "");
+        if (!code) { finish({ ok: false, reason: "skipped" }); return; }
+        serverWs.send(JSON.stringify({ type: "uploads_pair_submit", code }));
+      });
+    }
+
+    askCode();
+  });
+}
+
+// ── pair via temporary listener (no Primary running) ──────────────────────
+
+const TEMP_IDLE_MS = 5 * 60 * 1000; // 5-minute idle timeout
+
+// Binds a pairing-only WebSocket server on port. Waits for a
+// chrome-extension:// socket, generates a code for it, then prompts the
+// user to type the code.
+//
+// opts.onStatus(msg) — called when the extension connects; callers use it
+//   to print the "extension connected" status line.
+//
+// Returns { ok: true, extensionId } | { ok: false, reason }.
+async function pairViaTempListener(port, rl, { onStatus } = {}) {
+  const WebSocket = require("ws");
+  const { PairHost } = require("../mcp-server/pair-host.js");
+
+  const pairHost = new PairHost();
+  let idleTimer = null;
+  let server = null;
+  let resolved = false;
+
+  const cleanup = () => {
+    clearTimeout(idleTimer);
+    if (server) {
+      try { server.clients.forEach((c) => c.terminate()); } catch (_) {}
+      try { server.close(); } catch (_) {}
+    }
+  };
+
+  server = new WebSocket.WebSocketServer({ host: "127.0.0.1", port });
+
+  // Wait for the server to start listening before returning.
+  await new Promise((resolve, reject) => {
+    server.on("listening", resolve);
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        reject(Object.assign(new Error(`Port ${port} is in use`), { code: "EADDRINUSE" }));
+      } else {
+        reject(err);
+      }
+    });
+  });
+
+  return new Promise((outerResolve) => {
+    const finish = (result) => {
+      if (resolved) return;
+      resolved = true;
+      cleanup();
+      outerResolve(result);
+    };
+
+    const resetIdle = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => finish({ ok: false, reason: "skipped" }), TEMP_IDLE_MS);
+    };
+
+    const sigintHandler = () => { finish({ ok: false, reason: "skipped" }); process.exit(0); };
+    process.once("SIGINT", sigintHandler);
+
+    resetIdle();
+
+    server.on("connection", (ws, req) => {
+      const origin = (req.headers && req.headers.origin) || null;
+      resetIdle();
+
+      // Only accept chrome-extension:// sockets; silently close everything else.
+      if (!origin || !origin.startsWith("chrome-extension://")) {
+        ws.close(4000, "pairing-only listener");
+        return;
+      }
+
+      ws.on("message", (raw) => {
+        resetIdle();
+        let msg;
+        try { msg = JSON.parse(raw); } catch (_) { return; }
+
+        if (msg.type === "extension_ready") {
+          // Generate a code only on first contact; subsequent pings must not regenerate.
+          if (!pairHost._socketCodes.has(ws)) {
+            pairHost.generateForSocket(ws, origin);
+            if (onStatus) onStatus("extension connected — the code is in its popup");
+            askCode();
+          }
+          return;
+        }
+
+        if (msg.type === "ping") {
+          // Keep-alive — just reset the idle timer (already done above); do NOT regenerate.
+          return;
+        }
+
+        if (msg.type === "pair_code_request") {
+          pairHost.handleCodeRequest(ws, origin);
+          return;
+        }
+
+        // Popup/options asking whether this extension is paired yet.
+        // Reply with uploads_not_paired so the UI can show the pair code.
+        if (msg.type === "uploads_get_config") {
+          try {
+            if (ws.readyState === 1 /* OPEN */) {
+              const reply = { type: "uploads_not_paired", pairCode: pairHost._socketCodes.get(ws) || null };
+              if (msg._replyId !== undefined) reply._replyId = msg._replyId;
+              ws.send(JSON.stringify(reply));
+            }
+          } catch (_) {}
+          return;
+        }
+
+        // Non-pairing message from a Secondary or AI tool dialing in during setup.
+        try {
+          if (ws.readyState === 1 /* OPEN */) {
+            ws.send(JSON.stringify({
+              type: "error",
+              error: "pairing mode — restart your AI tool for browser control",
+            }));
+          }
+        } catch (_) {}
+      });
+
+      ws.on("close", () => pairHost.onSocketClose(ws));
+      ws.on("error", () => pairHost.onSocketClose(ws));
+
+      function askCode() {
+        rl.question("  Code (Enter to skip): ", (ans) => {
+          const code = (ans || "").trim().toUpperCase().replace(/\s+/g, "");
+          if (!code) { finish({ ok: false, reason: "skipped" }); return; }
+
+          const result = pairHost.submitCode(code);
+          if (result.ok) {
+            const bareId = result.extensionId
+              .replace(/^chrome-extension:\/\//, "")
+              .replace(/\/$/, "");
+            let writeErr = null;
+            try { addTrustedExtensionId(bareId); } catch (e) { writeErr = e; }
+            if (writeErr) {
+              // Re-push to the specific extension that matched, not the enclosing socket.
+              if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+                pairHost.generateForSocket(result.extWs, result.extensionId);
+              }
+              process.stderr.write(
+                "  Pairing failed — could not save the extension ID to config.json.\n" +
+                "  Check that the file is writable, then try again.\n",
+              );
+              finish({ ok: false, reason: "config_write_failed" });
+              return;
+            }
+            try {
+              if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+                result.extWs.send(JSON.stringify({ type: "uploads_paired" }));
+              }
+            } catch (_) {}
+            finish({ ok: true, extensionId: bareId });
+          } else if (result.reason === "locked_out") {
+            const mins = result.secsLeft ? Math.ceil(result.secsLeft / 60) : 15;
+            process.stderr.write(
+              `\n  Too many wrong codes. Pairing is locked for ${mins} minutes.\n` +
+              "  (You can still pair during the lockout with: poltertab uploads pair --id <extension-id>)\n",
+            );
+            finish({ ok: false, reason: "locked" });
+          } else if (result.reason === "expired") {
+            process.stderr.write(
+              "  That code expired — the popup is showing a fresh one. Try again.\n",
+            );
+            askCode();
+          } else {
+            const triesLeft =
+              result.triesLeft !== undefined ? ` ${result.triesLeft} tries left.` : "";
+            process.stderr.write(`  That code didn’t match.${triesLeft}\n`);
+            askCode();
+          }
+        });
+      }
+    });
+  });
+}
+
+// ── poltertab server probe ─────────────────────────────────────────────────
+
+// Returns true when the server at port is a poltertab Primary.
+// Prevents treating an unrelated WebSocket server as the pair host.
+async function probeIsPoltertab(port) {
+  const http = require("http");
+  return new Promise((resolve) => {
+    const req = http.get({ host: "127.0.0.1", port, path: "/status", timeout: 2000 }, (res) => {
+      let data = "";
+      res.on("data", (c) => { data += c; });
+      res.on("end", () => {
+        try {
+          const body = JSON.parse(data);
+          resolve(body.role === "primary");
+        } catch (_) { resolve(false); }
+      });
+    });
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+module.exports = {
+  resolveWsPort,
+  tryConnectToServer,
+  probeIsPoltertab,
+  pairViaRunningServer,
+  pairViaTempListener,
+};

package/bin/setup.js

@@ -30,6 +30,8 @@ const SNIPPET_SRC = path.join(PKG, "assets", "claude-md-snippet.md");
 // link would get the previous stable extension, because GitHub's
 // /releases/latest skips prereleases — a fresh, correctly-followed setup that
 // lands in version skew.
+const { addAllowlistEntry } = require("../mcp-server/uploads-config.js");
+const { validateAllowlistEntry } = require("../mcp-server/upload-paths.js");
 const updates = require("../mcp-server/update-check.js");
 const EXTENSION_URL = updates.extensionUrl(
   require("../package.json").version,
@@ -39,6 +41,10 @@ const EXTENSION_URL = updates.extensionUrl(
 // "already installed" — this is the whole idempotency check for step 2.
 const MARKER = "<!-- poltertab -->";
 
+// Default folder offered in the uploads prompt. Must never be inside
+// buildAlwaysBlocked — a unit test (H7) pins this.
+const DEFAULT_UPLOAD_FOLDER = "~/Downloads";
+
 const c = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
@@ -150,13 +156,163 @@ async function chooseScope(rl) {
   }
 }
 
-async function run(argv = []) {
+// --- Section 1: folder prompt -----------------------------------------------
+
+// Shows the uploads-folder prompt and updates the allowlist.
+// Uses the wizard's existing readline interface (rl); never opens a second one.
+// Caller guarantees stdin is a TTY before calling.
+//
+// Exported for direct unit testing.
+async function runFolderPrompt(rl, {
+  homeDir = os.homedir(),
+  addFn = addAllowlistEntry,
+  validateFn = validateAllowlistEntry,
+} = {}) {
+  console.log(`\n  Let agents upload files from a folder?  [${DEFAULT_UPLOAD_FOLDER}]`);
+  console.log("  Enter = allow ~/Downloads · type another folder · n = skip");
+
+  const MAX_RETRIES = 2;
+  let retries = 0;
+
+  for (;;) {
+    const raw = (await ask(rl, "  > ")).trim();
+
+    if (raw === "n" || raw === "N") {
+      console.log("  – uploads skipped      enable later: poltertab uploads allow <dir>");
+      return;
+    }
+
+    const folderPath = raw === "" ? DEFAULT_UPLOAD_FOLDER : raw;
+
+    const v = validateFn(folderPath, homeDir);
+    if (!v.ok) {
+      console.log(`  ${c.yellow("!")} ${v.errorText}`);
+      retries++;
+      if (retries >= MAX_RETRIES) {
+        console.log("  – uploads skipped (poltertab uploads allow <dir> any time)");
+        return;
+      }
+      // re-ask; the loop continues
+      continue;
+    }
+
+    const added = addFn(folderPath);
+    if (added) {
+      console.log(`  ${c.green("✓")} uploads folder       ${c.dim(folderPath)}`);
+    } else {
+      console.log(`  ${c.green("✓")} uploads folder       ${c.dim(folderPath)} (already set)`);
+    }
+    return;
+  }
+}
+
+// --- Section 3: setup pairing step ------------------------------------------
+
+// Shows the extension instructions and runs the pairing code loop.
+// Uses the wizard's existing readline interface (rl).
+// Caller guarantees stdin is a TTY before calling.
+//
+// opts.pairFlow — injectable pair function for unit tests. Signature:
+//   async (rl) => { ok, extensionId? } | { ok: false, reason }
+// When not injected, the real server/temp-listener flow is used.
+//
+// Exported for direct unit testing.
+async function runSetupPairingStep(rl, { pairFlow } = {}) {
+  const {
+    resolveWsPort,
+    tryConnectToServer,
+    probeIsPoltertab,
+    pairViaRunningServer,
+    pairViaTempListener,
+  } = require("./pair-flow.js");
+
+  console.log(`\n  ${c.bold("Last step — connect the extension:")}`);
+  console.log(`  1. Download and unzip:  ${c.cyan(EXTENSION_URL)}`);
+  console.log("  2. chrome://extensions → turn on Developer mode → Load unpacked → pick the folder");
+  console.log("  3. Click the PolterTab icon in Chrome and type the 4-letter code it shows.");
+  console.log("");
+
+  // Use the injected flow (tests) or the real connection flow.
+  if (!pairFlow) {
+    const port = resolveWsPort();
+    let serverWs = null;
+    try {
+      serverWs = await tryConnectToServer(port);
+      // Verify the server is actually poltertab before treating it as the pair host.
+      if (!(await probeIsPoltertab(port))) {
+        serverWs.terminate();
+        serverWs = null;
+        console.log(
+          `  Port ${port} is in use by something that isn’t poltertab.` +
+          " Close it or set a different port in ~/.poltertab/config.json, then retry.",
+        );
+        return;
+      }
+    } catch (err) {
+      if (err.code !== "ECONNREFUSED" && err.code !== "ENOENT" && err.code !== "ETIMEDOUT") {
+        console.log(`  Could not reach port ${port}: ${err.message}`);
+        return;
+      }
+      // Nothing listening — use temp listener below.
+    }
+
+    if (serverWs) {
+      process.stdout.write("  waiting for the extension to connect…\n");
+      pairFlow = (r) => pairViaRunningServer(serverWs, r);
+    } else {
+      process.stdout.write("  waiting for the extension to connect…\n");
+      pairFlow = async (r) => {
+        try {
+          return await pairViaTempListener(port, r, {
+            onStatus: (msg) => process.stdout.write(`  ${msg}\n`),
+          });
+        } catch (e) {
+          if (e.code === "EADDRINUSE") {
+            console.log(
+              `  Port ${port} is in use by something that isn’t poltertab.` +
+              " Close it or set a different port in ~/.poltertab/config.json, then retry.",
+            );
+            return { ok: false, reason: "skipped" };
+          }
+          throw e;
+        }
+      };
+    }
+  }
+
+  const result = await pairFlow(rl);
+
+  if (result.ok) {
+    const shortId = result.extensionId.slice(0, 8);
+    console.log(
+      `  ${c.green("✓")} paired               extension ${shortId}…` +
+      " · uploads panel is live in the extension",
+    );
+    console.log(c.dim(`      undo: poltertab uploads unpair ${result.extensionId}`));
+  } else if (result.reason === "skipped") {
+    console.log(
+      "  – pairing skipped      run poltertab uploads pair once the extension is loaded",
+    );
+  } else if (result.reason === "locked") {
+    console.log("  Too many wrong codes. Pairing is locked for 15 minutes.");
+  }
+  // Other reasons (error, server_disconnected): silent skip, don't abort setup.
+}
+
+// --- wizard ----------------------------------------------------------------
+
+async function run(argv = [], {
+  home = os.homedir(),
+  cwd = process.cwd(),
+  isTTY = process.stdin.isTTY,
+  rl: injectedRl = null,
+} = {}) {
   console.log(`\n  ${c.bold("PolterTab")} — browser control for AI agents\n`);
 
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  // Open one readline interface for all prompts. If tests inject one, use it.
+  const rl = injectedRl || (isTTY
+    ? readline.createInterface({ input: process.stdin, output: process.stdout })
+    : null);
 
   let scope;
   try {
@@ -164,12 +320,15 @@ async function run(argv = []) {
       ? "global"
       : argv.includes("--project")
         ? "project"
-        : await chooseScope(rl);
-  } finally {
-    rl.close();
+        : rl
+          ? await chooseScope(rl)
+          : (() => { throw new Error("Choose --global or --project when stdin is not a TTY"); })();
+  } catch (err) {
+    if (rl && !injectedRl) rl.close();
+    throw err;
   }
 
-  const paths = resolvePaths(scope);
+  const paths = resolvePaths(scope, { home, cwd });
   console.log("");
 
   // Each step reports what it actually did. A step that fails is reported with
@@ -199,10 +358,31 @@ async function run(argv = []) {
     console.log(c.dim(`      run: claude mcp add --scope ${paths.mcpScope} poltertab poltertab`));
   }
 
-  console.log(`\n  ${c.bold("One step left — install the Chrome extension:")}`);
-  console.log(`  ${c.cyan(EXTENSION_URL)}`);
-  console.log(c.dim("      unzip it, then chrome://extensions → Developer mode → Load unpacked\n"));
-  console.log(`  ${c.dim("Restart Claude Code to pick up the new tools.")}\n`);
+  // Section 1: optional uploads folder prompt (TTY only).
+  if (isTTY && rl) {
+    try {
+      await runFolderPrompt(rl, { homeDir: home });
+    } catch (err) {
+      console.log(`  ${c.yellow("!")} uploads folder skipped — ${err.message}`);
+    }
+  }
+
+  // Section 3: optional pairing step (TTY only).
+  if (isTTY && rl) {
+    try {
+      await runSetupPairingStep(rl);
+    } catch (err) {
+      console.log(`  ${c.yellow("!")} pairing step failed — ${err.message}`);
+    }
+  } else {
+    // Non-TTY: show extension instructions so the output is still useful.
+    console.log(`\n  ${c.bold("One step left — install the Chrome extension:")}`);
+    console.log(`  ${c.cyan(EXTENSION_URL)}`);
+    console.log(c.dim("      unzip it, then chrome://extensions → Developer mode → Load unpacked\n"));
+    console.log(`  ${c.dim("Restart Claude Code to pick up the new tools.")}\n`);
+  }
+
+  if (rl && !injectedRl) rl.close();
 }
 
 module.exports = {
@@ -211,8 +391,11 @@ module.exports = {
   installSkill,
   updateClaudeMd,
   registerServer,
+  runFolderPrompt,
+  runSetupPairingStep,
   MARKER,
   EXTENSION_URL,
+  DEFAULT_UPLOAD_FOLDER,
 };
 
 // Guard so the test suite can require this file without triggering a wizard

package/bin/uploads.js

@@ -9,9 +9,18 @@ const {
   addAllowlistEntry,
   removeAllowlistEntry,
   addTrustedExtensionId,
+  getTrustedExtensionIds,
+  removeTrustedExtensionId,
 } = require("../mcp-server/uploads-config.js");
 const { getRecentLog } = require("../mcp-server/uploads-log.js");
 const { validateAllowlistEntry, buildAlwaysBlocked } = require("../mcp-server/upload-paths.js");
+const {
+  resolveWsPort,
+  tryConnectToServer,
+  probeIsPoltertab,
+  pairViaRunningServer,
+  pairViaTempListener,
+} = require("./pair-flow.js");
 
 async function run(argv) {
   const sub = argv[0];
@@ -103,134 +112,181 @@ async function run(argv) {
     return;
   }
 
+  if (sub === "unpair") {
+    await runUnpair(argv.slice(1));
+    return;
+  }
+
   console.error(`\n  Unknown subcommand: ${sub}`);
-  console.error("  Usage: poltertab uploads list|allow <dir>|revoke <dir>|log [-n N]|pair [--id <id>]\n");
+  console.error("  Usage: poltertab uploads list|allow <dir>|revoke <dir>|log [-n N]|pair [--id <id>]|unpair [--id <id>]\n");
   process.exit(1);
 }
 
-// Reads the port poltertab is listening on from the default config or falls back.
-function resolveWsPort() {
-  try {
-    const { resolvePort } = require("../mcp-server/config.js");
-    return resolvePort();
-  } catch (_) {
-    return 7822;
-  }
-}
+// (pair primitives live in pair-flow.js and are imported above)
+
+// ── poltertab uploads pair ─────────────────────────────────────────────────
 
-// poltertab uploads pair — link a Chrome extension by its ID so it may send
-// upload config/log WS messages. Interactive by default (requires TTY);
-// --id <id> skips the prompt for scripted human use.
 async function runPair(argv) {
+  // --id is kept for backward compatibility: pair by bare extension ID directly.
   const idFlagIdx = argv.indexOf("--id");
   const flagId = idFlagIdx !== -1 ? argv[idFlagIdx + 1] : null;
 
-  if (!flagId && !process.stdin.isTTY) {
+  if (flagId) {
+    if (!/^[a-p]{32}$/.test(flagId)) {
+      console.error(`\nInvalid extension ID: ${flagId}`);
+      console.error("Chrome extension IDs are 32 lowercase letters (a-p).\n");
+      process.exit(1);
+    }
+    const added = addTrustedExtensionId(flagId);
+    if (added) {
+      console.log(`\n  Paired: ${flagId}`);
+      console.log("  Upload config access is now enabled for this extension.");
+      console.log(`  (undo: poltertab uploads unpair ${flagId})\n`);
+    } else {
+      console.log(`\n  Already paired: ${flagId}\n`);
+    }
+    return;
+  }
+
+  if (!process.stdin.isTTY) {
     console.error("\nError: poltertab uploads pair requires an interactive terminal.\n" +
       "Use --id <extension-id> to pair non-interactively.\n");
     process.exit(1);
   }
 
-  let extensionId = flagId;
+  const readline = require("readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
-  if (!extensionId) {
-    // Ask the running server which extension origins are connected.
-    const port = resolveWsPort();
-    let origins = [];
-    try {
-      origins = await fetchConnectedOrigins(port);
-    } catch (err) {
-      console.error(`\nCould not connect to poltertab server on port ${port}: ${err.message}`);
-      console.error("Make sure poltertab is running, then try again.\n");
+  const port = resolveWsPort();
+
+  let serverWs = null;
+  try {
+    serverWs = await tryConnectToServer(port);
+    // Verify the server is actually poltertab, not an unrelated WS server.
+    if (!(await probeIsPoltertab(port))) {
+      serverWs.terminate();
+      serverWs = null;
+      rl.close();
+      console.error(
+        `\n  Port ${port} is in use by something that isn't poltertab.` +
+        " Close it or set a different port in ~/.poltertab/config.json, then retry.\n",
+      );
+      process.exit(1);
+    }
+  } catch (err) {
+    if (err.code === "ETIMEDOUT") {
+      rl.close();
+      console.error(
+        `\n  Port ${port} is in use by something that isn't poltertab.` +
+        " Close it or set a different port in ~/.poltertab/config.json, then retry.\n",
+      );
+      process.exit(1);
+    }
+    if (err.code !== "ECONNREFUSED" && err.code !== "ENOENT") {
+      rl.close();
+      console.error(`\nCould not connect to port ${port}: ${err.message}\n`);
       process.exit(1);
     }
+    // Nothing listening — start temp listener.
+  }
 
-    const extIds = origins
-      .filter((o) => o.startsWith("chrome-extension://"))
-      .map((o) => o.slice("chrome-extension://".length).replace(/\/$/, ""));
+  let result;
+  if (serverWs) {
+    result = await pairViaRunningServer(serverWs, rl);
+  } else {
+    console.log(
+      `\n  No poltertab server found. Starting a temporary pairing listener on port ${port}.`,
+    );
+    console.log("  Open the extension popup — it will connect automatically and show a 4-letter code.\n");
+    process.stdout.write("  waiting for the extension to connect…\n");
 
-    if (extIds.length === 0) {
-      console.error("\nNo extensions are currently connected to poltertab.");
-      console.error("Make sure the poltertab Chrome extension is installed and active, then try again.\n");
+    try {
+      result = await pairViaTempListener(port, rl, {
+        onStatus: (msg) => process.stdout.write(`  ${msg}\n`),
+      });
+    } catch (err) {
+      rl.close();
+      if (err.code === "EADDRINUSE") {
+        console.error(
+          `\n  Port ${port} is in use by something that isn't poltertab.` +
+          " Close it or set a different port in ~/.poltertab/config.json, then retry.\n",
+        );
+      } else {
+        console.error(`\n  Failed to start pairing listener: ${err.message}\n`);
+      }
       process.exit(1);
     }
+  }
 
-    console.log("\nConnected extension IDs:");
-    extIds.forEach((id, i) => console.log(`  ${i + 1}. ${id}`));
-    console.log("\nOpen chrome://extensions to find which ID matches your poltertab extension.");
-
-    const readline = require("readline");
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const choice = await new Promise((resolve) => {
-      rl.question(
-        `\nCompare the ID(s) above with chrome://extensions to find your poltertab extension.\n` +
-        `Enter number (1-${extIds.length}) to pair, or paste the ID directly: `,
-        (ans) => {
-          rl.close();
-          resolve(ans.trim());
-        },
-      );
-    });
-    const num = parseInt(choice, 10);
-    if (!isNaN(num) && num >= 1 && num <= extIds.length) {
-      extensionId = extIds[num - 1];
-    } else if (/^[a-p]{32}$/.test(choice)) {
-      extensionId = choice;
+  rl.close();
+
+  if (result.ok) {
+    const shortId = result.extensionId.slice(0, 8);
+    console.log(
+      `\n  ✓ paired               extension ${shortId}… · uploads panel is live in the extension`,
+    );
+    console.log(`  (undo: poltertab uploads unpair ${result.extensionId})\n`);
+  } else if (result.reason === "skipped") {
+    console.log("\n  – pairing skipped      run poltertab uploads pair once the extension is loaded\n");
+  } else if (result.reason === "locked") {
+    console.error("\n  Too many wrong codes. Pairing is locked for 15 minutes.\n");
+    process.exit(1);
+  } else if (result.reason === "config_write_failed") {
+    process.exit(1);
+  }
+}
+
+// ── poltertab uploads unpair ───────────────────────────────────────────────
+
+async function runUnpair(argv) {
+  // Accept positional id: `poltertab uploads unpair <id>` (the form success hints print).
+  // Also accept --id <id> for backward compatibility.
+  const idFlagIdx = argv.indexOf("--id");
+  const flagId = idFlagIdx !== -1 ? argv[idFlagIdx + 1] : null;
+  const positionalId = !flagId && argv.length > 0 && !argv[0].startsWith("-") ? argv[0] : null;
+  const targetId = flagId || positionalId;
+
+  if (targetId) {
+    const removed = removeTrustedExtensionId(targetId);
+    if (removed) {
+      console.log(`\n  Unpaired: ${targetId}\n`);
     } else {
-      console.error("\nInvalid selection.\n");
-      process.exit(1);
+      console.log(`\n  Not found in paired extensions: ${targetId}\n`);
     }
+    return;
   }
 
-  if (!/^[a-p]{32}$/.test(extensionId)) {
-    console.error(`\nInvalid extension ID: ${extensionId}`);
-    console.error("Chrome extension IDs are 32 lowercase letters.\n");
-    process.exit(1);
+  // No-id form: list all paired ids, require TTY + y/n confirmation before removing.
+  const ids = getTrustedExtensionIds();
+  if (ids.length === 0) {
+    console.log("\n  No extensions are currently paired.\n");
+    return;
   }
 
-  const added = addTrustedExtensionId(extensionId);
-  if (added) {
-    console.log(`\n  Paired: ${extensionId}`);
-    console.log("  Upload config access is now enabled for this extension.\n");
-  } else {
-    console.log(`\n  Already paired: ${extensionId}\n`);
+  if (!process.stdin.isTTY) {
+    console.error(
+      "\n  'poltertab uploads unpair' with no id requires an interactive terminal.\n" +
+      "  Pass the extension id to remove a specific one: poltertab uploads unpair <id>\n",
+    );
+    process.exit(1);
   }
-}
 
-// Ask the WS server for connected extension origins via uploads_get_origins.
-function fetchConnectedOrigins(port) {
-  return new Promise((resolve, reject) => {
-    let WebSocket;
-    try {
-      WebSocket = require("ws");
-    } catch (_) {
-      reject(new Error("ws module not available"));
-      return;
-    }
-    const ws = new WebSocket(`ws://localhost:${port}`);
-    const timer = setTimeout(() => {
-      ws.terminate();
-      reject(new Error("timeout waiting for server response"));
-    }, 5000);
-    ws.on("open", () => {
-      ws.send(JSON.stringify({ type: "uploads_get_origins" }));
-    });
-    ws.on("message", (raw) => {
-      clearTimeout(timer);
-      try {
-        const msg = JSON.parse(raw);
-        if (msg.type === "uploads_origins") {
-          ws.close();
-          resolve(Array.isArray(msg.origins) ? msg.origins : []);
-        }
-      } catch (_) {
-        ws.close();
-        reject(new Error("Invalid response from server"));
+  console.log("\n  Currently paired extensions:");
+  for (const id of ids) console.log(`    ${id}`);
+  console.log();
+
+  const readline = require("readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  await new Promise((resolve) => {
+    rl.question("  Remove ALL paired extensions? [y/N] ", (ans) => {
+      rl.close();
+      if ((ans || "").trim().toLowerCase() === "y") {
+        for (const id of ids) removeTrustedExtensionId(id);
+        console.log(`\n  Unpaired ${ids.length} extension${ids.length === 1 ? "" : "s"}.\n`);
+      } else {
+        console.log("\n  Cancelled.\n");
       }
-    });
-    ws.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
+      resolve();
     });
   });
 }

package/mcp-server/bridge.js

@@ -35,7 +35,8 @@ const {
 } = require("./config.js");
 const updates = require("./update-check.js");
 const OWN_VERSION = require("./../package.json").version;
-const { getAllowlist, addAllowlistEntry, removeAllowlistEntry, getTrustedExtensionIds } = require("./uploads-config.js");
+const { getAllowlist, addAllowlistEntry, removeAllowlistEntry, getTrustedExtensionIds, addTrustedExtensionId } = require("./uploads-config.js");
+const { PairHost } = require("./pair-host.js");
 const { logUpload, getRecentLog } = require("./uploads-log.js");
 const { buildAlwaysBlocked, validateAllowlistEntry } = require("./upload-paths.js");
 const fs = require("fs");
@@ -69,6 +70,10 @@ function isPaired() {
 
 let WS_PORT = resolvePort();
 
+// Manages in-memory pair codes for the current Primary session. Null when this
+// node is a Secondary (Secondary never generates codes; the Primary does).
+let pairHost = null;
+
 // Populated when the extension connects; stays null until then, which is itself
 // worth reporting — a skew warning must not fire on "no extension yet".
 let extensionVersion = null;
@@ -301,6 +306,7 @@ function allowOrigin(info, cb) {
 }
 
 function setupPrimaryServer() {
+  pairHost = new PairHost();
   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
@@ -1151,12 +1157,67 @@ function setupPrimaryWss(wss) {
                 // A socket that died mid-handshake reconnects on its own.
               }
             }
+            // Push a pair code to unpaired extensions so the UI can display it
+            // without the user running any CLI command first.
+            // Per-origin check: an already-trusted extension must not receive a code.
+            if (pairHost && ws.handshakeOrigin && !pairHost._socketCodes.has(ws) && !isUploadsAuthorized(ws.handshakeOrigin)) {
+              pairHost.generateForSocket(ws, ws.handshakeOrigin);
+            }
+          }
+          return;
+        }
+
+        // pair_code_request — extension asks for a (re)fresh of its pair code.
+        // Only accepted from unpaired extension sockets; throttled per socket (30 s).
+        if (msg.type === "pair_code_request") {
+          if (!ws.handshakeOrigin || !ws.handshakeOrigin.startsWith("chrome-extension://")) return;
+          if (isUploadsAuthorized(ws.handshakeOrigin) || !pairHost) return;
+          pairHost.handleCodeRequest(ws, ws.handshakeOrigin);
+          return;
+        }
+
+        // uploads_pair_submit — CLI submits a 4-char code to pair an extension.
+        // Originless (CLI) callers only; extension sockets must not self-pair.
+        if (msg.type === "uploads_pair_submit") {
+          if (ws.handshakeOrigin) return; // extension socket — ignore
+          if (!pairHost) {
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({ type: "uploads_pair_result", ok: false, reason: "no_active_code" }));
+            }
+            return;
+          }
+          const result = pairHost.submitCode(msg.code);
+          if (result.ok) {
+            // Store the bare ID (without chrome-extension:// prefix).
+            const bareId = result.extensionId.slice("chrome-extension://".length).replace(/\/$/, "");
+            let trustErr = null;
+            try { addTrustedExtensionId(bareId); } catch (e) { trustErr = e; }
+            if (trustErr) {
+              // Config write failed — do NOT claim success to avoid a paired-but-not-stored split.
+              // Re-push a fresh code so the extension popup remains usable for a retry.
+              if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+                pairHost.generateForSocket(result.extWs, result.extensionId);
+              }
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: "uploads_pair_result", ok: false, reason: "config_write_failed" }));
+              }
+              return;
+            }
+            if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+              result.extWs.send(JSON.stringify({ type: "uploads_paired" }));
+            }
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({ type: "uploads_pair_result", ok: true, extensionId: bareId }));
+            }
+          } else {
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({ type: "uploads_pair_result", ...result }));
+            }
           }
           return;
         }
 
         // uploads_get_origins — return list of connected extension origins.
-        // Used by `poltertab uploads pair` to discover which extension to trust.
         // Only originless (CLI/local) sockets may request this; chrome-extension://
         // origins must not be able to enumerate other connected extensions.
         if (msg.type === "uploads_get_origins") {
@@ -1229,12 +1290,14 @@ function setupPrimaryWss(wss) {
           if (msg.type === "uploads_get_config") {
             const allowlist = getAllowlist();
             const alwaysBlocked = buildAlwaysBlocked(homeDir);
+            const trustedExtensionIds = getTrustedExtensionIds();
             if (ws.readyState === WebSocket.OPEN) {
               ws.send(JSON.stringify({
                 type: "uploads_config",
                 _replyId: msg._replyId || null,
                 allowlist,
                 alwaysBlocked,
+                trustedExtensionIds,
               }));
             }
             return;
@@ -1353,6 +1416,7 @@ function setupPrimaryWss(wss) {
     });
 
     ws.on("close", () => {
+      if (pairHost) pairHost.onSocketClose(ws);
       if (ws.nodeId) {
         console.error(
           `[PolterTab MCP] Secondary node disconnected: ${ws.nodeId}`,

package/mcp-server/config.js

@@ -22,6 +22,7 @@
 // mirrored at the top of background.js with a pointer back to this comment. If
 // you change one, change both.
 
+const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
@@ -37,12 +38,17 @@ const path = require("path");
 const POLTERTAB_HOME =
   process.env.POLTERTAB_HOME || path.join(os.homedir(), ".poltertab");
 
-// Port: MCP_BROWSER_WS_PORT env, then --port CLI arg, then the default.
+// Port: --port arg → MCP_BROWSER_WS_PORT env → ws_port in config.json → 7822.
 const DEFAULT_WS_PORT = 7822;
 function resolvePort(argv = process.argv, env = process.env) {
   const i = argv.indexOf("--port");
   if (i !== -1 && argv[i + 1]) return parseInt(argv[i + 1], 10);
   if (env.MCP_BROWSER_WS_PORT) return parseInt(env.MCP_BROWSER_WS_PORT, 10);
+  try {
+    const home = env.POLTERTAB_HOME || path.join(os.homedir(), ".poltertab");
+    const cfg = JSON.parse(fs.readFileSync(path.join(home, "config.json"), "utf8"));
+    if (Number.isInteger(cfg.ws_port) && cfg.ws_port > 0) return cfg.ws_port;
+  } catch (_) {}
   return DEFAULT_WS_PORT;
 }
 

package/mcp-server/pair-host.js

@@ -0,0 +1,184 @@
+"use strict";
+
+// In-memory pairing state. The pair code NEVER leaves this module except
+// via the pair_code push to one socket. It is never written to config.json,
+// to uploads.log.jsonl, to the console, or returned in get_status / state_update.
+//
+// generateForSocket  — push a fresh code to an extension socket.
+// handleCodeRequest  — throttled re-push (30 s / socket).
+// submitCode         — validate a code from the CLI; returns { ok, extensionId, extWs }
+//                       or { ok: false, reason, triesLeft? / secsLeft? }.
+// onSocketClose      — void the code for a socket when it disconnects.
+
+const crypto = require("crypto");
+
+const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // 31 chars; no I L O 0 1
+const CODE_LENGTH = 4;
+const CODE_TTL_MS = 5 * 60 * 1000;       // 5 minutes
+const REQUEST_THROTTLE_MS = 30 * 1000;   // 30 s per socket
+const LOCKOUT_MAX_WRONG = 5;
+const LOCKOUT_DURATION_MS = 15 * 60 * 1000; // 15 minutes
+
+function _randomCode() {
+  let s = "";
+  for (let i = 0; i < CODE_LENGTH; i++) {
+    s += ALPHABET[crypto.randomInt(ALPHABET.length)];
+  }
+  return s;
+}
+
+class PairHost {
+  // opts.codeTtlMs — injectable TTL for unit tests (defaults to 5 minutes).
+  constructor({ codeTtlMs = CODE_TTL_MS } = {}) {
+    this._codeTtlMs = codeTtlMs;
+    // code → { ws, extensionId, expiresAt, timer }
+    this._codes = new Map();
+    // ws → code
+    this._socketCodes = new Map();
+    // ws → timestamp of last pair_code_request
+    this._socketLastRequest = new Map();
+    // global wrong-guess counter
+    this._lockout = { wrongCount: 0, lockedUntil: 0 };
+    // codes that recently expired — kept for one TTL window so submitCode can
+    // tell the user "expired, try the new one" without counting it as wrong.
+    this._recentlyExpired = new Set();
+  }
+
+  _isLockedOut() {
+    return this._lockout.lockedUntil > Date.now();
+  }
+
+  _uniqueCode() {
+    let code;
+    let attempts = 0;
+    do {
+      code = _randomCode();
+    } while (this._codes.has(code) && ++attempts < 200);
+    return code;
+  }
+
+  // Push a pair_code to this extension socket.
+  // Voids any previous code for the same socket first.
+  generateForSocket(ws, extensionId) {
+    // Void old code for this socket without removing throttle tracking.
+    const old = this._socketCodes.get(ws);
+    if (old) {
+      const entry = this._codes.get(old);
+      if (entry) clearTimeout(entry.timer);
+      this._codes.delete(old);
+      this._socketCodes.delete(ws);
+      // Track as recently-expired so a late submitCode returns "expired" not "wrong".
+      this._recentlyExpired.add(old);
+      setTimeout(() => this._recentlyExpired.delete(old), this._codeTtlMs).unref();
+    }
+
+    const code = this._uniqueCode();
+    const expiresAt = Date.now() + this._codeTtlMs;
+    const timer = setTimeout(() => {
+      if (this._codes.get(code)) {
+        this._codes.delete(code);
+        this._socketCodes.delete(ws);
+        // Track as recently-expired so a late submitCode returns "expired" (not
+        // "wrong") and does not burn a lockout try.
+        this._recentlyExpired.add(code);
+        setTimeout(() => this._recentlyExpired.delete(code), this._codeTtlMs).unref();
+        // Spec: push a fresh code down the same socket so the popup never shows
+        // a dead code. If the socket is already closed, nothing to do.
+        if (ws.readyState === 1 /* OPEN */) {
+          this.generateForSocket(ws, extensionId);
+        }
+      }
+    }, this._codeTtlMs);
+
+    this._codes.set(code, { ws, extensionId, expiresAt, timer });
+    this._socketCodes.set(ws, code);
+
+    try {
+      if (ws.readyState === 1 /* OPEN */) {
+        ws.send(JSON.stringify({ type: "pair_code", code, expiresAt }));
+      }
+    } catch (_) {}
+  }
+
+  // Throttled re-request from an extension socket.
+  handleCodeRequest(ws, extensionId) {
+    const now = Date.now();
+    const last = this._socketLastRequest.get(ws) || 0;
+    if (now - last < REQUEST_THROTTLE_MS) {
+      // Re-send the existing code if one exists; otherwise ignore.
+      const existing = this._socketCodes.get(ws);
+      if (existing && this._codes.has(existing)) {
+        try {
+          if (ws.readyState === 1) {
+            ws.send(JSON.stringify({ type: "pair_code", code: existing }));
+          }
+        } catch (_) {}
+      }
+      return;
+    }
+    this._socketLastRequest.set(ws, now);
+    this.generateForSocket(ws, extensionId);
+  }
+
+  // Validate a submitted code. Called by bridge.js (from CLI) or by the temp
+  // listener (directly from the local readline prompt).
+  // Returns { ok: true, extensionId, extWs }
+  //      or { ok: false, reason: "locked_out"|"wrong"|"expired", secsLeft?, triesLeft? }
+  submitCode(rawCode) {
+    const now = Date.now();
+    if (this._isLockedOut()) {
+      const secsLeft = Math.ceil((this._lockout.lockedUntil - now) / 1000);
+      return { ok: false, reason: "locked_out", secsLeft };
+    }
+
+    const code = String(rawCode || "").toUpperCase().trim();
+    const entry = this._codes.get(code);
+
+    // Expired code: tell the user to wait for the new one; do NOT count as a
+    // wrong guess — the expiry timer already regenerated a fresh code.
+    // This handles both the sub-second race (entry still present but past
+    // expiresAt) and the post-timer case (entry deleted, code in _recentlyExpired).
+    if ((entry && entry.expiresAt < now) || this._recentlyExpired.has(code)) {
+      return { ok: false, reason: "expired" };
+    }
+
+    if (!entry) {
+      this._lockout.wrongCount += 1;
+      if (this._lockout.wrongCount >= LOCKOUT_MAX_WRONG) {
+        this._lockout = { wrongCount: 0, lockedUntil: now + LOCKOUT_DURATION_MS };
+        return {
+          ok: false,
+          reason: "locked_out",
+          secsLeft: Math.ceil(LOCKOUT_DURATION_MS / 1000),
+        };
+      }
+      return {
+        ok: false,
+        reason: "wrong",
+        triesLeft: LOCKOUT_MAX_WRONG - this._lockout.wrongCount,
+      };
+    }
+
+    // Consume — single-use.
+    clearTimeout(entry.timer);
+    this._codes.delete(code);
+    this._socketCodes.delete(entry.ws);
+    this._lockout.wrongCount = 0;
+
+    return { ok: true, extensionId: entry.extensionId, extWs: entry.ws };
+  }
+
+  // Called on every socket close in the Primary's connection handler.
+  onSocketClose(ws) {
+    const code = this._socketCodes.get(ws);
+    if (code) {
+      const entry = this._codes.get(code);
+      if (entry) clearTimeout(entry.timer);
+      this._codes.delete(code);
+      this._socketCodes.delete(ws);
+    }
+    this._socketLastRequest.delete(ws);
+  }
+}
+
+module.exports = { PairHost };

package/mcp-server/uploads-config.js

@@ -70,11 +70,22 @@ function getTrustedExtensionIds() {
   return Array.isArray(v) ? v : [];
 }
 
+// Removes id from trusted_extension_ids. Returns true if removed, false if absent.
+function removeTrustedExtensionId(id) {
+  const cfg = _readConfig();
+  const list = Array.isArray(cfg.trusted_extension_ids) ? cfg.trusted_extension_ids : [];
+  const next = list.filter((e) => e !== id);
+  if (next.length === list.length) return false;
+  _writeConfig({ ...cfg, trusted_extension_ids: next });
+  return true;
+}
+
 module.exports = {
   getAllowlist,
   addAllowlistEntry,
   removeAllowlistEntry,
   addTrustedExtensionId,
   getTrustedExtensionIds,
+  removeTrustedExtensionId,
   CONFIG_PATH,
 };

package/package.json

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