gazesight 0.3.5 → 0.5.0

package/dist/cli/index.js

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 // apps/cli/src/index.ts
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { createInterface } from "node:readline/promises";
-import { resolve, dirname as dirname2, join as join2, delimiter } from "node:path";
+import { existsSync as existsSync2 } from "node:fs";
+import { createInterface as createInterface2 } from "node:readline/promises";
+import { resolve as resolve2, dirname as dirname2, join as join2, delimiter } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // apps/cli/src/config.ts
 import { randomBytes } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
@@ -22,6 +21,17 @@ var agentGuidanceSchema = z.strictObject({
 var localConfigSchema = z.strictObject({
   token: z.string().regex(/^[a-f0-9]{64}$/),
   port: z.number().int().min(1024).max(65535),
+  pairings: z.array(
+    z.strictObject({
+      id: z.string().uuid(),
+      browser: z.enum(["firefox", "chrome"]),
+      extensionId: z.string().min(1).max(256),
+      origin: z.string().min(1).max(300),
+      credentialHash: z.string().regex(/^[a-f0-9]{64}$/),
+      createdAt: z.string().datetime(),
+      revokedAt: z.string().datetime().optional()
+    })
+  ).max(32).default([]),
   allowedOrigins: z.array(z.url()).default([]),
   agentGuidance: agentGuidanceSchema.default({
     enabled: true,
@@ -81,9 +91,17 @@ function setupConfig(path, port) {
   }
   return config;
 }
+function writeLocalConfig(path, value) {
+  const config = localConfigSchema.parse(value);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(config, null, 2), { mode: 384 });
+  renameSync(temporary, path);
+  return config;
+}
 
 // packages/protocol/src/release.ts
-var VERSION = "0.3.5";
+var VERSION = "0.5.0";
 
 // apps/cli/src/doctor.ts
 import { z as z2 } from "zod";
@@ -102,12 +120,12 @@ function diagnosticRows(status, reachable = false, authenticated = false) {
     {
       name: "extension connected",
       pass: !!status?.connected,
-      action: "Load the Firefox or Chrome extension and import your local config in its extension options."
+      action: status?.authorizedPairings ? "An extension is paired but disconnected. Start it and verify the configured bridge port." : "Open Firefox or Chrome, then click Connect to GazeSight in the extension."
     },
     {
       name: "pairing",
       pass: authenticated && !!status?.paired,
-      action: "Import the same local configuration into Firefox options; verify port and pairing."
+      action: "Run gazesight pair, click Connect to GazeSight, and approve the matching code."
     },
     {
       name: "target selected",
@@ -145,11 +163,1415 @@ var statusSchema = z2.object({
   connected: z2.boolean(),
   paired: z2.boolean(),
   targetState: z2.enum(["none", "authorized", "reauthorization_required"]),
-  backgroundCapture: z2.object({ enabled: z2.boolean(), permissionGranted: z2.boolean() }).optional()
+  backgroundCapture: z2.object({ enabled: z2.boolean(), permissionGranted: z2.boolean() }).optional(),
+  authorizedPairings: z2.number().int().nonnegative().optional()
 });
 
+// apps/cli/src/pair.ts
+import { createInterface } from "node:readline/promises";
+
+// apps/mcp-server/src/bridge/websocket-server.ts
+import { WebSocketServer, WebSocket } from "ws";
+
+// packages/protocol/src/schemas.ts
+import { z as z3 } from "zod";
+var targetSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative().optional()
+});
+var stabilityDiagnosticsSchema = z3.strictObject({
+  stable: z3.boolean(),
+  stabilityWaitMs: z3.number().finite().nonnegative(),
+  lastMutationAgoMs: z3.number().finite().nonnegative(),
+  fontsReady: z3.boolean(),
+  pendingImages: z3.number().int().nonnegative().max(1e6),
+  timeoutReached: z3.boolean()
+});
+var diagnosticsQuerySchema = targetSchema.extend({
+  maxEntries: z3.number().int().min(1).max(100).default(50),
+  reset: z3.boolean().default(true)
+});
+var highlightSchema = targetSchema.extend({
+  selector: z3.string().min(1).max(2048),
+  durationMs: z3.number().int().min(500).max(3e4).default(3e3)
+});
+var highlightResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url(),
+  highlighted: z3.boolean()
+});
+var consoleEntrySchema = z3.strictObject({
+  level: z3.enum(["warn", "error"]),
+  message: z3.string().max(512),
+  timestamp: z3.number().finite().nonnegative()
+});
+var networkEntrySchema = z3.strictObject({
+  url: z3.url().max(1024),
+  method: z3.string().max(16),
+  resourceType: z3.string().max(32),
+  status: z3.number().int().min(100).max(599).optional(),
+  error: z3.string().max(128).optional(),
+  timestamp: z3.number().finite().nonnegative()
+});
+var consoleResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  entries: z3.array(consoleEntrySchema).max(100),
+  dropped: z3.number().int().nonnegative(),
+  forwardingDropped: z3.number().int().nonnegative()
+});
+var networkResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  entries: z3.array(networkEntrySchema).max(100),
+  dropped: z3.number().int().nonnegative()
+});
+var pageStatusContentSchema = z3.strictObject({
+  url: z3.url(),
+  title: z3.string().max(160),
+  readyState: z3.enum(["loading", "interactive", "complete"]),
+  viewport: z3.strictObject({
+    width: z3.number().int().positive(),
+    height: z3.number().int().positive(),
+    devicePixelRatio: z3.number().finite().positive()
+  }),
+  scroll: z3.strictObject({ x: z3.number().finite(), y: z3.number().finite() }),
+  stabilityPending: z3.boolean(),
+  consoleInstrumentationActive: z3.boolean(),
+  consoleForwardingDropped: z3.number().int().nonnegative()
+});
+var pageStatusResultSchema = pageStatusContentSchema.extend({
+  tabId: z3.number().int().nonnegative(),
+  targetState: z3.enum(["authorized", "reauthorization_required", "none"]),
+  runtimeErrorCount: z3.number().int().nonnegative(),
+  consoleEntryCount: z3.number().int().nonnegative(),
+  networkFailureCount: z3.number().int().nonnegative()
+});
+var interactionTypeSchema = z3.enum([
+  "click",
+  "type",
+  "press_key",
+  "hover",
+  "scroll",
+  "select",
+  "focus"
+]);
+var interactionTargetSchema = targetSchema.extend({
+  selector: z3.string().min(1).max(2048)
+});
+var typeSchema = interactionTargetSchema.extend({
+  text: z3.string().max(4096),
+  clear: z3.boolean().default(true)
+});
+var pressKeySchema = targetSchema.extend({
+  selector: z3.string().min(1).max(2048).optional(),
+  key: z3.string().max(12).refine(
+    (key) => key.length === 1 || [
+      "Enter",
+      "Escape",
+      "Tab",
+      "Backspace",
+      "Delete",
+      "ArrowUp",
+      "ArrowDown",
+      "ArrowLeft",
+      "ArrowRight",
+      "Home",
+      "End"
+    ].includes(key)
+  ),
+  shift: z3.boolean().default(false)
+});
+var scrollSchema = targetSchema.extend({
+  selector: z3.string().min(1).max(2048).optional(),
+  x: z3.number().finite().min(-1e6).max(1e6).default(0),
+  y: z3.number().finite().min(-1e6).max(1e6).default(0),
+  mode: z3.enum(["by", "to"]).default("by")
+});
+var selectSchema = interactionTargetSchema.extend({
+  value: z3.string().max(4096)
+});
+var interactionResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url(),
+  action: interactionTypeSchema,
+  inputSource: z3.literal("dom"),
+  completed: z3.literal(true),
+  scroll: z3.strictObject({ x: z3.number().finite(), y: z3.number().finite() }).optional()
+});
+var captureSchema = targetSchema.extend({
+  url: z3.url().optional(),
+  format: z3.enum(["png", "jpeg"]).default("jpeg"),
+  quality: z3.number().int().min(0).max(100).default(85),
+  waitForStable: z3.boolean().default(false),
+  includeOverlay: z3.boolean().optional(),
+  stableWindowMs: z3.number().int().min(20).max(1e3).default(100),
+  maxWaitMs: z3.number().int().min(50).max(5e3).default(2e3)
+});
+var reloadSchema = targetSchema.extend({
+  bypassCache: z3.boolean().default(false)
+});
+var regionCaptureSchema = captureSchema.extend({
+  x: z3.number().finite().nonnegative(),
+  y: z3.number().finite().nonnegative(),
+  width: z3.number().finite().positive().max(32768),
+  height: z3.number().finite().positive().max(32768)
+});
+var elementCaptureSchema = captureSchema.extend({
+  selector: z3.string().min(1).max(2048),
+  padding: z3.number().finite().min(0).max(1e3).default(0)
+});
+var fullPageCaptureSchema = captureSchema.extend({
+  maxPixels: z3.number().int().min(1).max(32e6).default(16e6),
+  maxSegments: z3.number().int().min(1).max(64).default(32),
+  timeoutMs: z3.number().int().min(500).max(8e3).default(7e3)
+});
+var navigateSchema = targetSchema.extend({ url: z3.url() });
+var diffSchema = z3.strictObject({
+  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(),
+  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",
+  "mobile",
+  "tablet",
+  "desktop",
+  "desktop-wide"
+]);
+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),
+  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(),
+  url: z3.url(),
+  windowId: z3.number().int().nonnegative(),
+  width: z3.number().int().positive(),
+  height: z3.number().int().positive(),
+  devicePixelRatio: z3.number().finite().positive(),
+  zoom: z3.number().finite().positive(),
+  outerWidth: z3.number().int().positive(),
+  outerHeight: z3.number().int().positive(),
+  dedicatedPreview: z3.boolean(),
+  sourceTabId: z3.number().int().nonnegative().optional(),
+  requested: z3.strictObject({
+    width: z3.number().int().positive(),
+    height: z3.number().int().positive(),
+    profile: viewportProfileSchema.optional()
+  }).optional(),
+  exact: z3.boolean().optional(),
+  attempts: z3.number().int().min(0).max(3).optional(),
+  requiresTargetSelection: 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(),
+  depth: z3.number().int().min(0).max(8).default(3),
+  maxNodes: z3.number().int().min(1).max(300).default(100),
+  textLength: z3.number().int().min(0).max(300).default(160),
+  maxBytes: z3.number().int().min(2048).max(65536).default(32768)
+});
+var getElementSchema = domSchema.extend({
+  selector: z3.string().min(1).max(2048)
+});
+var changedRegionsSchema = targetSchema.extend({
+  maxRegions: z3.number().int().min(1).max(100).default(50),
+  reset: z3.boolean().default(true)
+});
+var capabilitySchema = z3.enum([
+  "highlight",
+  "clear_highlight",
+  "capture_region",
+  "capture_element",
+  "capture_full_page",
+  "get_dom",
+  "get_element",
+  "get_changed_regions",
+  "get_viewport",
+  "set_viewport",
+  ...interactionTypeSchema.options,
+  "get_console",
+  "get_network_failures",
+  "get_page_status"
+]);
+var boundsSchema = z3.strictObject({
+  x: z3.number().finite(),
+  y: z3.number().finite(),
+  width: z3.number().finite().nonnegative(),
+  height: z3.number().finite().nonnegative()
+});
+var domNodeSchema = z3.strictObject({
+  index: z3.number().int().nonnegative(),
+  parent: z3.number().int().nonnegative().optional(),
+  depth: z3.number().int().min(0).max(8),
+  tag: z3.string().max(80),
+  id: z3.string().max(160).optional(),
+  classes: z3.array(z3.string().max(80)).max(6).optional(),
+  role: z3.string().max(80).optional(),
+  text: z3.string().max(300).optional(),
+  ariaLabel: z3.string().max(300).optional(),
+  name: z3.string().max(160).optional(),
+  type: z3.string().max(80).optional(),
+  href: z3.string().max(1024).optional(),
+  bounds: boundsSchema,
+  visible: z3.boolean(),
+  redacted: z3.boolean().optional(),
+  disabled: z3.boolean().optional(),
+  checked: z3.boolean().optional(),
+  selected: z3.boolean().optional()
+});
+var domResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url(),
+  nodes: z3.array(domNodeSchema).max(300),
+  truncated: z3.boolean(),
+  payloadBytes: z3.number().int().max(65536)
+});
+var changedRegionsResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url(),
+  regions: z3.array(
+    boundsSchema.extend({
+      reason: z3.enum(["mutation", "resize", "attribute", "text"]),
+      selector: z3.string().max(240).optional()
+    })
+  ).max(100),
+  trackingStarted: z3.boolean(),
+  dropped: z3.number().int().nonnegative(),
+  coverage: z3.literal("potential-dom-and-layout-changes")
+});
+var errorSchema = z3.strictObject({
+  type: z3.enum(["error", "unhandledrejection", "console-error"]),
+  message: z3.string().max(4096),
+  source: z3.string().max(2048).optional(),
+  line: z3.number().int().nonnegative().optional(),
+  column: z3.number().int().nonnegative().optional(),
+  timestamp: z3.number().nonnegative()
+});
+var stateSchema = z3.strictObject({
+  extensionVersion: z3.string().max(80).optional(),
+  extensionId: z3.string().min(1).max(256).optional(),
+  capabilities: z3.array(capabilitySchema).max(20).optional(),
+  selectedTab: z3.number().int().nonnegative().nullable(),
+  url: z3.string().max(2048).nullable(),
+  targetState: z3.enum(["none", "authorized", "reauthorization_required"]).optional(),
+  browser: z3.strictObject({
+    name: z3.enum(["firefox", "chrome"]),
+    version: z3.string().max(80)
+  }).optional(),
+  backgroundCapture: z3.strictObject({
+    enabled: z3.boolean(),
+    permissionGranted: z3.boolean()
+  }).optional()
+});
+var requestSchema = z3.discriminatedUnion("type", [
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("highlight"),
+    payload: highlightSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("clear_highlight"),
+    payload: targetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_console"),
+    payload: diagnosticsQuerySchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_network_failures"),
+    payload: diagnosticsQuerySchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_page_status"),
+    payload: targetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("click"),
+    payload: interactionTargetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("type"),
+    payload: typeSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("press_key"),
+    payload: pressKeySchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("hover"),
+    payload: interactionTargetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("scroll"),
+    payload: scrollSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("select"),
+    payload: selectSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("focus"),
+    payload: interactionTargetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_viewport"),
+    payload: targetSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("set_viewport"),
+    payload: setViewportSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_dom"),
+    payload: domSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_element"),
+    payload: getElementSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_changed_regions"),
+    payload: changedRegionsSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("capture_region"),
+    payload: regionCaptureSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("capture_element"),
+    payload: elementCaptureSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("capture_full_page"),
+    payload: fullPageCaptureSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("capture"),
+    payload: captureSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("reload"),
+    payload: reloadSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("navigate"),
+    payload: navigateSchema
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    type: z3.literal("get_errors"),
+    payload: targetSchema
+  })
+]);
+var responseSchema = z3.discriminatedUnion("ok", [
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    ok: z3.literal(true),
+    result: z3.unknown()
+  }),
+  z3.strictObject({
+    id: z3.uuid(),
+    version: z3.literal(1),
+    ok: z3.literal(false),
+    error: z3.strictObject({
+      code: z3.string().max(80),
+      message: z3.string().max(4096),
+      stability: stabilityDiagnosticsSchema.optional()
+    })
+  })
+]);
+var helloSchema = z3.strictObject({
+  version: z3.literal(1),
+  type: z3.literal("hello"),
+  token: z3.string().regex(/^[a-f0-9]{64}$/),
+  state: stateSchema
+});
+var stateMessageSchema = z3.strictObject({
+  version: z3.literal(1),
+  type: z3.literal("state"),
+  state: stateSchema
+});
+var captureResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url(),
+  width: z3.number().int().positive(),
+  height: z3.number().int().positive(),
+  format: z3.enum(["png", "jpeg"]),
+  captureMs: z3.number().nonnegative(),
+  processingMs: z3.number().nonnegative().optional(),
+  totalMs: z3.number().nonnegative().optional(),
+  segments: z3.number().int().positive().max(64).optional(),
+  scrollRestored: z3.boolean().optional(),
+  stabilityWaitMs: z3.number().nonnegative().optional(),
+  extensionTotalMs: z3.number().nonnegative().optional(),
+  renderAppearsStable: z3.boolean().optional(),
+  stable: z3.boolean().optional(),
+  lastMutationAgoMs: z3.number().finite().nonnegative().optional(),
+  fontsReady: z3.boolean().optional(),
+  pendingImages: z3.number().int().nonnegative().optional(),
+  timeoutReached: z3.boolean().optional(),
+  dataUrl: z3.string().max(16 * 1024 * 1024)
+});
+var tabResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  url: z3.url()
+});
+var errorsResultSchema = z3.strictObject({
+  tabId: z3.number().int().nonnegative(),
+  errors: z3.array(errorSchema).max(200)
+});
+var GSError = class extends Error {
+  constructor(code, message, stability) {
+    super(message);
+    this.code = code;
+    this.stability = stability;
+  }
+};
+
+// apps/mcp-server/src/bridge/pairing.ts
+import { timingSafeEqual } from "node:crypto";
+function tokensMatch(actual, expected) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function originAllowed(origin) {
+  return origin === void 0 || /^moz-extension:\/\/[a-f0-9-]+\/?$/i.test(origin) || /^chrome-extension:\/\/[a-p]{32}\/?$/.test(origin);
+}
+
+// apps/mcp-server/src/bridge/request-router.ts
+import { randomUUID } from "node:crypto";
+var RequestRouter = class {
+  constructor(send, timeoutMs = 1e4) {
+    this.send = send;
+    this.timeoutMs = timeoutMs;
+  }
+  pending = /* @__PURE__ */ new Map();
+  request(type, payload) {
+    const request = requestSchema.parse({
+      id: randomUUID(),
+      version: 1,
+      type,
+      payload
+    });
+    return new Promise((resolve3, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(request.id);
+        reject(
+          new GSError(
+            "GS_TIMEOUT",
+            "Firefox did not respond in time. Check the extension connection."
+          )
+        );
+      }, this.timeoutMs);
+      this.pending.set(request.id, { resolve: resolve3, reject, timer });
+      try {
+        this.send(request);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(request.id);
+        reject(error);
+      }
+    });
+  }
+  receive(value) {
+    const response = responseSchema.parse(value);
+    const call = this.pending.get(response.id);
+    if (!call)
+      throw new GSError(
+        "GS_INVALID_MESSAGE",
+        "Unknown or duplicate response ID."
+      );
+    clearTimeout(call.timer);
+    this.pending.delete(response.id);
+    if (response.ok) call.resolve(response.result);
+    else
+      call.reject(
+        new GSError(
+          response.error.code,
+          response.error.message,
+          response.error.stability
+        )
+      );
+  }
+  disconnect() {
+    for (const call of this.pending.values()) {
+      clearTimeout(call.timer);
+      call.reject(
+        new GSError(
+          "GS_NOT_CONNECTED",
+          "Firefox disconnected. Wait for reconnection."
+        )
+      );
+    }
+    this.pending.clear();
+  }
+};
+
+// apps/mcp-server/src/bridge/connection-registry.ts
+function originOf(url) {
+  if (url === null) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+var BrowserConnectionRegistry = class {
+  connections = /* @__PURE__ */ new Map();
+  nextGeneration = 1;
+  nextSuffix = 1;
+  get(browser) {
+    return this.connections.get(browser);
+  }
+  byConnectionId(connectionId) {
+    for (const connection of this.connections.values())
+      if (connection.connectionId === connectionId) return connection;
+    return void 0;
+  }
+  all() {
+    return [...this.connections.values()];
+  }
+  isDuplicate(browser) {
+    return this.connections.has(browser);
+  }
+  // Returns the new connection, or undefined if `browser` already has a live
+  // connection (duplicate — caller must refuse the new socket, not replace).
+  register(browser, initialState, now = Date.now()) {
+    if (this.connections.has(browser)) return void 0;
+    const connection = {
+      connectionId: `${browser}-${this.nextSuffix++}`,
+      browser,
+      lifecycleGeneration: this.nextGeneration++,
+      connectedAt: now,
+      state: initialState,
+      lastSeenAt: now
+    };
+    this.connections.set(browser, connection);
+    return connection;
+  }
+  // Removes a connection by id, only if it is still the one currently
+  // registered for its browser family (guards against a stale remove for a
+  // connection that was already superseded).
+  remove(connectionId) {
+    for (const [browser, connection] of this.connections)
+      if (connection.connectionId === connectionId) {
+        this.connections.delete(browser);
+        return connection;
+      }
+    return void 0;
+  }
+  updateState(connectionId, state, now = Date.now()) {
+    const connection = this.byConnectionId(connectionId);
+    if (!connection) return void 0;
+    const previousTargetState = connection.state.targetState;
+    connection.state = state;
+    connection.lastSeenAt = now;
+    return { connection, previousTargetState };
+  }
+};
+function isExplicitActivation(nextTargetState, isCurrentlyActive) {
+  return nextTargetState === "authorized" && !isCurrentlyActive;
+}
+var ActiveTargetRouter = class {
+  route;
+  sequence = 0;
+  get current() {
+    return this.route;
+  }
+  activate(connection) {
+    this.route = {
+      connectionId: connection.connectionId,
+      browser: connection.browser,
+      activationSequence: ++this.sequence,
+      activatedAt: Date.now(),
+      tabId: connection.state.selectedTab,
+      origin: originOf(connection.state.url)
+    };
+    return this.route;
+  }
+  considerStateUpdate(connection) {
+    const isCurrentlyActive = this.route?.connectionId === connection.connectionId;
+    if (!isExplicitActivation(connection.state.targetState, isCurrentlyActive))
+      return this.route;
+    return this.activate(connection);
+  }
+  // Reconnect-only restoration (GAZESIGHT_MASTER_SPEC.md §142/§143): a
+  // newly-registered connection may rebind the EXISTING active route only if
+  // it is provably a resumption of the exact same logical session that
+  // already owned it — never a new activation path. This is deliberately
+  // NOT the same operation as considerStateUpdate: a hello can never create a
+  // route from nothing here (requirement 1), and it can never take a route
+  // away from a different browser family that has since become active
+  // (requirement 2 — see below), including after an MCP restart, where
+  // `this.route` starts undefined and requirement 1 alone already blocks it.
+  //
+  // Every one of the following must hold, in order, fail-closed on the first
+  // mismatch (no partial/fuzzy match — restoration is authoritative identity
+  // matching, never time-based trust):
+  //  1. A route already exists — hello alone never creates one.
+  //  2. The route belongs to the SAME browser family as this connection —
+  //     if a different browser was explicitly activated in the meantime
+  //     (including while this one was disconnected), that activation always
+  //     wins and is never reclaimed.
+  //  3. The reconnecting hello reports the target as already authorized
+  //     (the browser's own extension, e.g. Continuous Access, already
+  //     independently re-validated the tab/origin/allow-list before ever
+  //     setting this).
+  //  4. The reconnecting tab id matches the tab id recorded at the route's
+  //     last activation — never trusts "same origin, different tab".
+  //  5. The reconnecting origin matches the origin recorded at the route's
+  //     last activation, exactly (no aliasing) — an unresolvable origin on
+  //     either side is treated as incompatible, not as a pass.
+  // A stale connectionId from before a teardown can never reach this
+  // function at all (the registry only looks up currently-registered
+  // connections by id — see BrowserConnectionRegistry.byConnectionId/
+  // updateState), so a delayed message from an already-torn-down socket
+  // cannot reclaim anything.
+  considerReconnectRestore(connection) {
+    if (!this.route) return void 0;
+    if (this.route.connectionId === connection.connectionId) return this.route;
+    if (this.route.browser !== connection.browser) return this.route;
+    if (connection.state.targetState !== "authorized") return this.route;
+    if (this.route.tabId === null || this.route.tabId !== connection.state.selectedTab)
+      return this.route;
+    const origin = originOf(connection.state.url);
+    if (this.route.origin === null || origin === null || this.route.origin !== origin)
+      return this.route;
+    return this.activate(connection);
+  }
+};
+
+// apps/mcp-server/src/bridge/websocket-server.ts
+import { createServer } from "node:http";
+
+// apps/mcp-server/src/bridge/pairing-service.ts
+import { createHash, randomBytes as randomBytes2, randomInt, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
+var hash = (value) => createHash("sha256").update(value).digest("hex");
+var equalHash = (value, expected) => {
+  const actual = Buffer.from(hash(value));
+  const wanted = Buffer.from(expected);
+  return actual.length === wanted.length && timingSafeEqual2(actual, wanted);
+};
+var json = (response, status, value) => {
+  response.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+  response.end(JSON.stringify(value));
+};
+async function body(request) {
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of request) {
+    length += chunk.length;
+    if (length > 4096) throw new Error("body too large");
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function browserForOrigin(origin) {
+  if (/^moz-extension:\/\/[a-f0-9-]+\/?$/i.test(origin)) return "firefox";
+  if (/^chrome-extension:\/\/[a-p]{32}\/?$/.test(origin)) return "chrome";
+}
+var PairingService = class {
+  constructor(token, configPath, initial) {
+    this.token = token;
+    this.configPath = configPath;
+    this.pairings = initial;
+  }
+  pending = /* @__PURE__ */ new Map();
+  recent = /* @__PURE__ */ new Map();
+  pairings;
+  authenticate(credential, origin, browser) {
+    if (!origin) return false;
+    return this.pairings.some((pairing) => !pairing.revokedAt && pairing.browser === browser && pairing.origin === origin && equalHash(credential, pairing.credentialHash));
+  }
+  listPending() {
+    this.expire();
+    return [...this.pending.values()].filter((item) => item.state === "pending").map(({ id, browser, extensionId, code, createdAt, expiresAt }) => ({ id, browser, extensionId, code, createdAt, expiresAt }));
+  }
+  listPairings() {
+    return this.pairings.map(({ id, browser, extensionId, origin, createdAt, revokedAt }) => ({ id, browser, extensionId, origin, createdAt, ...revokedAt ? { revokedAt } : {} }));
+  }
+  deliveryState(id) {
+    const item = this.pending.get(id);
+    return item ? { state: item.state, redeemed: item.redeemed === true, expiresAt: item.expiresAt } : void 0;
+  }
+  approve(id, code) {
+    this.expire();
+    const item = this.pending.get(id);
+    if (!item || item.state !== "pending" || item.code !== code) return false;
+    const credential = randomBytes2(32).toString("hex");
+    const pairing = { id: crypto.randomUUID(), browser: item.browser, extensionId: item.extensionId, origin: item.origin, credentialHash: hash(credential), createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    this.pairings.push(pairing);
+    item.credential = credential;
+    item.state = "approved";
+    this.persist();
+    return true;
+  }
+  reject(id) {
+    const item = this.pending.get(id);
+    if (!item || item.state !== "pending") return false;
+    item.state = "rejected";
+    return true;
+  }
+  revoke(id) {
+    const item = this.pairings.find((pairing) => pairing.id === id && !pairing.revokedAt);
+    if (!item) return false;
+    item.revokedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.persist();
+    return true;
+  }
+  persist() {
+    if (!this.configPath) return;
+    const config = readLocalConfig(this.configPath);
+    writeLocalConfig(this.configPath, { ...config, pairings: this.pairings });
+  }
+  expire() {
+    const now = Date.now();
+    for (const item of this.pending.values()) if (item.expiresAt <= now && item.state === "pending") item.state = "rejected";
+  }
+  admin(request) {
+    return request.headers.origin === void 0 && tokensMatch(request.headers.authorization?.replace(/^Bearer /, "") ?? "", this.token);
+  }
+  async handle(request, response) {
+    const url = request.url;
+    if (!url?.startsWith("/gazesight/pairing/")) return false;
+    const origin = request.headers.origin;
+    if (origin && originAllowed(origin)) response.setHeader("Access-Control-Allow-Origin", origin);
+    response.setHeader("Vary", "Origin");
+    if (request.method === "OPTIONS" && origin && originAllowed(origin)) {
+      response.writeHead(204, { "Access-Control-Allow-Methods": "POST", "Access-Control-Allow-Headers": "content-type, authorization" }).end();
+      return true;
+    }
+    try {
+      if (url === "/gazesight/pairing/request" && request.method === "POST") {
+        const browser = origin ? browserForOrigin(origin) : void 0;
+        if (!origin || !browser) {
+          json(response, 403, { error: "ineligible_origin" });
+          return true;
+        }
+        const now = Date.now();
+        const attempts = (this.recent.get(origin) ?? []).filter((time) => now - time < 6e4);
+        if (attempts.length >= 5) {
+          json(response, 429, { error: "rate_limited" });
+          return true;
+        }
+        attempts.push(now);
+        this.recent.set(origin, attempts);
+        const value = await body(request);
+        if (value.browser !== browser || typeof value.extensionId !== "string" || value.extensionId.length > 256 || typeof value.secret !== "string" || !/^[a-f0-9]{64}$/.test(value.secret)) {
+          json(response, 400, { error: "invalid_request" });
+          return true;
+        }
+        const item = { id: crypto.randomUUID(), browser, extensionId: value.extensionId, origin, secretHash: hash(value.secret), code: String(randomInt(0, 1e6)).padStart(6, "0"), createdAt: now, expiresAt: now + 12e4, attempts: 0, state: "pending" };
+        this.pending.set(item.id, item);
+        json(response, 201, { requestId: item.id, code: item.code, expiresAt: item.expiresAt });
+        return true;
+      }
+      if (url === "/gazesight/pairing/status" && request.method === "POST") {
+        const value = await body(request);
+        const item = typeof value.requestId === "string" ? this.pending.get(value.requestId) : void 0;
+        if (!item || item.origin !== origin || typeof value.secret !== "string") {
+          json(response, 404, { state: "unavailable" });
+          return true;
+        }
+        item.attempts += 1;
+        if (item.attempts > 180 || !equalHash(value.secret, item.secretHash)) {
+          json(response, 403, { state: "rejected" });
+          return true;
+        }
+        if (Date.now() >= item.expiresAt) {
+          json(response, 410, { state: "expired" });
+          return true;
+        }
+        if (item.state === "approved" && item.credential && !item.redeemed) {
+          const pairing = this.pairings.find((value2) => value2.origin === item.origin && value2.extensionId === item.extensionId && value2.credentialHash === hash(item.credential));
+          item.redeemed = true;
+          json(response, 200, { state: "approved", credential: item.credential, pairingId: pairing?.id });
+          item.credential = void 0;
+          return true;
+        }
+        json(response, 200, { state: item.state });
+        return true;
+      }
+      if (url === "/gazesight/pairing/revoke-self" && request.method === "POST" && origin) {
+        const value = await body(request);
+        const id = typeof value.id === "string" ? value.id : "";
+        const credential = request.headers.authorization?.replace(/^Bearer /, "") ?? "";
+        const pairing = this.pairings.find((item) => item.id === id && item.origin === origin && !item.revokedAt && equalHash(credential, item.credentialHash));
+        if (!pairing) {
+          json(response, 403, { ok: false });
+          return true;
+        }
+        pairing.revokedAt = (/* @__PURE__ */ new Date()).toISOString();
+        this.persist();
+        json(response, 200, { ok: true });
+        return true;
+      }
+      if (!this.admin(request)) {
+        json(response, 404, { error: "not_found" });
+        return true;
+      }
+      if (url === "/gazesight/pairing/delivery" && request.method === "POST") {
+        const value = await body(request);
+        const delivery = typeof value.id === "string" ? this.deliveryState(value.id) : void 0;
+        json(response, delivery ? 200 : 404, delivery ?? { error: "not_found" });
+        return true;
+      }
+      if (url === "/gazesight/pairing/pending" && request.method === "GET") {
+        json(response, 200, { requests: this.listPending() });
+        return true;
+      }
+      if (url === "/gazesight/pairing/list" && request.method === "GET") {
+        json(response, 200, { pairings: this.listPairings() });
+        return true;
+      }
+      if (request.method === "POST" && ["approve", "reject", "revoke"].some((action) => url === `/gazesight/pairing/${action}`)) {
+        const value = await body(request);
+        const id = typeof value.id === "string" ? value.id : "";
+        const ok = url.endsWith("approve") ? this.approve(id, typeof value.code === "string" ? value.code : "") : url.endsWith("reject") ? this.reject(id) : this.revoke(id);
+        json(response, ok ? 200 : 404, { ok });
+        return true;
+      }
+      json(response, 404, { error: "not_found" });
+      return true;
+    } catch {
+      json(response, 400, { error: "invalid_request" });
+      return true;
+    }
+  }
+};
+
+// 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";
+  if (/^chrome-extension:\/\/[a-p]{32}\/?$/.test(origin)) return "chrome";
+  return void 0;
+}
+var Bridge = class {
+  constructor(config) {
+    this.config = config;
+    this.pairing = new PairingService(config.token, config.configPath, config.pairings ?? []);
+    const verifyClient = (info) => originAllowed(info.origin || void 0);
+    this.http = createServer(async (request, response) => {
+      response.setHeader("Cache-Control", "no-store");
+      response.setHeader("X-GazeSight-Version", VERSION);
+      if (await this.pairing.handle(request, response)) return;
+      if (request.method !== "GET" || request.url !== "/gazesight/status" || request.headers.origin !== void 0) {
+        response.writeHead(404).end();
+        return;
+      }
+      if (!tokensMatch(
+        request.headers.authorization?.replace(/^Bearer /, "") ?? "",
+        config.token
+      )) {
+        response.writeHead(401).end();
+        return;
+      }
+      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,
+      perMessageDeflate: false,
+      verifyClient
+    });
+    this.http.listen(config.port, "127.0.0.1");
+    this.server.on("connection", (socket, request) => {
+      let paired = false;
+      let connection;
+      const originBrowser = browserFromOrigin(request.headers.origin);
+      const timer = setTimeout(
+        () => socket.close(1008, "Pairing required"),
+        3e3
+      );
+      const teardown = () => {
+        clearTimeout(timer);
+        if (!connection) return;
+        this.wiring.get(connection.connectionId)?.router.disconnect();
+        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) => {
+        try {
+          if (!paired && Buffer.byteLength(bytes.toString()) > 4096)
+            throw new Error("Pairing message too large");
+          if (binary) throw new Error("Binary messages forbidden");
+          const message = JSON.parse(bytes.toString());
+          if (!paired) {
+            const hello = helloSchema.parse(message);
+            const claimedBrowser = hello.state.browser?.name;
+            if (originBrowser !== void 0 && claimedBrowser !== void 0 && originBrowser !== claimedBrowser)
+              throw new Error("Origin/browser mismatch");
+            const browser = claimedBrowser ?? originBrowser;
+            if (browser === void 0)
+              throw new Error("Unidentifiable browser");
+            if (!tokensMatch(hello.token, config.token) && !this.pairing.authenticate(hello.token, request.headers.origin, browser))
+              throw new Error("Pairing rejected");
+            if (this.registry.isDuplicate(browser))
+              throw new Error("Duplicate connection");
+            connection = this.registry.register(browser, hello.state);
+            if (!connection) throw new Error("Duplicate connection");
+            const router = new RequestRouter((req) => {
+              if (socket.readyState !== WebSocket.OPEN)
+                throw new GSError(
+                  "GS_NOT_CONNECTED",
+                  "Start Firefox and pair the GazeSight extension in its settings."
+                );
+              socket.send(JSON.stringify(req));
+            }, config.timeoutMs);
+            this.wiring.set(connection.connectionId, { socket, router });
+            this.activeTargetRouter.considerReconnectRestore(connection);
+            paired = true;
+            clearTimeout(timer);
+            socket.send(JSON.stringify({ version: 1, type: "paired" }));
+            return;
+          }
+          if (!connection) return;
+          const state = stateMessageSchema.safeParse(message);
+          if (state.success) {
+            const result = this.registry.updateState(
+              connection.connectionId,
+              state.data.state
+            );
+            if (result) this.activeTargetRouter.considerStateUpdate(result.connection);
+            return;
+          }
+          this.wiring.get(connection.connectionId)?.router.receive(message);
+        } catch {
+          socket.close(1008, "GS_INVALID_MESSAGE");
+        }
+      });
+      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;
+  pairing;
+  // Resolves the connection currently backing the global active target, or
+  // undefined if no browser is active (nothing selected yet, or the
+  // previously active browser disconnected — no automatic fallback).
+  resolveActive() {
+    const route = this.activeTargetRouter.current;
+    if (!route) return void 0;
+    return this.registry.byConnectionId(route.connectionId);
+  }
+  resolveActiveWiring() {
+    const route = this.activeTargetRouter.current;
+    if (!route) return void 0;
+    return this.wiring.get(route.connectionId);
+  }
+  get connected() {
+    const wiring = this.resolveActiveWiring();
+    return wiring?.socket.readyState === WebSocket.OPEN;
+  }
+  get state() {
+    return this.resolveActive()?.state ?? EMPTY_STATE;
+  }
+  get port() {
+    return this.config.port;
+  }
+  // Same call shape as before (`bridge.router.request(type, payload)`) so
+  // server.ts and its 25 tools need no changes at all — routing to whichever
+  // browser is active is entirely internal to Bridge.
+  router = {
+    request: async (type, payload) => {
+      const route = this.activeTargetRouter.current;
+      if (!route)
+        throw new GSError(
+          "GS_NOT_CONNECTED",
+          "Start Firefox and pair the GazeSight extension in its settings."
+        );
+      const wiring = this.wiring.get(route.connectionId);
+      if (!wiring || wiring.socket.readyState !== WebSocket.OPEN)
+        throw new GSError(
+          "GS_TARGET_UNAVAILABLE",
+          "The active browser disconnected. Select the target again in that browser, or switch to another browser with its own 'Use this tab'."
+        );
+      return wiring.router.request(type, payload);
+    }
+  };
+  status() {
+    const active = this.resolveActive();
+    const connectedBrowsers = Object.fromEntries(
+      ["firefox", "chrome"].map((browser) => [
+        browser,
+        this.registry.get(browser) !== void 0 && this.wiring.get(this.registry.get(browser).connectionId)?.socket.readyState === WebSocket.OPEN
+      ])
+    );
+    const authorizedTargets = Object.fromEntries(
+      ["firefox", "chrome"].map((browser) => {
+        const connection = this.registry.get(browser);
+        return [
+          browser,
+          connection?.state.targetState === "authorized" ? { url: connection.state.url } : null
+        ];
+      })
+    );
+    return {
+      connected: this.connected,
+      paired: this.connected,
+      authorizedPairings: this.pairing.listPairings().filter((item) => !item.revokedAt).length,
+      targetState: this.state.targetState ?? "none",
+      tabId: this.state.selectedTab,
+      bridge: { port: this.port },
+      ...this.state,
+      connectedBrowsers,
+      authorizedTargets,
+      activeTarget: active ? { browser: active.browser, url: active.state.url } : null
+    };
+  }
+  async ready() {
+    if (this.listenError) throw this.listenError;
+    if (this.server.address()) return;
+    await new Promise((resolve3, reject) => {
+      this.server.once("listening", resolve3);
+      const onError = () => reject(this.listenError);
+      this.server.once("error", onError);
+      this.http.once("error", onError);
+    });
+  }
+  async close() {
+    clearInterval(this.heartbeat);
+    for (const wiring of this.wiring.values()) wiring.router.disconnect();
+    for (const client of this.server.clients) client.terminate();
+    await new Promise((resolve3) => this.server.close(() => resolve3()));
+    await new Promise((resolve3) => this.http.close(() => resolve3()));
+  }
+};
+
+// apps/cli/src/pair.ts
+var headers = (token) => ({ Authorization: `Bearer ${token}`, "Content-Type": "application/json" });
+async function admin(port, token, path, method = "GET", value) {
+  return fetch(`http://127.0.0.1:${port}/gazesight/pairing/${path}`, {
+    method,
+    headers: headers(token),
+    body: value === void 0 ? void 0 : JSON.stringify(value),
+    signal: AbortSignal.timeout(1500)
+  });
+}
+async function pairingFlow(config, configPath, revoke) {
+  let bridge;
+  try {
+    const check = await admin(config.port, config.token, "list").catch(() => void 0);
+    if (!check?.ok) {
+      bridge = new Bridge({ ...config, configPath, timeoutMs: 1e4 });
+      await bridge.ready();
+    }
+    if (revoke) {
+      const current = await admin(config.port, config.token, "list");
+      if (!current.ok) throw new Error("Pairing administration unavailable.");
+      const pairings = (await current.json()).pairings;
+      const ids = revoke === "all" ? pairings.filter((item) => !item.revokedAt).map((item) => item.id) : [revoke];
+      let count = 0;
+      for (const id of ids) if ((await admin(config.port, config.token, "revoke", "POST", { id })).ok) count++;
+      console.log(`Revoked pairings: ${count}. Extensions must pair again.`);
+      return;
+    }
+    if (!process.stdin.isTTY) {
+      console.log("Pairing listener ready. Open the GazeSight extension and click Connect to GazeSight.");
+      return;
+    }
+    console.log("Pairing listener ready. Open the GazeSight browser extension and click Connect to GazeSight.");
+    console.log("Waiting for a request (Ctrl+C to stop)\u2026");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      for (; ; ) {
+        const response = await admin(config.port, config.token, "pending");
+        if (!response.ok) throw new Error("Pairing administration unavailable.");
+        const requests = (await response.json()).requests;
+        const request = requests[0];
+        if (!request) {
+          await new Promise((resolve3) => setTimeout(resolve3, 500));
+          continue;
+        }
+        console.log(`Pairing request: ${request.browser} \xB7 verification code ${request.code}`);
+        const answer = (await rl.question("Approve this matching request? [y/N] ")).trim().toLowerCase();
+        const approved = answer === "y" || answer === "yes";
+        const result = await admin(config.port, config.token, approved ? "approve" : "reject", "POST", { id: request.id, code: request.code });
+        if (!result.ok) throw new Error("The pairing request expired or was already used.");
+        if (approved) {
+          const deadline = Date.now() + 5e3;
+          let delivered = false;
+          while (Date.now() < deadline) {
+            const delivery = await admin(config.port, config.token, "delivery", "POST", { id: request.id });
+            if (delivery.ok && (await delivery.json()).redeemed) {
+              delivered = true;
+              break;
+            }
+            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.");
+        } else console.log("Pairing rejected.");
+        return;
+      }
+    } finally {
+      rl.close();
+    }
+  } finally {
+    if (bridge) await bridge.close();
+  }
+}
+
+// apps/cli/src/agent-config.ts
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { basename, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+function parseKnownGazeSightArgs(command, argsText) {
+  const cli = argsText.match(/^(.*?[\\/]dist[\\/]cli[\\/]index\.js)\s+mcp(?:\s+--config\s+(.+))?$/i);
+  if (cli) return [cli[1], "mcp", ...cli[2] ? ["--config", cli[2]] : []];
+  if (/^npx(?:\.cmd|\.exe)?$/i.test(basename(command))) {
+    const npx = argsText.match(/^(.*?)\b(gazesight(?:@\d+\.\d+\.\d+)?)\s+mcp(?:\s+--config\s+(.+))?$/i);
+    if (npx) {
+      const prefix = npx[1].trim().split(/\s+/).filter(Boolean);
+      return [...prefix, npx[2], "mcp", ...npx[3] ? ["--config", npx[3]] : []];
+    }
+  }
+  if (/^gazesight(?:-mcp)?(?:\.cmd|\.exe)?$/i.test(basename(command))) {
+    const direct = argsText.match(/^mcp(?:\s+--config\s+(.+))?$/i);
+    if (direct) return ["mcp", ...direct[1] ? ["--config", direct[1]] : []];
+  }
+  return void 0;
+}
+function normalize(value) {
+  const normalized = value.trim().replace(/^['"]|['"]$/g, "").replaceAll("\\", "/");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function parseScope(output) {
+  const value = output.match(/^\s*Scope:\s*(.+)$/im)?.[1]?.toLowerCase() ?? "user";
+  if (value.includes("project")) return "project";
+  if (value.includes("local")) return "local";
+  return "user";
+}
+function versionFromPackageRoot(argsText) {
+  const normalized = argsText.replaceAll("\\", "/");
+  const marker = "/dist/cli/index.js";
+  const markerIndex = normalized.toLowerCase().indexOf(marker);
+  if (markerIndex < 0) return void 0;
+  const root2 = argsText.slice(0, markerIndex);
+  const packagePath = resolve(root2, "package.json");
+  if (!existsSync(packagePath)) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync2(packagePath, "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseRegisteredConfig(agent, output) {
+  const command = output.match(/^\s*(?:Command|command):\s*(.+)$/im)?.[1]?.trim();
+  const argsText = output.match(/^\s*(?:Args|args):\s*(.*)$/im)?.[1]?.trim();
+  if (!command || argsText === void 0) return void 0;
+  const combined = `${command} ${argsText}`;
+  const explicitVersion = combined.match(/(?:^|\s)gazesight@(\d+\.\d+\.\d+)(?:\s|$)/i)?.[1];
+  const commandName = basename(normalize(command));
+  const relatedToGazeSight = /(?:^|[\\/])gazesight(?:-mcp)?(?:\.cmd|\.exe)?$/i.test(command) || /(?:^|[\\/])dist[\\/]cli[\\/]index\.js(?:\s|$)/i.test(argsText) || /(?:^|\s)gazesight(?:@\d+\.\d+\.\d+)?(?:\s|$)/i.test(argsText) || ["npx", "npx.cmd", "npx.exe"].includes(commandName) && /gazesight/i.test(argsText);
+  return {
+    command,
+    argsText,
+    args: parseKnownGazeSightArgs(command, argsText),
+    scope: agent === "claude" ? parseScope(output) : "user",
+    version: explicitVersion ?? versionFromPackageRoot(argsText),
+    obsoleteNpxCache: /(?:^|[\\/])_npx(?:[\\/]|$)/i.test(combined),
+    relatedToGazeSight
+  };
+}
+function configurationsMatch(existing, proposed) {
+  return !existing.obsoleteNpxCache && normalize(existing.command) === normalize(proposed.command) && normalize(existing.argsText) === normalize(proposed.args.join(" ")) && (!existing.version || existing.version === proposed.version);
+}
+function display(config) {
+  if ("argsText" in config)
+    return `command=${JSON.stringify(config.command)} args=${JSON.stringify(config.argsText)}${config.version ? ` version=${config.version}` : " version=unknown"} scope=${config.scope}`;
+  return `command=${JSON.stringify(config.command)} args=${JSON.stringify(config.args.join(" "))} version=${config.version}`;
+}
+function failure(result) {
+  return (result.stderr || result.stdout || "unknown error").trim().split(/\r?\n/)[0];
+}
+function configureAgent(agent, binaryPath, proposed, allowUpdate, spawn = (command, commandArgs) => spawnSync(command, commandArgs, { encoding: "utf8", windowsHide: true })) {
+  const get = spawn(binaryPath, ["mcp", "get", "gazesight"]);
+  const existing = get.status === 0 ? parseRegisteredConfig(agent, get.stdout) : void 0;
+  if (!existing) {
+    const addArgs2 = [
+      "mcp",
+      "add",
+      "gazesight",
+      ...agent === "claude" ? ["--scope", "user"] : [],
+      "--",
+      proposed.command,
+      ...proposed.args
+    ];
+    const add2 = spawn(binaryPath, addArgs2);
+    return add2.status === 0 ? { ok: true, state: "configured", message: "Configured." } : { ok: false, state: "failed", message: `Failed: ${failure(add2)}` };
+  }
+  if (!existing.relatedToGazeSight)
+    return {
+      ok: false,
+      state: "conflict",
+      message: `Refusing to overwrite an unrelated MCP entry named gazesight. Existing: ${display(existing)}`
+    };
+  if (!existing.args && allowUpdate)
+    return {
+      ok: false,
+      state: "conflict",
+      message: `Refusing an update because the existing GazeSight arguments cannot be reconstructed safely for rollback. Existing: ${display(existing)}`
+    };
+  if (configurationsMatch(existing, proposed))
+    return { ok: true, state: "identical", message: "Already configured (identical; unchanged)." };
+  const comparison = `Configuration differs.
+  Existing: ${display(existing)}
+  Proposed: ${display(proposed)}`;
+  if (!allowUpdate)
+    return {
+      ok: false,
+      state: "outdated",
+      message: `${comparison}
+  Re-run setup with --update to replace only this GazeSight entry while preserving its ${existing.scope} scope.`
+    };
+  const removeArgs = [
+    "mcp",
+    "remove",
+    "gazesight",
+    ...agent === "claude" ? ["--scope", existing.scope] : []
+  ];
+  const remove = spawn(binaryPath, removeArgs);
+  if (remove.status !== 0)
+    return { ok: false, state: "failed", message: `${comparison}
+  Update failed before replacement: ${failure(remove)}` };
+  const addArgs = [
+    "mcp",
+    "add",
+    "gazesight",
+    ...agent === "claude" ? ["--scope", existing.scope] : [],
+    "--",
+    proposed.command,
+    ...proposed.args
+  ];
+  const add = spawn(binaryPath, addArgs);
+  if (add.status === 0)
+    return { ok: true, state: "updated", message: `${comparison}
+  Updated safely.` };
+  const restoreArgs = [
+    "mcp",
+    "add",
+    "gazesight",
+    ...agent === "claude" ? ["--scope", existing.scope] : [],
+    "--",
+    existing.command,
+    ...existing.args
+  ];
+  const restore = spawn(binaryPath, restoreArgs);
+  return {
+    ok: false,
+    state: "failed",
+    message: restore.status === 0 ? `${comparison}
+  Replacement failed: ${failure(add)}. The previous entry was restored.` : `${comparison}
+  Replacement failed: ${failure(add)}. Automatic restoration also failed: ${failure(restore)}. Follow the displayed existing configuration to restore it manually.`
+  };
+}
+
 // 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);
@@ -162,13 +1584,13 @@ 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;
+      if (existsSync2(candidate)) return candidate;
     }
   return void 0;
 }
 async function promptClientChoice() {
   if (!process.stdin.isTTY) return ["claude", "codex"];
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
   try {
     const answer = (await rl.question(
       "Configure MCP for:\n  1) Claude Code\n  2) Codex\n  3) Both\nEnter choice [1-3] (default 3): "
@@ -180,38 +1602,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") {
@@ -221,23 +1613,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"].includes(args[0]))
+    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"].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"}`
@@ -262,6 +1662,15 @@ 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
+      };
       for (const agent of chosen) {
         const label = agent === "claude" ? "Claude Code" : "Codex";
         const binaryPath = detectOnPath(agent);
@@ -269,7 +1678,7 @@ Agent guidance: ${config.agentGuidance.enabled ? "Enabled" : "Disabled"}${config
           console.log(`${label}: not detected on PATH \u2014 configure manually below.`);
           continue;
         }
-        const result2 = configureAgent(agent, binaryPath, serverArgs);
+        const result2 = configureAgent(agent, binaryPath, proposed, args.includes("--update"));
         console.log(`${label}: ${result2.ok ? "PASS" : "FAIL"} \u2014 ${result2.message}`);
       }
       const undetected = explicit ? chosen.filter((agent) => !detectOnPath(agent)) : ["claude", "codex"];
@@ -291,21 +1700,24 @@ args = ${JSON.stringify(server.args)}`
         }
       }
       console.log(
-        `Pairing: Firefox options > Import local configuration > ${configPath} > Enregistrer. The token stays in the private file.
-Chrome (manual install, not yet on the Chrome Web Store): open chrome://extensions, enable Developer mode, "Load unpacked", select ${join2(root, "chrome")}, then Options > Import local configuration.
-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.
-Start your coding agent, open your local app in your browser, click GazeSight, then run gazesight doctor.`
+        `Open your GazeSight browser extension and click Connect to GazeSight.
+Firefox: install or update the signed extension from the official listing \u2014 https://addons.mozilla.org/addon/6a2319d4fa544731884d/ (matches gazesight@${VERSION}).
+Chrome (manual install, not yet on the Chrome Web Store): open chrome://extensions, enable Developer mode, "Load unpacked", select ${join2(root, "chrome")}.
+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);
+    }
+    if (args[0] === "pair") {
+      await pairingFlow(config, configPath, option("--revoke"));
     }
-    const result = await probe(config.port, config.token);
+    const result = args[0] === "pair" ? void 0 : await probe(config.port, config.token);
     const rows = diagnosticRows(
-      result.status,
-      result.reachable,
-      result.authenticated
+      result?.status,
+      result?.reachable ?? false,
+      result?.authenticated ?? false
     );
-    for (const row of rows)
+    if (args[0] !== "pair") for (const row of rows)
       console.log(
         "status" in row ? `${row.name}: ${row.status}` : `${row.name}: ${row.pass ? "PASS" : `FAIL \u2014 ${row.action}`}`
       );