qiksy-mcp 1.46.0 → 1.48.0

package/AGENT-GUIDE.md

@@ -92,7 +92,7 @@ ladder.
    ```json
    { "mcpServers": { "qiksy": {
      "command": "npx",
-     "args": ["qiksy-mcp", "--port", "7333"],
+     "args": ["-y", "qiksy-mcp", "--port", "7333"],
      "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
    } } }
    ```

package/README.md

@@ -223,7 +223,7 @@ Only worth doing for the two gaps above — screenshots and `evaluate`. Playwrig
        },
        "qiksy": {
          "command": "npx",
-         "args": ["qiksy-mcp", "--port", "7333"],
+         "args": ["-y", "qiksy-mcp", "--port", "7333"],
          "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
        }
      }
@@ -294,8 +294,8 @@ One bridge is **one port + one token = one browser**. Pointing a second browser
 
 ```json
 { "mcpServers": {
-  "qiksy":   { "command": "npx", "args": ["qiksy-mcp", "--port", "7333"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_A" } },
-  "qiksy-2": { "command": "npx", "args": ["qiksy-mcp", "--port", "7334"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_B" } }
+  "qiksy":   { "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7333"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_A" } },
+  "qiksy-2": { "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7334"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_B" } }
 } }
 ```
 
@@ -323,7 +323,7 @@ or `.mcp.json` at the project root:
 ```json
 { "mcpServers": { "qiksy": {
   "type": "stdio",
-  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7333"],
   "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
 } } }
 ```
@@ -334,7 +334,7 @@ Same canonical shape:
 
 ```json
 { "mcpServers": { "qiksy": {
-  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7333"],
   "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
 } } }
 ```
@@ -344,7 +344,7 @@ Same canonical shape:
 ```json
 { "context_servers": { "qiksy": {
   "source": "custom",
-  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7333"],
   "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
 } } }
 ```
@@ -356,7 +356,7 @@ Same canonical shape:
   "inputs": [{ "type": "promptString", "id": "qac-token", "description": "Qiksy MCP token", "password": true }],
   "servers": { "qiksy": {
     "type": "stdio",
-    "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+    "command": "npx", "args": ["-y", "qiksy-mcp", "--port", "7333"],
     "env": { "QIKSY_MCP_TOKEN": "${input:qac-token}" }
   } }
 }

package/connect.mjs

@@ -72,9 +72,17 @@ export function agentTargets({ home = homedir(), platform = osPlatform(), dir =
  * would have coped anyway.
  */
 export function serverEntry({ port, token, platform = osPlatform() }) {
+  /* `-y` IS NOT A CONVENIENCE — IT IS WHAT STOPS THE START HANGING.
+   *
+   * Without it, an npx that does not already hold the package ASKS: «Need to install the following
+   * packages… Ok to proceed?» — and it asks on stdin, which in an MCP server IS the protocol. The
+   * client's `initialize` frame becomes the answer to a yes/no question, nothing replies, and the
+   * agent reports `MCP server qiksy connection timed out after 30000ms` with no server-side trace
+   * at all, because the server never ran. It bites hardest right after a release, when the cached
+   * version is no longer the latest one — which is exactly when it was reported (21.09.2026). */
   const base = platform === 'win32'
-    ? { command: 'cmd', args: ['/c', 'npx', 'qiksy-mcp', '--port', String(port)] }
-    : { command: 'npx', args: ['qiksy-mcp', '--port', String(port)] };
+    ? { command: 'cmd', args: ['/c', 'npx', '-y', 'qiksy-mcp', '--port', String(port)] }
+    : { command: 'npx', args: ['-y', 'qiksy-mcp', '--port', String(port)] };
   return { ...base, env: { QIKSY_MCP_TOKEN: token } };
 }
 
@@ -122,6 +130,68 @@ export function portInPlace(targets) {
   return 0;
 }
 
+/**
+ * THE PAIRING, FOR A COMMAND THAT HAS NO ENVIRONMENT — i.e. the finish hook.
+ *
+ * The server proper is started BY the agent, which hands it the token in the entry's `env` block.
+ * A Stop hook is not started that way: it is a bare command in a bare shell, so QIKSY_MCP_TOKEN is
+ * empty, the hub closes the unauthenticated join — correctly — and the hook then fails in the one
+ * way nobody notices: silently, once per run, into a log no one reads. Measured on a real setup
+ * (21.09.2026): `npx qiksy-mcp done` answered «the bridge closed the connection» and the browser
+ * never heard a thing, while the same command with the token in front of it rang through.
+ *
+ * So the hook reads the same pairing the agent itself uses. `~/.claude.json` is in the search
+ * because that is where `claude mcp add` puts an entry — top level, or under projects/<cwd> — and
+ * it is READ ONLY here: connect writes `.mcp.json` instead, and a command that fires on every stop
+ * must never rewrite the file that holds every project's servers.
+ */
+export function pairingInPlace({ dir = process.cwd(), home = homedir(), platform = osPlatform() } = {}) {
+  const targets = agentTargets({ dir, home, platform });
+  const found = { token: tokenInPlace(targets), port: portInPlace(targets) };
+  if (found.token && found.port) return found;
+
+  for (const entry of claudeJsonEntries(join(home, '.claude.json'), dir)) {
+    const tok = entry?.env?.QIKSY_MCP_TOKEN;
+    if (!found.token && typeof tok === 'string' && tok.length >= 16) found.token = tok;
+    if (!found.port) {
+      const args = Array.isArray(entry?.args) ? entry.args : [];
+      const i = args.indexOf('--port');
+      const p = i !== -1 ? Number(args[i + 1]) : NaN;
+      if (Number.isInteger(p) && p > 0) found.port = p;
+    }
+    if (found.token && found.port) break;
+  }
+  return found;
+}
+
+/**
+ * Every qiksy entry in `~/.claude.json`, THE ONE FOR THIS FOLDER FIRST.
+ *
+ * Order is the whole point: the token is the same everywhere (the popup has one field), but the
+ * PORT is per project, and a hook that picks a neighbouring project's port rings a bridge that
+ * belongs to somebody else's run. Deepest matching project path wins, then the global entry, then
+ * whatever else is there — the last one so a folder that was never connected still finds the
+ * pairing instead of going silent.
+ */
+function claudeJsonEntries(file, dir) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return []; // missing or hand-broken: not our file to fix, and not a reason to fail
+  }
+  const projects = json?.projects && typeof json.projects === 'object' ? json.projects : {};
+  const mine = Object.keys(projects)
+    .filter((p) => dir === p || dir.startsWith(`${p}/`))
+    .sort((a, b) => b.length - a.length);
+  const rest = Object.keys(projects).filter((p) => !mine.includes(p));
+  const out = [];
+  for (const p of mine) if (projects[p]?.mcpServers?.qiksy) out.push(projects[p].mcpServers.qiksy);
+  if (json?.mcpServers?.qiksy) out.push(json.mcpServers.qiksy);
+  for (const p of rest) if (projects[p]?.mcpServers?.qiksy) out.push(projects[p].mcpServers.qiksy);
+  return out;
+}
+
 /** Write our one entry, keep everything else in the file exactly as it was. */
 export function writeEntry(target, entry) {
   const { json, existed } = readConfig(target.file);
@@ -213,8 +283,15 @@ export const mintToken = () => randomBytes(18).toString('base64url');
 export async function connectAgents({ dir = process.cwd(), home = homedir(), platform = osPlatform(), port, token, hook = true } = {}) {
   const targets = agentTargets({ home, platform, dir });
   const installed = targets.filter((t) => existsSync(t.needs));
-  const keptToken = token || tokenInPlace(targets);
-  const keptPort = port || portInPlace(targets);
+  /* THE SEARCH FOR AN EXISTING PAIRING IS WIDER THAN THE LIST WE WRITE INTO, and that is the whole
+     point of it. `claude mcp add` puts the entry in ~/.claude.json, which is not a file connect
+     writes; looking only at its own targets, a re-run found nothing, minted a FRESH token and wrote
+     it everywhere — leaving the browser paired with a secret nobody holds any more. It costs the
+     person a «Token rejected» on the next restart and a trip to the popup, for a command they ran
+     to fix something else. Seen live on the owner's own machine, 21.09.2026. */
+  const inPlace = pairingInPlace({ dir, home, platform });
+  const keptToken = token || inPlace.token;
+  const keptPort = port || inPlace.port;
   const usePort = keptPort || (await freePort());
   const useToken = keptToken || mintToken();
   const entry = serverEntry({ port: usePort, token: useToken, platform });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Browser MCP server for the Chrome tab you already have open — your session, your logins. Gives Claude Code, Cursor, Codex and VS Code the live page: findings, forms, failed requests with server bodies.",
   "keywords": [
     "mcp",

package/server.mjs

@@ -26,6 +26,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { WebSocketServer, WebSocket } from 'ws';
 import { z } from 'zod';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, rmSync } from 'node:fs';
 import { basename, extname, dirname, isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
@@ -35,7 +36,7 @@ import { project } from './project.mjs';
 import { recordGap, listGaps, gapInvite, GAPS_FILE } from './gaps.mjs';
 import { STATES, STATE_KEYS, renderGallery } from './gallery.mjs';
 import { renderSearchableSvg } from './svg-shot.mjs';
-import { connectAgents, toClipboard } from './connect.mjs';
+import { connectAgents, toClipboard, pairingInPlace } from './connect.mjs';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
@@ -855,17 +856,26 @@ if (process.argv[2] === 'done') {
    * loudly because the browser is closed would be a hook people remove.
    */
   const bad = process.argv.includes('--problem');
-  const said = await new Promise((res) => {
+
+  /* ONE ATTEMPT WITH ONE PAIRING. Resolves to the sentence to print, plus `refused` when the hub
+     shut the door on us — which is the only failure worth trying a second key on. */
+  const ring = (token, port) => new Promise((res) => {
     let ws;
-    const give = (msg) => { try { ws?.close(); } catch { /* already gone */ } res(msg); };
+    let answered = false;
+    const give = (said, refused = false) => {
+      if (answered) return;
+      answered = true;
+      try { ws?.close(); } catch { /* already gone */ }
+      res({ said, refused });
+    };
     const timer = setTimeout(() => give('no answer from the bridge'), 6000);
     try {
-      ws = new WebSocket(`ws://${HOST}:${PORT}`);
+      ws = new WebSocket(`ws://${HOST}:${port}`);
     } catch {
       clearTimeout(timer);
-      return res('could not reach the bridge');
+      return give('could not reach the bridge');
     }
-    ws.on('open', () => ws.send(JSON.stringify({ t: 'join', v: PROTOCOL_VERSION, token: TOKEN, pid: process.pid })));
+    ws.on('open', () => ws.send(JSON.stringify({ t: 'join', v: PROTOCOL_VERSION, token, pid: process.pid })));
     ws.on('message', (raw) => {
       let m;
       try { m = JSON.parse(raw.toString()); } catch { return; }
@@ -873,9 +883,45 @@ if (process.argv[2] === 'done') {
       if (m.t === 'res') { clearTimeout(timer); give(m.result?.soundNote || m.error || 'done'); }
     });
     ws.on('error', () => { clearTimeout(timer); give('no bridge on this port'); });
-    ws.on('close', () => { clearTimeout(timer); give('the bridge closed the connection'); });
+    /* Closed before an answer = the token was refused. The hub says nothing more, by design: it
+       is an authentication gate, and a gate that explains itself is a gate that helps a stranger. */
+    ws.on('close', () => { clearTimeout(timer); give('the bridge closed the connection — the token it holds is a different one', true); });
   });
-  log(said);
+
+  /* TWO PLACES A TOKEN CAN COME FROM, AND THE ENVIRONMENT IS NOT THE TRUSTWORTHY ONE.
+   *
+   * A hook runs in a bare shell: no `env` block from the agent, so usually nothing — and sometimes
+   * WORSE than nothing, because an old QIKSY_MCP_TOKEN left in a .zshenv from a previous setup is
+   * exported into every shell on the machine and looks exactly like configuration. Found on the
+   * owner's own machine 21.09.2026: the shell carried a token three generations old, the hub
+   * refused it, and the command reported «the bridge closed the connection» — which reads as a
+   * browser problem, so the search starts in the popup, which was never wrong.
+   *
+   * So the environment is tried FIRST (an explicit export must still win when it is right), and a
+   * refusal falls through to the pairing the agent itself is using. Two attempts, never more. */
+  const tries = [];
+  if (TOKEN) tries.push({ token: TOKEN, port: PORT, from: 'the environment' });
+  const p = pairingInPlace({ dir: process.cwd() });
+  if (p.token && p.token !== TOKEN) {
+    const own = portArg === -1 && !process.env.QIKSY_MCP_PORT && p.port ? p.port : PORT;
+    tries.push({ token: p.token, port: own, from: 'your agent config' });
+  }
+  if (!tries.length) {
+    /* Naming the missing half, because «the bridge closed the connection» sent the last person
+       looking at the browser — the one part that was working. */
+    log('no token: set QIKSY_MCP_TOKEN, or run `npx qiksy-mcp connect` in this project first');
+    process.exit(0);
+  }
+
+  let last = '';
+  for (const t of tries) {
+    const r = await ring(t.token, t.port);
+    last = r.said;
+    if (!r.refused) break;
+    /* Said out loud only when there IS a second key to try — otherwise it is noise on every stop. */
+    if (t !== tries[tries.length - 1]) log(`the token in ${t.from} was refused — trying the one in your agent config`);
+  }
+  log(last);
   process.exit(0);
 }
 
@@ -918,6 +964,48 @@ let role = 'starting'; // 'hub' | 'follower'
 let hubSocket = null; // follower → its socket to the hub
 const followers = new Set(); // hub → the sibling agent windows riding on it
 let foreignPort = false; // the port is held by something that is not a Qiksy hub
+/* Set when the process on the port answered like a Qiksy bridge and REFUSED us (close 4001).
+   «Refused» and «not ours at all» are different problems with different repairs, and printing
+   one list of three guesses for both is what cost a tester «very much time» (report, 21.09.2026). */
+let portRefusedUs = false;
+
+/**
+ * WHO IS ON THE PORT — asked of the operating system, not guessed.
+ *
+ * The old message named three suspects at once («another process, a bridge running a different
+ * token, or an OLDER qiksy-mcp») and left the reader to work out which. The holder's pid and
+ * command line are one cheap call away on every machine this runs on, and a name ends the search
+ * instead of starting it. Cached: this is a diagnostic, not a heartbeat.
+ */
+let holderCache = null;
+function portHolder(port) {
+  if (holderCache && Date.now() - holderCache.at < 5_000) return holderCache.text;
+  let text = '';
+  try {
+    if (process.platform === 'win32') {
+      const net = spawnSync('netstat', ['-ano'], { encoding: 'utf8', timeout: 2000 });
+      const line = (net.stdout || '').split('\n').find((l) => l.includes(`:${port}`) && /LISTENING/i.test(l));
+      const pid = line?.trim().split(/\s+/).pop();
+      if (pid) {
+        const task = spawnSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], { encoding: 'utf8', timeout: 2000 });
+        const name = (task.stdout || '').split(',')[0]?.replace(/"/g, '').trim();
+        text = name ? `pid ${pid} (${name})` : `pid ${pid}`;
+      }
+    } else {
+      const ls = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', timeout: 2000 });
+      const pid = (ls.stdout || '').trim().split('\n')[0];
+      if (pid) {
+        const ps = spawnSync('ps', ['-o', 'command=', '-p', pid], { encoding: 'utf8', timeout: 2000 });
+        const cmd = (ps.stdout || '').trim().slice(0, 120);
+        text = cmd ? `pid ${pid} — ${cmd}` : `pid ${pid}`;
+      }
+    }
+  } catch {
+    /* no lsof, no permission, a locked-down box: the message is still better without this line */
+  }
+  holderCache = { at: Date.now(), text };
+  return text;
+}
 let wss = null;
 let takeoverTimer = null;
 let takeoverDelay = 400;
@@ -993,12 +1081,16 @@ function becomeFollower() {
     }
     if (msg.t === 'res' && msg.id != null) settle(msg);
   });
-  ws.on('close', () => {
+  ws.on('close', (code) => {
     if (hubSocket === ws) hubSocket = null;
     // A "hub" that never welcomed us is not one: either a foreign process holds the
     // port or it runs a different token. Say THAT — blaming the extension for this
     // is the bug that started all of it.
     foreignPort = !welcomed;
+    /* 4001 is OUR OWN refusal code: whatever is there speaks this protocol and turned us away,
+       which can only be the token. Anything else — a silent close, a foreign server, a reset —
+       is a different problem and must not borrow that sentence. */
+    portRefusedUs = !welcomed && code === 4001;
     failPending(welcomed ? 'the agent window that owned the bridge closed mid-call' : bridgeUnavailableMessage());
     scheduleTakeover();
   });
@@ -1055,11 +1147,31 @@ function bridgeUnavailableMessage() {
     );
   }
   if (foreignPort) {
+    const who = portHolder(PORT);
+    const holder = who ? ` The process holding it: ${who}.` : '';
+    /* THE ONE FACT THIS PROCESS ALWAYS KNOWS ABOUT ITSELF comes first. A window started with no
+       token is refused by every bridge there is, and no amount of looking at the port explains
+       that — the answer is in this window's own environment (report, 21.09.2026: «as soon as the
+       token matched — connected instantly», after a long hunt through the port). */
+    if (!TOKEN) {
+      return (
+        `This window has no QIKSY_MCP_TOKEN, so the bridge already on port ${PORT} refuses it — the token is the reason, ` +
+        `not the port.${holder} Put the same token in this window's MCP config (env QIKSY_MCP_TOKEN) as the one in the ` +
+        'Qiksy popup — `npx qiksy-mcp connect` writes it for you and keeps the pairing you already have.'
+      );
+    }
+    if (portRefusedUs) {
+      return (
+        `Port ${PORT} is held by another Qiksy bridge, and it REFUSED this window's token — so the two are running ` +
+        `different tokens.${holder} Nothing here is fixed in the popup. Give both windows the same token (\`npx qiksy-mcp connect\` ` +
+        'in each project writes the pairing you already have), or give this window its own port (--port / QIKSY_MCP_PORT).'
+      );
+    }
     return (
-      `Port ${PORT} is held by something this bridge cannot share it with: another process, a bridge running a ` +
-      'different token, or an OLDER qiksy-mcp (pre-1.1) that does not know how to host sibling agent windows. The ' +
-      'extension itself is probably fine — this is NOT fixed in the popup. Restart or update whatever owns the port, ' +
-      'or give this window its own port (--port / QIKSY_MCP_PORT).'
+      `Port ${PORT} is held by a process that is not a Qiksy bridge this one can share with — either something else ` +
+      `entirely, or an OLDER qiksy-mcp (pre-1.1) that cannot host sibling agent windows.${holder} The extension itself is ` +
+      'probably fine — this is NOT fixed in the popup. Restart or update whatever owns the port, or give this window its ' +
+      'own port (--port / QIKSY_MCP_PORT).'
     );
   }
   if (role === 'follower') {
@@ -4533,15 +4645,22 @@ server.registerTool(
       take: z
         .array(z.string())
         .optional()
-        .describe('Which properties, e.g. ["name","value","state"] or ["text","attr:data-id","style:color"]. Default ["name","text"].'),
+        .describe('Which properties, e.g. ["name","value","state"] or ["text","attr:data-id","style:color"]. Default ["name","text"]. Alias: `properties`.'),
+      /* THE NAME THE DESCRIPTION INVITES. This tool's own sentence is «which of their PROPERTIES
+         to take», so an agent reasonably sends `properties` — and zod strips an unknown key
+         silently, leaving the default ["name","text"]. The columns then look unsupported: a
+         tester reported exactly that («properties were silently ignored», 21.09.2026) about a
+         feature that works. A synonym costs one line; a silent default costs a session. */
+      properties: z.array(z.string()).optional().describe('Same as `take`, for when that is the word that came to mind.'),
       limit: z.number().optional().describe('Cap the rows (max 300). A capped answer says so rather than looking complete.'),
       select: selectArg,
       omit: omitArg,
     },
   },
-  async ({ tabId, nodes, take, limit, select, omit }) => {
+  async ({ tabId, nodes, take, properties, limit, select, omit }) => {
     try {
-      return asText(project(await callExtension('qa_collect', { tabId, nodes, take, limit }, 25_000), { select, omit }));
+      const want = take?.length ? take : properties?.length ? properties : take;
+      return asText(project(await callExtension('qa_collect', { tabId, nodes, take: want, limit }, 25_000), { select, omit }));
     } catch (e) {
       return asError(e);
     }
@@ -7218,12 +7337,30 @@ const SETTLED_BY_SHAPE = new Set(['date-sections', 'popup-date-input', 'file', '
  *
  * Then Escape, so the probe leaves the form as it found it.
  */
-async function probeWidget(tabId, { name, selector, close = true }) {
+async function probeWidget(tabId, { name, selector, ref, close = true }) {
+  /* A REF IS RESOLVED BEFORE THE FRESH SNAPSHOT, NEVER AGAINST IT. `ref` is the identifier every
+     other verb takes, so refusing it here with «pass name or selector» reads as an inconsistency
+     (report, 21.09.2026) — but a ref belongs to ONE snapshot and the one taken below RENUMBERS
+     them, so the number is looked up in the snapshot it came from and the node is then re-found
+     by what it WAS: selector first, its name second. */
+  const was = ref != null ? recallNode(tabId, ref) : null;
+  if (ref != null && !was) {
+    return {
+      ok: false,
+      error: `ref ${ref} is not in the last snapshot of this tab — take a qa_snapshot first, or pass \`name\`/\`selector\``,
+    };
+  }
   const snap = await callExtension('qa_snapshot', { tabId }, 30_000);
   rememberSnapshot(tabId, snap);
   const nodes = Array.isArray(snap?.nodes) ? snap.nodes : [];
   let node = null;
-  if (name) {
+  if (was) {
+    node = (was.selector && nodes.find((n) => n.selector === was.selector)) || (was.name ? pickNode(nodes, { name: was.name }, new Set())?.node : null) || null;
+    if (!node) {
+      return { ok: false, error: `the control behind ref ${ref} ("${was.name || was.selector}") is no longer on the page` };
+    }
+    selector = selector || was.selector;
+  } else if (name) {
     node = pickNode(nodes, { name }, new Set())?.node || null;
     if (!node) {
       return {
@@ -7235,7 +7372,7 @@ async function probeWidget(tabId, { name, selector, close = true }) {
   } else if (selector) {
     node = nodes.find((n) => n.selector === selector) || null;
   } else {
-    return { ok: false, error: 'pass `name` or `selector` — there is nothing to probe otherwise' };
+    return { ok: false, error: 'pass `ref`, `name` or `selector` — there is nothing to probe otherwise' };
   }
 
   const structural = node ? classifyNode(node, nodes) : null;
@@ -7286,13 +7423,14 @@ server.registerTool(
       tabId: tabIdArg,
       name: z.string().optional().describe("The control's accessible name, as a human reads it on screen"),
       selector: z.string().optional().describe('CSS selector — for a control with no accessible name at all, which is the case this tool exists for'),
+      ref: z.number().optional().describe('A ref from the last qa_snapshot of this tab. Resolved against THAT snapshot and re-found on the fresh one, so it survives the renumbering.'),
       close: z.boolean().optional().describe('Press Escape afterwards to close whatever opened. Default true; pass false when you want to keep the popup open and read it'),
     },
   },
-  async ({ tabId, name, selector, close }, extra) => {
+  async ({ tabId, name, selector, ref, close }, extra) => {
     const bar = loader(extra, 'working out what that widget is');
     try {
-      return asText(await probeWidget(tabId, { name, selector, close: close !== false }));
+      return asText(await probeWidget(tabId, { name, selector, ref, close: close !== false }));
     } catch (e) {
       return asError(e);
     } finally {