gazesight 0.4.0 → 0.5.1

package/dist/cli/index.js

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 
 // apps/cli/src/index.ts
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
 import { createInterface as createInterface2 } from "node:readline/promises";
-import { resolve, dirname as dirname2, join as join2, delimiter } from "node:path";
+import { resolve as resolve2, dirname as dirname2, join as join2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // apps/cli/src/config.ts
 import { randomBytes } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, posix, win32 } from "node:path";
 import { homedir } from "node:os";
 
 // apps/cli/src/config-browser.ts
@@ -42,22 +41,23 @@ var localConfigSchema = z.strictObject({
 
 // apps/cli/src/config.ts
 function configPathFor(platform, home, env) {
+  const pathJoin = platform === "win32" ? win32.join : posix.join;
   if (platform === "win32")
-    return join(
-      env.APPDATA ?? join(home, "AppData", "Roaming"),
+    return pathJoin(
+      env.APPDATA ?? pathJoin(home, "AppData", "Roaming"),
       "GazeSight",
       "config.json"
     );
   if (platform === "darwin")
-    return join(
+    return pathJoin(
       home,
       "Library",
       "Application Support",
       "GazeSight",
       "config.json"
     );
-  return join(
-    env.XDG_CONFIG_HOME ?? join(home, ".config"),
+  return pathJoin(
+    env.XDG_CONFIG_HOME ?? pathJoin(home, ".config"),
     "gazesight",
     "config.json"
   );
@@ -102,7 +102,7 @@ function writeLocalConfig(path, value) {
 }
 
 // packages/protocol/src/release.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.1";
 
 // apps/cli/src/doctor.ts
 import { z as z2 } from "zod";
@@ -326,9 +326,20 @@ var fullPageCaptureSchema = captureSchema.extend({
 });
 var navigateSchema = targetSchema.extend({ url: z3.url() });
 var diffSchema = z3.strictObject({
-  baseline: z3.uuid(),
+  baseline: z3.uuid().optional().describe(
+    "A prior PNG imageReference from this session. Omit and use referenceImagePath instead to diff against an external design reference."
+  ),
+  referenceImagePath: z3.string().min(1).max(4096).optional().describe(
+    "Path (relative to the MCP server's working directory, or absolute) to a local PNG design reference to diff the live capture against. Exactly one of baseline/referenceImagePath is required."
+  ),
   current: z3.uuid().optional(),
-  threshold: z3.number().finite().min(0).max(1).default(0.1)
+  tabId: z3.number().int().nonnegative().optional().describe(
+    "Only used with referenceImagePath when current is omitted, to select which tab to capture. Ignored otherwise (baseline's own tab is used)."
+  ),
+  threshold: z3.number().finite().min(0).max(1).default(0.1),
+  checkpoint: z3.string().min(1).max(200).regex(/^[A-Za-z0-9_-]+$/).optional().describe(
+    "Visual Convergence best-so-far tracking id (e.g. 'hero-desktop'). Only meaningful together with referenceImagePath: persists the best-known result locally and objectively reports isBest/regressed on every call, independent of the agent's own assessment."
+  )
 });
 var viewportProfileSchema = z3.enum([
   "mobile-small",
@@ -341,7 +352,10 @@ var setViewportSchema = targetSchema.extend({
   profile: viewportProfileSchema.optional(),
   width: z3.number().int().min(200).max(8192).optional(),
   height: z3.number().int().min(200).max(8192).optional(),
-  dedicatedPreview: z3.boolean().default(true)
+  dedicatedPreview: z3.boolean().default(true),
+  close: z3.boolean().optional().describe(
+    "Close the current dedicated preview window instead of creating or resizing one. Width/height/profile are ignored when true. Idempotent: has no effect if no preview is open."
+  )
 });
 var viewportResultSchema = z3.strictObject({
   tabId: z3.number().int().nonnegative(),
@@ -363,7 +377,10 @@ var viewportResultSchema = z3.strictObject({
   exact: z3.boolean().optional(),
   attempts: z3.number().int().min(0).max(3).optional(),
   requiresTargetSelection: z3.boolean().optional(),
-  sourceWindowUnchanged: z3.boolean().optional()
+  sourceWindowUnchanged: z3.boolean().optional(),
+  previewClosed: z3.boolean().optional().describe(
+    "Present when close:true was requested. True if a dedicated preview window was actually open and closed; false if there was none to close."
+  )
 });
 var domSchema = targetSchema.extend({
   selector: z3.string().min(1).max(2048).optional(),
@@ -703,7 +720,7 @@ var RequestRouter = class {
       type,
       payload
     });
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(request.id);
         reject(
@@ -713,7 +730,7 @@ var RequestRouter = class {
           )
         );
       }, this.timeoutMs);
-      this.pending.set(request.id, { resolve: resolve2, reject, timer });
+      this.pending.set(request.id, { resolve: resolve3, reject, timer });
       try {
         this.send(request);
       } catch (error) {
@@ -1092,6 +1109,7 @@ var PairingService = class {
 
 // apps/mcp-server/src/bridge/websocket-server.ts
 var EMPTY_STATE = { selectedTab: null, url: null };
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 2e4;
 function browserFromOrigin(origin) {
   if (origin === void 0) return void 0;
   if (/^moz-extension:\/\/[a-f0-9-]+\/?$/i.test(origin)) return "firefox";
@@ -1121,6 +1139,12 @@ var Bridge = class {
       response.setHeader("Content-Type", "application/json");
       response.end(JSON.stringify(this.status()));
     });
+    this.http.once("error", (error) => {
+      this.listenError = error.code === "EADDRINUSE" ? new GSError(
+        "GS_PORT_IN_USE",
+        `Port ${config.port} is already in use by another GazeSight MCP server. Only one can run at a time -- close the other session first.`
+      ) : error;
+    });
     this.server = new WebSocketServer({
       server: this.http,
       maxPayload: 17 * 1024 * 1024,
@@ -1143,6 +1167,11 @@ var Bridge = class {
         this.wiring.delete(connection.connectionId);
         this.registry.remove(connection.connectionId);
       };
+      this.alive.set(socket, { pongReceived: true });
+      socket.on("pong", () => {
+        const state = this.alive.get(socket);
+        if (state) state.pongReceived = true;
+      });
       socket.on("error", () => {
       });
       socket.on("message", (bytes, binary) => {
@@ -1197,12 +1226,31 @@ var Bridge = class {
       });
       socket.on("close", teardown);
     });
+    this.heartbeat = setInterval(() => {
+      for (const socket of this.server.clients) {
+        const state = this.alive.get(socket);
+        if (!state) continue;
+        if (!state.pongReceived) {
+          socket.terminate();
+          continue;
+        }
+        state.pongReceived = false;
+        socket.ping();
+      }
+    }, config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS);
+    this.heartbeat.unref?.();
   }
   registry = new BrowserConnectionRegistry();
   activeTargetRouter = new ActiveTargetRouter();
   wiring = /* @__PURE__ */ new Map();
+  alive = /* @__PURE__ */ new WeakMap();
+  heartbeat;
   server;
   http;
+  listenError;
+  closePromise;
+  mcpClientCount = 0;
+  desktopIpcReady = false;
   pairing;
   // Resolves the connection currently backing the global active target, or
   // undefined if no browser is active (nothing selected yet, or the
@@ -1265,6 +1313,8 @@ var Bridge = class {
       })
     );
     return {
+      mcpClients: this.mcpClientCount,
+      desktopIpcReady: this.desktopIpcReady,
       connected: this.connected,
       paired: this.connected,
       authorizedPairings: this.pairing.listPairings().filter((item) => !item.revokedAt).length,
@@ -1277,18 +1327,47 @@ var Bridge = class {
       activeTarget: active ? { browser: active.browser, url: active.state.url } : null
     };
   }
+  setMcpClientCount(count) {
+    this.mcpClientCount = Math.max(0, Math.min(32, Math.floor(count)));
+  }
+  setDesktopIpcReady(ready) {
+    this.desktopIpcReady = ready;
+  }
   async ready() {
+    if (this.listenError) throw this.listenError;
     if (this.server.address()) return;
-    await new Promise((resolve2, reject) => {
-      this.server.once("listening", resolve2);
-      this.server.once("error", reject);
+    await new Promise((resolve3, reject) => {
+      const cleanup = () => {
+        this.server.off("listening", onListening);
+        this.server.off("error", onError);
+        this.http.off("error", onError);
+      };
+      const onListening = () => {
+        cleanup();
+        resolve3();
+      };
+      const onError = () => {
+        cleanup();
+        reject(this.listenError);
+      };
+      this.server.once("listening", onListening);
+      this.server.once("error", onError);
+      this.http.once("error", onError);
     });
   }
   async close() {
-    for (const wiring of this.wiring.values()) wiring.router.disconnect();
-    for (const client of this.server.clients) client.terminate();
-    await new Promise((resolve2) => this.server.close(() => resolve2()));
-    await new Promise((resolve2) => this.http.close(() => resolve2()));
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = (async () => {
+      clearInterval(this.heartbeat);
+      for (const wiring of this.wiring.values()) wiring.router.disconnect();
+      this.wiring.clear();
+      for (const client of this.server.clients) client.terminate();
+      if (this.http.listening)
+        await new Promise((resolve3) => this.http.close(() => resolve3()));
+      else if (this.server.address())
+        await new Promise((resolve3) => this.server.close(() => resolve3()));
+    })();
+    return this.closePromise;
   }
 };
 
@@ -1334,7 +1413,7 @@ async function pairingFlow(config, configPath, revoke) {
         const requests = (await response.json()).requests;
         const request = requests[0];
         if (!request) {
-          await new Promise((resolve2) => setTimeout(resolve2, 500));
+          await new Promise((resolve3) => setTimeout(resolve3, 500));
           continue;
         }
         console.log(`Pairing request: ${request.browser} \xB7 verification code ${request.code}`);
@@ -1351,7 +1430,7 @@ async function pairingFlow(config, configPath, revoke) {
               delivered = true;
               break;
             }
-            await new Promise((resolve2) => setTimeout(resolve2, 100));
+            await new Promise((resolve3) => setTimeout(resolve3, 100));
           }
           if (!delivered) throw new Error("The approved credential was not delivered; keep the extension open and retry pairing.");
           console.log("Pairing approved and delivered. The extension can now reconnect securely.");
@@ -1366,8 +1445,314 @@ async function pairingFlow(config, configPath, revoke) {
   }
 }
 
+// apps/agent-integration/src/index.ts
+import { spawn as nodeSpawn } from "node:child_process";
+import { constants as fsConstants, existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { delimiter, join, posix as posix2, resolve, win32 as win322 } from "node:path";
+var PROCESS_TIMEOUT_MS = 12e3;
+var PROCESS_OUTPUT_BYTES = 16 * 1024;
+function createBoundedRunner(spawnProcess = nodeSpawn) {
+  return (command, args2, options = {}) => runBounded(command, args2, options, spawnProcess);
+}
+var DEFAULT_SPAWN = createBoundedRunner();
+var runAgentCommand = DEFAULT_SPAWN;
+function runBounded(command, args2, options = {}, spawnProcess = nodeSpawn) {
+  return new Promise((resolveResult) => {
+    let child;
+    try {
+      child = spawnProcess(command, [...args2], {
+        shell: false,
+        windowsHide: true,
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch {
+      resolveResult({ code: null, stdout: "", stderr: "", timedOut: false });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const append = (current, chunk) => {
+      const value = current + String(chunk);
+      return Buffer.byteLength(value) <= PROCESS_OUTPUT_BYTES ? value : Buffer.from(value).subarray(0, PROCESS_OUTPUT_BYTES).toString();
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout = append(stdout, chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = append(stderr, chunk);
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+    }, options.timeoutMs ?? PROCESS_TIMEOUT_MS);
+    child.once("error", () => {
+      clearTimeout(timer);
+      resolveResult({ code: null, stdout, stderr, timedOut });
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolveResult({ code, stdout, stderr, timedOut });
+    });
+  });
+}
+function pathCandidates(agent, platform, env, home) {
+  const name = agent === "claude" ? "claude" : "codex";
+  const pathJoin = (platform === "win32" ? win322 : posix2).join;
+  const native = [];
+  const packageScripts = [];
+  if (platform === "win32") {
+    const packageManagerBins = [env.PNPM_HOME, env.NPM_CONFIG_PREFIX].filter((value) => Boolean(value)).flatMap((root2) => [pathJoin(root2, `${name}.exe`), pathJoin(root2, `${name}.cmd`)]);
+    if (agent === "claude") {
+      native.push(
+        pathJoin(home, ".local", "bin", "claude.exe"),
+        pathJoin(env.LOCALAPPDATA ?? pathJoin(home, "AppData", "Local"), "Programs", "Claude", "claude.exe"),
+        pathJoin(env.ProgramFiles ?? "C:\\Program Files", "Claude", "claude.exe")
+      );
+    } else {
+      native.push(
+        pathJoin(env.LOCALAPPDATA ?? pathJoin(home, "AppData", "Local"), "Programs", "OpenAI", "Codex", "bin", "codex.exe")
+      );
+    }
+    const npm = pathJoin(env.APPDATA ?? pathJoin(home, "AppData", "Roaming"), "npm", `${name}.cmd`);
+    const modules = [
+      pathJoin(env.APPDATA ?? pathJoin(home, "AppData", "Roaming"), "npm", "node_modules"),
+      ...env.NPM_CONFIG_PREFIX ? [pathJoin(env.NPM_CONFIG_PREFIX, "node_modules")] : [],
+      ...env.PNPM_HOME ? [pathJoin(env.PNPM_HOME, "global", "5", "node_modules"), pathJoin(env.PNPM_HOME, "node_modules")] : [],
+      pathJoin(home, "AppData", "Local", "pnpm", "global", "5", "node_modules")
+    ];
+    const packageName = agent === "claude" ? "@anthropic-ai/claude-code" : "@openai/codex";
+    const nodeCandidates = [
+      env.ProgramFiles ? pathJoin(env.ProgramFiles, "nodejs", "node.exe") : "C:\\Program Files\\nodejs\\node.exe",
+      ...env.LOCALAPPDATA ? [pathJoin(env.LOCALAPPDATA, "Programs", "nodejs", "node.exe")] : [],
+      ...(env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean).map((directory) => pathJoin(directory, "node.exe"))
+    ];
+    for (const modulesRoot of modules) {
+      const root2 = pathJoin(modulesRoot, packageName);
+      try {
+        const metadata = JSON.parse(readFileSync2(pathJoin(root2, "package.json"), "utf8"));
+        const bin = typeof metadata.bin === "string" ? metadata.bin : metadata.bin && typeof metadata.bin === "object" ? metadata.bin[name] : void 0;
+        if (typeof bin !== "string" || bin.startsWith("/") || bin.split(/[\\/]/).includes("..")) continue;
+        const script = pathJoin(root2, bin);
+        for (const node of nodeCandidates)
+          packageScripts.push({ command: node, prefixArgs: [script], source: "verified npm package" });
+      } catch {
+      }
+    }
+    native.push(npm, ...packageManagerBins);
+  } else {
+    native.push(
+      pathJoin(home, ".local", "bin", name),
+      pathJoin(home, ".npm-global", "bin", name),
+      pathJoin(home, ".local", "share", "pnpm", name),
+      ...env.PNPM_HOME ? [pathJoin(env.PNPM_HOME, name)] : [],
+      ...env.NPM_CONFIG_PREFIX ? [pathJoin(env.NPM_CONFIG_PREFIX, "bin", name)] : []
+    );
+    if (platform === "darwin")
+      native.push(
+        pathJoin(home, "Library", "pnpm", name),
+        "/opt/homebrew/bin/" + name,
+        "/usr/local/bin/" + name
+      );
+    else if (platform === "linux")
+      native.push("/usr/bin/" + name, "/usr/local/bin/" + name);
+  }
+  const fromPath = (env.PATH ?? env.Path ?? "").split(delimiter).filter(Boolean).flatMap(
+    (directory) => platform === "win32" ? [pathJoin(directory, `${name}.exe`), pathJoin(directory, `${name}.cmd`)] : [pathJoin(directory, name)]
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const direct = [...native, ...fromPath].filter((path) => {
+    const key = platform === "win32" ? path.toLowerCase() : path;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).map((command) => ({ command, prefixArgs: [], source: "candidate" }));
+  return [...packageScripts, ...direct];
+}
+async function verifyCandidate(candidate, platform) {
+  try {
+    const canonical = await realpath(candidate.command);
+    if (canonical.includes("..")) return void 0;
+    const info = await stat(canonical);
+    if (!info.isFile()) return void 0;
+    for (const argument of candidate.prefixArgs) {
+      if (!argument.toLowerCase().endsWith(".js")) continue;
+      const script = await realpath(argument);
+      if (!(await stat(script)).isFile()) return void 0;
+      if (platform === "win32" && !script.toLowerCase().endsWith(".js")) return void 0;
+    }
+    if (platform !== "win32") {
+      await access(canonical, fsConstants.X_OK);
+      if ((info.mode & 73) === 0) return void 0;
+    } else if (!/\.(exe|cmd)$/i.test(canonical)) return void 0;
+    return { ...candidate, command: canonical };
+  } catch {
+    return void 0;
+  }
+}
+function parseVersion(agent, output) {
+  const value = output.match(/\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/)?.[1];
+  if (!value) return void 0;
+  if (agent === "claude" && Number(value.split(".")[0]) < 2) return void 0;
+  return value;
+}
+async function findAgentBinary(id, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.USERPROFILE ?? env.HOME ?? "";
+  const run = options.spawn ?? DEFAULT_SPAWN;
+  let sawCandidate = false;
+  let sawDiscoveryError = false;
+  for (const pathCandidate of pathCandidates(id, platform, env, home)) {
+    const candidate = await verifyCandidate(pathCandidate, platform);
+    if (!candidate) continue;
+    sawCandidate = true;
+    const versionResult = await run(candidate.command, [...candidate.prefixArgs, "--version"], { timeoutMs: PROCESS_TIMEOUT_MS, cwd: home });
+    const version = versionResult.code === 0 ? parseVersion(id, `${versionResult.stdout}
+${versionResult.stderr}`) : void 0;
+    const help = await run(candidate.command, [...candidate.prefixArgs, "mcp", "--help"], { timeoutMs: PROCESS_TIMEOUT_MS, cwd: home });
+    if (help.code === 0 && /\badd\b/i.test(help.stdout + help.stderr) && /\bremove\b/i.test(help.stdout + help.stderr))
+      return { candidate, installation: version ? "INSTALLED" : "INSTALLED_VERSION_UNKNOWN", ...version ? { version } : {} };
+    if (!version || help.timedOut || versionResult.timedOut) sawDiscoveryError = true;
+  }
+  return {
+    installation: sawDiscoveryError ? "DISCOVERY_ERROR" : sawCandidate ? "UNSUPPORTED_VERSION" : "NOT_INSTALLED"
+  };
+}
+function parseMcpEntry(agent, output) {
+  const command = output.match(/^\s*(?:Command|command):\s*(.+)$/im)?.[1]?.trim();
+  const args2 = output.match(/^\s*(?:Args|args):\s*(.*)$/im)?.[1]?.trim();
+  if (!command || args2 === void 0) return void 0;
+  const scopeText = output.match(/^\s*Scope:\s*(.+)$/im)?.[1]?.trim().toLowerCase() ?? "user";
+  const scope = scopeText.match(/^(user|project|local)\b/)?.[1] ?? "user";
+  const legacyNpm = /(?:^|\s)(?:npx(?:\.cmd)?\s+(?:(?:--yes|-y)\s+)?(?:gazesight|@gazesight\/mcp-server)|gazesight(?:@\d+\.\d+\.\d+)?\s+mcp)(?:\s|$)/i.test(`${command} ${args2}`) || /[\\/]_npx[\\/]/i.test(`${command} ${args2}`);
+  const knownOwner = legacyNpm || /(?:^|[\\/])dist[\\/]cli[\\/]index\.js(?:\s|$)/i.test(args2) && /\bmcp\b/i.test(args2);
+  const oldCli = args2.match(/^(.*?[\\/]dist[\\/]cli[\\/]index\.js)\s+mcp(?:\s+--config\s+(.+?))?(?:\s+(--desktop-adapter))?$/i);
+  const oldNpm = args2.match(/^(--yes\s+)?(gazesight(?:@\d+\.\d+\.\d+)?|@gazesight\/mcp-server)(?:\s+--yes)?\s+mcp(?:\s+--config\s+(.+))?$/i);
+  const argsVector = oldCli ? [oldCli[1], "mcp", ...oldCli[2] ? ["--config", oldCli[2]] : [], ...oldCli[3] ? [oldCli[3]] : []] : oldNpm ? [...oldNpm[1] ? ["--yes"] : [], oldNpm[2], "mcp", ...oldNpm[3] ? ["--config", oldNpm[3]] : []] : /(?:^|[\\/])gazesight(?:-mcp)?(?:\.cmd|\.exe)?$/i.test(command) && /^mcp\b/i.test(args2) ? ["mcp", ...args2.match(/^mcp\s+--config\s+(.+)$/i)?.[1] ? ["--config", args2.match(/^mcp\s+--config\s+(.+)$/i)[1]] : []] : args2.split(/\s+/).filter(Boolean);
+  return { command, args: args2, argsVector, scope: agent === "claude" ? scope : "user", legacyNpm, knownOwner };
+}
+async function getEntry(agent, binary, run) {
+  const result = await run(binary.command, [...binary.prefixArgs, "mcp", "get", "gazesight"], { timeoutMs: PROCESS_TIMEOUT_MS });
+  const output = `${result.stdout}
+${result.stderr}`;
+  const headers2 = output.match(/(?:^|\n)\s*gazesight\s*:?\s*(?=\r?\n|$)/gi) ?? [];
+  const entry = result.code === 0 && headers2.length <= 1 ? parseMcpEntry(agent, output) : void 0;
+  const named = headers2.length > 0;
+  return { entry, named, code: result.code, output };
+}
+function cliArgs(agent, operation, launch, scope) {
+  if (operation === "remove") return agent === "claude" ? ["mcp", "remove", "gazesight", "-s", scope ?? "user"] : ["mcp", "remove", "gazesight"];
+  const spec = launch;
+  return agent === "claude" ? ["mcp", "add", "--transport", "stdio", "-s", scope ?? "user", "gazesight", "--", spec.command, ...spec.args] : ["mcp", "add", "gazesight", "--", spec.command, ...spec.args];
+}
+function sameLaunch(entry, launch) {
+  const norm = (value) => {
+    return value.trim().replace(/^['"]|['"]$/g, "").replaceAll("\\", "/").toLowerCase();
+  };
+  return norm(entry.command) === norm(launch.command) && norm(entry.args) === norm(launch.args.join(" "));
+}
+async function verifyCurrent(agent, binary, launch, run) {
+  const result = await getEntry(agent, binary, run);
+  return result.entry && result.entry.knownOwner && sameLaunch(result.entry, launch);
+}
+function safeCliFailure(result) {
+  if (result.timedOut) return "TIMEOUT";
+  const value = `${result.stderr}
+${result.stdout}`;
+  if (/eacces|eperm|access denied|permission denied/i.test(value)) return "PERMISSION";
+  if (/scope/i.test(value)) return "SCOPE";
+  if (/managed|read.only|policy/i.test(value)) return "MANAGED";
+  if (/not found|not configured|no (?:mcp )?server|does not exist/i.test(value)) return "ENTRY";
+  if (result.code === null) return "SPAWN";
+  return "OTHER";
+}
+async function reconcileMcpEntry(id, binary, launch, action, run = DEFAULT_SPAWN, cwd) {
+  const invoke = (args2) => run(binary.command, [...binary.prefixArgs, ...args2], { timeoutMs: PROCESS_TIMEOUT_MS, cwd });
+  const before = await getEntry(id, binary, (command, args2, options) => run(command, args2, { ...options, cwd }));
+  if (before.named && !before.entry) return { ok: false, state: "conflict", message: "AGENT_ENTRY_AMBIGUOUS" };
+  if (before.entry && !before.entry.knownOwner) return { ok: false, state: "conflict", message: "AGENT_ENTRY_AMBIGUOUS" };
+  if (action === "configure" && before.entry) {
+    return sameLaunch(before.entry, launch) ? { ok: true, state: "identical", message: "Already configured and verified." } : { ok: false, state: "outdated", message: "AGENT_ALREADY_CONFIGURED" };
+  }
+  if (action === "repair" && !before.entry)
+    return { ok: false, state: "failed", message: "AGENT_NOT_CONFIGURED" };
+  if (action === "repair" && before.entry && sameLaunch(before.entry, launch))
+    return { ok: true, state: "identical", message: "Already configured and verified." };
+  if (action === "remove" && !before.entry)
+    return { ok: false, state: "failed", message: "AGENT_NOT_CONFIGURED" };
+  const old = before.entry;
+  const safeRun = (command, args2, options) => run(command, args2, { ...options, cwd });
+  if (old) {
+    const removed = await invoke(cliArgs(id, "remove", void 0, old.scope));
+    if (removed.code !== 0)
+      return {
+        ok: false,
+        state: "failed",
+        message: `AGENT_REMOVE_FAILED_${safeCliFailure(removed)}`
+      };
+    const after = await getEntry(id, binary, safeRun);
+    if (after.entry || after.named) {
+      await invoke(cliArgs(id, "add", { command: old.command, args: old.argsVector, version: "legacy" }, old.scope));
+      return { ok: false, state: "failed", message: "AGENT_REMOVE_VERIFY_FAILED" };
+    }
+    if (action === "remove") return { ok: true, state: "removed", message: "Removed and verified." };
+  }
+  const added = await invoke(cliArgs(id, "add", launch));
+  if (added.code === 0 && await verifyCurrent(id, binary, launch, safeRun))
+    return { ok: true, state: old ? "updated" : "configured", message: old ? "Repaired and verified." : "Configured and verified." };
+  if (old) {
+    const maybe = await getEntry(id, binary, safeRun);
+    if (maybe.entry?.knownOwner) await invoke(cliArgs(id, "remove", void 0, maybe.entry.scope));
+    await invoke(cliArgs(id, "add", { command: old.command, args: old.argsVector, version: "legacy" }, old.scope));
+  }
+  return {
+    ok: false,
+    state: "failed",
+    message: added.timedOut ? "AGENT_OPERATION_TIMEOUT" : "AGENT_CONFIGURE_VERIFY_FAILED"
+  };
+}
+
+// apps/cli/src/agent-config.ts
+import { homedir as homedir2 } from "node:os";
+function safeFailure(result) {
+  const value = result.stderr || result.stdout || "unknown error";
+  return value.trim().split(/\r?\n/)[0].slice(0, 180);
+}
+async function configureAgent(agent, binaryPath, proposed, allowUpdate, spawn) {
+  const run = async (command, args2) => {
+    if (!spawn) return runAgentCommand(command, args2);
+    const result2 = spawn(command, args2);
+    return {
+      code: result2.status,
+      stdout: result2.stdout,
+      stderr: result2.stderr,
+      timedOut: false
+    };
+  };
+  const binary = typeof binaryPath === "string" ? { command: binaryPath, prefixArgs: [], source: "cli setup" } : binaryPath;
+  const result = await reconcileMcpEntry(
+    agent,
+    binary,
+    proposed,
+    allowUpdate ? "repair" : "configure",
+    run,
+    homedir2()
+  );
+  const states = ["configured", "identical", "outdated", "updated", "conflict", "failed"];
+  const state = states.includes(result.state) ? result.state : "failed";
+  return {
+    ok: result.ok,
+    state,
+    message: result.ok ? result.message : `${result.message}${result.message.startsWith("AGENT_") ? "" : ` \u2014 ${safeFailure({ stdout: "", stderr: result.message })}`}`
+  };
+}
+
 // apps/cli/src/index.ts
-var root = resolve(dirname2(fileURLToPath(import.meta.url)), "..");
+var root = resolve2(dirname2(fileURLToPath(import.meta.url)), "..");
 var args = process.argv.slice(2);
 function option(name) {
   const i = args.indexOf(name);
@@ -1376,14 +1761,6 @@ function option(name) {
     throw new Error("Missing option value.");
   return args[i + 1];
 }
-function detectOnPath(binary) {
-  for (const directory of (process.env.PATH ?? "").split(delimiter))
-    for (const name of [binary, `${binary}.exe`, `${binary}.cmd`]) {
-      const candidate = join2(directory, name);
-      if (existsSync(candidate)) return candidate;
-    }
-  return void 0;
-}
 async function promptClientChoice() {
   if (!process.stdin.isTTY) return ["claude", "codex"];
   const rl = createInterface2({ input: process.stdin, output: process.stdout });
@@ -1398,38 +1775,8 @@ async function promptClientChoice() {
     rl.close();
   }
 }
-function configureAgent(agent, binaryPath, serverArgs) {
-  if (agent === "claude") {
-    const existing = spawnSync(binaryPath, ["mcp", "get", "gazesight"], {
-      encoding: "utf8"
-    });
-    if (existing.status === 0)
-      return { ok: true, message: "Already configured (unchanged)." };
-    const add2 = spawnSync(
-      binaryPath,
-      ["mcp", "add", "gazesight", "--scope", "user", "--", ...serverArgs],
-      { encoding: "utf8" }
-    );
-    if (add2.status === 0) return { ok: true, message: "Configured." };
-    return {
-      ok: false,
-      message: `Failed: ${(add2.stderr || add2.stdout || "unknown error").trim().split("\n")[0]}`
-    };
-  }
-  const list = spawnSync(binaryPath, ["mcp", "list"], { encoding: "utf8" });
-  if (list.status === 0 && list.stdout.includes("gazesight"))
-    return { ok: true, message: "Already configured (unchanged)." };
-  const add = spawnSync(binaryPath, ["mcp", "add", "gazesight", "--", ...serverArgs], {
-    encoding: "utf8"
-  });
-  if (add.status === 0) return { ok: true, message: "Configured." };
-  return {
-    ok: false,
-    message: `Failed: ${(add.stderr || add.stdout || "unknown error").trim().split("\n")[0]}`
-  };
-}
 try {
-  const configPath = resolve(
+  const configPath = resolve2(
     option("--config") ?? process.env.GAZESIGHT_CONFIG_FILE ?? defaultConfigPath()
   );
   if (args[0] === "mcp") {
@@ -1439,24 +1786,31 @@ try {
   else if (!args[0] || args.includes("--help"))
     console.log(
       `GazeSight ${VERSION}
-gazesight setup [--config PATH] [--port PORT] [--client claude|codex|both]
+gazesight setup [--config PATH] [--port PORT] [--client claude|codex|both] [--update]
 gazesight pair [--config PATH] [--revoke ID|all]
 gazesight doctor [--config PATH]
 gazesight mcp [--config PATH]
+--update replaces only an outdated GazeSight MCP entry after showing the existing and proposed configurations.
+Claude Code and Codex may both be configured, but only one MCP process can own a configured bridge port at a time. A second process exits with GS_PORT_IN_USE; close the first client session or configure a separate port.
 No browser is launched. Secrets are never printed.`
     );
   else {
     if (!["setup", "doctor", "pair"].includes(args[0]))
       throw new Error("Unknown command.");
-    if (args.slice(1).some(
-      (value, i) => i % 2 === 0 && !["--config", "--port", "--client", "--revoke"].includes(value)
-    ))
-      throw new Error("Unknown option.");
+    const valueOptions = /* @__PURE__ */ new Set(["--config", "--port", "--client", "--revoke"]);
+    const flagOptions = /* @__PURE__ */ new Set(["--update"]);
+    for (let i = 1; i < args.length; i++) {
+      const value = args[i];
+      if (flagOptions.has(value)) continue;
+      if (!valueOptions.has(value) || !args[i + 1] || args[i + 1].startsWith("--"))
+        throw new Error("Unknown option or missing option value.");
+      i++;
+    }
     const clientOption = option("--client");
     if (clientOption && !["claude", "codex", "both"].includes(clientOption))
       throw new Error("--client must be claude, codex, or both.");
     const node = Number(process.versions.node.split(".")[0]) >= 20;
-    const build = existsSync(join2(root, "mcp/index.js")) && existsSync(join2(root, "firefox/manifest.json"));
+    const build = existsSync2(join2(root, "mcp/index.js")) && existsSync2(join2(root, "firefox/manifest.json"));
     console.log(
       `Node: ${node ? "PASS" : "FAIL"}
 GazeSight build: ${build ? "PASS" : "FAIL"}`
@@ -1481,17 +1835,28 @@ Agent guidance: ${config.agentGuidance.enabled ? "Enabled" : "Disabled"}${config
         "--config",
         configPath
       ];
+      if (chosen.length > 1)
+        console.log(
+          "Shared-use notice: Claude Code and Codex will both be configured, but they cannot use the same bridge port simultaneously. The first MCP process owns the port; a second exits explicitly with GS_PORT_IN_USE. Close the first client session before starting the other, or configure a separate port/config."
+        );
+      const proposed = {
+        command: serverArgs[0],
+        args: serverArgs.slice(1),
+        version: VERSION
+      };
+      const available = /* @__PURE__ */ new Set();
       for (const agent of chosen) {
         const label = agent === "claude" ? "Claude Code" : "Codex";
-        const binaryPath = detectOnPath(agent);
-        if (!binaryPath) {
+        const binary = await findAgentBinary(agent, { home: process.env.USERPROFILE ?? process.env.HOME, env: process.env });
+        if (!binary.candidate) {
           console.log(`${label}: not detected on PATH \u2014 configure manually below.`);
           continue;
         }
-        const result2 = configureAgent(agent, binaryPath, serverArgs);
+        available.add(agent);
+        const result2 = await configureAgent(agent, binary.candidate, proposed, args.includes("--update"));
         console.log(`${label}: ${result2.ok ? "PASS" : "FAIL"} \u2014 ${result2.message}`);
       }
-      const undetected = explicit ? chosen.filter((agent) => !detectOnPath(agent)) : ["claude", "codex"];
+      const undetected = explicit ? chosen.filter((agent) => !available.has(agent)) : ["claude", "codex"];
       if (undetected.length) {
         const server = { command: process.execPath, args: serverArgs.slice(1) };
         if (undetected.includes("claude")) {
@@ -1511,10 +1876,9 @@ args = ${JSON.stringify(server.args)}`
       }
       console.log(
         `Open your GazeSight browser extension and click Connect to GazeSight.
-Chrome (manual install, not yet on the Chrome Web Store): open chrome://extensions, enable Developer mode, "Load unpacked", select ${join2(root, "chrome")}.
-Development only (Firefox): about:debugging > Load Temporary Add-on > ${join2(root, "firefox/manifest.json")}
-Unsigned XPI: ${join2(root, "gazesight-firefox.xpi")}
-External Firefox Release/Beta installation requires the separately supplied Mozilla-signed XPI.
+Firefox: install or update the signed extension from the official listing \u2014 https://addons.mozilla.org/addon/6a2319d4fa544731884d/.
+Chrome: install or update the public extension from the Chrome Web Store \u2014 https://chromewebstore.google.com/detail/gazesight/hikhblabkhbaoilcffenldphdkjdmphc.
+Development only (building from this checkout, Firefox): about:debugging > Load Temporary Add-on > ${join2(root, "firefox/manifest.json")}, or install the unsigned XPI at ${join2(root, "gazesight-firefox.xpi")}.
 Manual JSON import remains available under Advanced settings.`
       );
       if (process.stdin.isTTY) await pairingFlow(config, configPath);