local-operator-ui 0.22.2 → 0.22.4

package/out/main/index.js

@@ -13,6 +13,7 @@ const os = require("node:os");
 const node_util = require("node:util");
 const dotenv = require("dotenv");
 const electronLog = require("electron-log");
+const node_http = require("node:http");
 const https = require("node:https");
 const electronUpdater = require("electron-updater");
 function _interopNamespaceDefault(e) {
@@ -1274,7 +1275,7 @@ const DESKTOP_STREAM_DETAIL = {
   /** The IPC subscribe itself rejected before a stream existed. */
   openFailed: "The event stream could not be opened.",
   /** A backend answered and refused this app's bearer (typically 401/403). */
-  refused: (status) => `The event stream was refused (${status}).`,
+  refused: (status2) => `The event stream was refused (${status2}).`,
   /**
    * The same refusal where no status reached the caller.
    *
@@ -3998,8 +3999,3459 @@ class BackendInstaller {
     }
   }
 }
+const PRIVATE_FILE_MODE = 384;
+const PRIVATE_DIR_MODE = 448;
+function writeJsonAtomic(path2, value) {
+  try {
+    fs.mkdirSync(path$1.dirname(path2), { recursive: true, mode: PRIVATE_DIR_MODE });
+    const staged = `${path2}.${process.pid}.tmp`;
+    fs.writeFileSync(staged, `${JSON.stringify(value, null, 2)}
+`, {
+      mode: PRIVATE_FILE_MODE
+    });
+    fs.renameSync(staged, path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readJson(path2) {
+  try {
+    return JSON.parse(fs.readFileSync(path2, "utf8"));
+  } catch {
+    return null;
+  }
+}
+class BridgeCommandError extends Error {
+  constructor(code, message, data = {}) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+function errorData(error) {
+  return error instanceof BridgeCommandError ? error.data : {};
+}
+const CDP_DEADLINE_MS = 15e3;
+const CDP_ATTACH_DEADLINE_MS = 5e3;
+const CHROME_API_DEADLINE_MS = 5e3;
+const SCRIPTING_DEADLINE_MS = 15e3;
+function deadline(op, ms, what) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new BridgeCommandError("internal", `${what} did not respond within ${ms}ms`, {
+          stalled: what
+        })
+      );
+    }, ms);
+    op.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+function nextSequence(queue) {
+  return (queue ?? []).reduce(
+    (highest, entry) => Math.max(highest, entry.sequence),
+    0
+  ) + 1;
+}
+const SCROLL_DIRECTIONS = /* @__PURE__ */ new Set([
+  "top",
+  "bottom",
+  "up",
+  "down",
+  "left",
+  "right"
+]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const WEB_CONTENTS_DEADLINE_MS = CHROME_API_DEADLINE_MS;
+const ONCE_GRANT_TTL_MS = 10 * 6e4;
+function receiptKey(origin, requester) {
+  return `${origin}
+${requester}`;
+}
+const TOMBSTONE_CAP = 8;
+function activeRequest(record, now) {
+  if (!record) return void 0;
+  return now < record.expiresAt ? record : void 0;
+}
+function consumableGrant(grants, origin, requester, now) {
+  const grant = grants?.[origin];
+  if (!grant || now >= grant.expiresAt) return void 0;
+  if (!requester || grant.requester !== requester) return void 0;
+  return grant;
+}
+function accessState(record, tombstones, storedAllowed, onceGrant, origin, requester, now) {
+  if (storedAllowed || onceGrant) return "allowed";
+  const live = activeRequest(record, now);
+  if (live && live.origin === origin && live.requester === requester) {
+    if (!live.decision) return "pending";
+    return live.decision === "deny" ? "denied" : "allowed";
+  }
+  const tomb = tombstones?.[receiptKey(origin, requester)];
+  if (tomb && now < tomb.expiresAt) return "superseded";
+  return "none";
+}
+function tombstoneFor(record) {
+  return { origin: record.origin, requester: record.requester, expiresAt: record.expiresAt };
+}
+function safeHttpUrl(raw) {
+  if (typeof raw !== "string") throw new Error("URL is required");
+  const parsed = new URL(raw);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("only http:// and https:// can be opened");
+  }
+  if (parsed.hostname === "127.0.0.1") {
+    const authority = raw.match(/^https?:\/\/([^/?#]+)/i)?.[1] ?? "";
+    const rawHost = authority.startsWith("[") ? authority.slice(0, authority.indexOf("]") + 1) : authority.split(":", 1)[0];
+    if (rawHost !== "127.0.0.1") throw new Error("IPv4 loopback must use 127.0.0.1 exactly");
+  }
+  return parsed;
+}
+function isLoopbackHost(url) {
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+}
+function displayAuthority(url) {
+  return url.host;
+}
+let pslRules = null;
+function configurePslRules(rules2) {
+  pslRules = rules2 ? new Set(rules2.split("\n")) : null;
+}
+function domainScopeAvailable() {
+  return pslRules !== null;
+}
+function rules() {
+  return pslRules ?? /* @__PURE__ */ new Set();
+}
+function isIpLiteral(hostname) {
+  return hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}
+function registrableDomain(url) {
+  const hostname = url.hostname;
+  if (!hostname || hostname.endsWith(".") || isIpLiteral(hostname)) return null;
+  const labels = hostname.split(".");
+  if (labels.length < 2 || labels.some((label) => !label)) return null;
+  const table = rules();
+  if (table.size === 0) return null;
+  let suffixLabels = 1;
+  for (let index = labels.length - 1; index >= 0; index -= 1) {
+    const candidate = labels.slice(index).join(".");
+    const matched = labels.length - index;
+    if (table.has(`!${candidate}`)) {
+      suffixLabels = matched - 1;
+      break;
+    }
+    if (table.has(candidate)) suffixLabels = Math.max(suffixLabels, matched);
+    if (index > 0 && table.has(`*.${candidate}`)) suffixLabels = Math.max(suffixLabels, matched + 1);
+  }
+  if (labels.length <= suffixLabels) return null;
+  return labels.slice(labels.length - suffixLabels - 1).join(".");
+}
+function broadGrantFor(url) {
+  if (isLoopbackHost(url)) return { scope: "host", key: url.hostname };
+  const domain = registrableDomain(url);
+  return domain ? { scope: "domain", key: domain } : null;
+}
+function validSiteGrantSchema(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && value.version === 1 && !!value.grants && typeof value.grants === "object" && !Array.isArray(value.grants);
+}
+function siteGrantScope(grant, scope) {
+  return grant?.scope === scope && typeof grant.createdAt === "number";
+}
+function matchingGrantScope(origins, hostGrants, url, siteGrants) {
+  if (origins[url.origin] === "allow") return "origin";
+  if (validSiteGrantSchema(siteGrants)) {
+    if (isLoopbackHost(url)) {
+      if (siteGrantScope(siteGrants.grants[url.hostname], "host")) return "host";
+    } else {
+      const domain = registrableDomain(url);
+      if (domain && siteGrantScope(siteGrants.grants[domain], "domain")) return "domain";
+    }
+  }
+  return null;
+}
+function storedOriginAllowed(origins, url, hostGrants, siteGrants) {
+  return matchingGrantScope(origins, hostGrants, url, siteGrants) !== null;
+}
+const ACCESS_QUEUE_CAP = 16;
+const ACCESS_RESULT_CAP = 32;
+const ACCESS_REQUEST_TTL_MS = 10 * 6e4;
+const IN_COMMAND_TTL_MS = 6e4;
+const ACCESS_RESULT_TTL_MS = 15 * 6e4;
+function resultKey(entryId, requester) {
+  return `${entryId}
+${requester}`;
+}
+function liveQueue(queue, now) {
+  return (queue ?? []).filter((entry) => now < entry.expiresAt).sort((a, b) => a.sequence - b.sequence);
+}
+function cleanResults(results, now) {
+  return Object.fromEntries(
+    Object.entries(results ?? {}).filter(([, receipt]) => now < receipt.expiresAt).sort((a, b) => b[1].decidedAt - a[1].decidedAt).slice(0, ACCESS_RESULT_CAP)
+  );
+}
+function findPending(queue, origin, requester, kind, now = Date.now()) {
+  return liveQueue(queue, now).find(
+    (entry) => entry.origin === origin && entry.requester === requester && (!kind || entry.kind === kind)
+  );
+}
+function newEntry(origin, displayAuthority2, requester, kind, now, sequence, commandId, entryId, broad) {
+  return {
+    // `||`, not a default parameter: a default fires only on `undefined`, so a
+    // legacy pendingOrigin record carrying `promptId: ""` would mint a live
+    // entry with an empty id. An empty id reads as "no generation" in the ack
+    // latch and would be swallowed as the previous decision's own echo.
+    // Unreachable today (every writer minted a UUID) and defensive only (A12).
+    entryId: crypto.randomUUID().replaceAll("-", ""),
+    origin,
+    displayAuthority: displayAuthority2,
+    requester,
+    kind,
+    requestedAt: now,
+    expiresAt: now + (kind === "async" ? ACCESS_REQUEST_TTL_MS : IN_COMMAND_TTL_MS),
+    sequence,
+    ...commandId ? { commandId } : {},
+    ...broad ? { broad } : {}
+  };
+}
+function receiptFor(entry, state, now) {
+  return {
+    entryId: entry.entryId,
+    origin: entry.origin,
+    requester: entry.requester,
+    state,
+    decidedAt: now,
+    expiresAt: now + ACCESS_RESULT_TTL_MS
+  };
+}
+function receiptForRequester(results, origin, requester, now) {
+  return Object.values(cleanResults(results, now)).filter((receipt) => receipt.origin === origin && receipt.requester === requester).sort((a, b) => b.decidedAt - a.decidedAt)[0];
+}
+const APPROVALS_FILENAME = "approvals.json";
+function emptyStore() {
+  return {
+    version: 1,
+    origins: {},
+    siteGrants: { version: 1, grants: {} },
+    records: []
+  };
+}
+class ApprovalStore {
+  path;
+  now;
+  onChanged;
+  log;
+  store;
+  /** The live pending entries, FIFO. In-memory: a pending prompt that outlived
+   * the app would be a prompt about a navigation nobody remembers requesting. */
+  queue = [];
+  /** Decisions, keyed `entryId\nrequester` (see `resultKey`). */
+  results = {};
+  /** Unspent "Allow once" grants, keyed by origin. */
+  onceGrants = {};
+  /** Receipts for displaced requesters (see `access-flow.ts`). */
+  tombstones = {};
+  constructor(options) {
+    this.path = path$1.join(options.dir, APPROVALS_FILENAME);
+    this.now = options.now ?? Date.now;
+    this.onChanged = options.onChanged ?? (() => {
+    });
+    this.log = options.log ?? (() => {
+    });
+    const loaded = readJson(this.path);
+    const fresh = emptyStore();
+    this.store = loaded && loaded.version === 1 ? {
+      ...fresh,
+      ...loaded,
+      // The three mutable containers are taken from the FRESH store when
+      // the file did not carry them, never shared with another instance.
+      origins: loaded.origins ?? fresh.origins,
+      siteGrants: loaded.siteGrants ?? fresh.siteGrants,
+      records: loaded.records ?? fresh.records
+    } : fresh;
+  }
+  // ---- the gate ------------------------------------------------------------
+  /** Whether the agent may reach this URL: an exact-origin allow, a broad grant,
+   * or nothing. A persisted DENY for the exact origin wins over any broader
+   * grant: the user's most specific statement about a site is the one that
+   * counts, and a deny that a domain grant could override would make the deny
+   * button a lie.
+   *
+   * The signature is the VENDORED one — `(origins, url, hostGrants?, siteGrants?)`
+   * — and the `hostGrants` slot is passed `undefined` for the same reason
+   * `grantScopeFor` does: that slot reads the extension's legacy 0.1.4-0.1.7
+   * loopback shape, which this host never wrote. Passing `siteGrants` there
+   * instead compiles (the slot is `unknown` and optional) and silently drops
+   * every broad grant, which is why the call spells the order out. */
+  originAllowed(url) {
+    if (this.store.origins[url.origin] === "deny") return false;
+    return storedOriginAllowed(
+      this.store.origins,
+      url,
+      void 0,
+      this.store.siteGrants
+    );
+  }
+  /** Why the URL is refused, for the refusal's `data` — a sentence the model can
+   * use rather than a bare boolean. */
+  refusalReason(url) {
+    return this.store.origins[url.origin] === "deny" ? "denied" : "unapproved";
+  }
+  /**
+   * The admission decision for a top-level navigation, made ONCE at command
+   * entry.
+   *
+   * The "once" is load-bearing (the extension's round-1 M1): a grant consumed
+   * here is already spent, and re-consulting the grant map later in the same
+   * command would let the 10-minute TTL lapse between entry and navigation,
+   * turning a granted navigation back into a prompt the agent thinks it already
+   * passed.
+   *
+   * An unapproved origin is refused EARLY with `origin_not_allowed` — never by
+   * blocking the navigation on a prompt. That is the design's three-step dance:
+   * the agent gets a typed failure it can narrate, then runs
+   * `request_access` → tells the user → `await_access`.
+   */
+  ensureTopLevelAccess(url, requester) {
+    if (this.originAllowed(url)) return { allowed: true, viaOnceGrant: false };
+    const grant = consumableGrant(
+      this.onceGrants,
+      url.origin,
+      requester,
+      this.now()
+    );
+    if (grant) {
+      delete this.onceGrants[url.origin];
+      this.persistIfChanged();
+      return { allowed: true, viaOnceGrant: true };
+    }
+    throw new BridgeCommandError(
+      "origin_not_allowed",
+      `the user has not approved ${url.origin} for agent access`,
+      {
+        origin: url.origin,
+        authority: displayAuthority(url),
+        reason: this.refusalReason(url)
+      }
+    );
+  }
+  // ---- request_access / await_access / cancel_access -----------------------
+  /** The live entry for an exact origin, if any: what a consent surface renders. */
+  pendingEntry() {
+    return liveQueue(this.queue, this.now())[0];
+  }
+  /** Every live pending entry, in FIFO order (the cap is small, so a list is
+   * cheap and the surface decides what to show). */
+  pendingEntries() {
+    return liveQueue(this.queue, this.now());
+  }
+  /**
+   * Raise a request, or report that one already covers this caller.
+   *
+   * The rules are `vendor/driver/access-flow.ts`'s, applied to the queue: a repeat
+   * request for the same origin by the same requester is idempotent with its
+   * original TTL, a request for a different origin REPLACES the live one (with
+   * a tombstone for the displaced requester), and a live deny receipt answers
+   * "denied" without re-prompting until its cool-down expires.
+   */
+  requestAccess(rawUrl, requester, kind = "async", commandId) {
+    const url = safeHttpUrl(rawUrl);
+    const now = this.now();
+    if (this.originAllowed(url)) {
+      return { origin: url.origin, state: "allowed" };
+    }
+    const existing = findPending(this.queue, url.origin, requester, kind, now);
+    if (existing) {
+      return this.entryResponse(existing, "pending");
+    }
+    const receipt = receiptForRequester(
+      this.results,
+      url.origin,
+      requester,
+      now
+    );
+    if (receipt && receipt.state !== "superseded") {
+      const state = receipt.state === "denied" ? "denied" : "allowed";
+      return { origin: url.origin, state, entry_id: receipt.entryId };
+    }
+    this.sweep(now);
+    if (liveQueue(this.queue, now).length >= ACCESS_QUEUE_CAP) {
+      throw new BridgeCommandError(
+        "access_queue_full",
+        `site approval queue is full with ${liveQueue(this.queue, now).length} pending requests`,
+        { pending_count: liveQueue(this.queue, now).length }
+      );
+    }
+    this.displaceLive(now);
+    const entry = newEntry(
+      url.origin,
+      displayAuthority(url),
+      requester,
+      kind,
+      now,
+      nextSequence(this.queue),
+      commandId,
+      void 0,
+      broadGrantFor(url)
+    );
+    this.queue.push(entry);
+    this.onChanged();
+    this.log(
+      `[browser] ${requester} is asking for access to ${url.origin} (${this.pendingEntries().length} pending)`
+    );
+    return this.entryResponse(entry, "pending");
+  }
+  entryResponse(entry, state) {
+    return {
+      origin: entry.origin,
+      state,
+      entry_id: entry.entryId,
+      authority: entry.displayAuthority,
+      expires_at: entry.expiresAt,
+      ...entry.broad ? { broad: entry.broad } : {}
+    };
+  }
+  /** What `await_access` answers, WITHOUT waiting (the loop is in
+   * `awaitAccess`). */
+  accessStateFor(rawUrl, requester) {
+    const url = safeHttpUrl(rawUrl);
+    const now = this.now();
+    const entry = findPending(
+      this.queue,
+      url.origin,
+      requester,
+      void 0,
+      now
+    );
+    const state = accessState(
+      entry ? {
+        origin: entry.origin,
+        hostname: entry.displayAuthority,
+        requester: entry.requester,
+        requestedAt: entry.requestedAt,
+        expiresAt: entry.expiresAt,
+        ...this.decisionFor(entry) ? { decision: this.decisionFor(entry) } : {}
+      } : void 0,
+      this.tombstones,
+      this.originAllowed(url),
+      !!consumableGrant(this.onceGrants, url.origin, requester, now),
+      url.origin,
+      requester,
+      now
+    );
+    return {
+      origin: url.origin,
+      state,
+      ...entry ? { entry_id: entry.entryId } : {}
+    };
+  }
+  /** The caller's own exact-origin pending entry, removed. Only this
+   * requester's own entry: a cancel must not let one session dismiss another's
+   * prompt. */
+  cancelAccess(rawUrl, requester) {
+    const url = safeHttpUrl(rawUrl);
+    const now = this.now();
+    const index = this.queue.findIndex(
+      (entry2) => entry2.origin === url.origin && entry2.requester === requester
+    );
+    if (index < 0)
+      return { origin: url.origin, state: "none" };
+    const [entry] = this.queue.splice(index, 1);
+    if (entry) {
+      this.results[resultKey(entry.entryId, entry.requester)] = receiptFor(
+        entry,
+        "cancelled",
+        now
+      );
+    }
+    this.onChanged();
+    return { origin: url.origin, state: "cancelled" };
+  }
+  /**
+   * Answer the pending prompt: the user's decision, applied.
+   *
+   * Reached from the renderer IPC (a chrome band will call it; nothing else
+   * can, and the IPC handler checks the sender). `entryId` names which pending
+   * entry is being answered, so an answer that arrives after the queue moved on
+   * fails rather than granting whatever is pending now.
+   */
+  respond(entryId, decision, requester = "") {
+    const entry = this.queue.find((candidate) => candidate.entryId === entryId);
+    if (!entry) {
+      throw new BridgeCommandError(
+        "internal",
+        "that site approval request is no longer pending"
+      );
+    }
+    const now = this.now();
+    this.queue = this.queue.filter(
+      (candidate) => candidate.entryId !== entryId
+    );
+    if (decision === "once") {
+      this.onceGrants[entry.origin] = {
+        expiresAt: now + ONCE_GRANT_TTL_MS,
+        requester: entry.requester,
+        ...entry.commandId ? { handoff: entry.commandId } : {}
+      };
+      this.results[resultKey(entry.entryId, entry.requester)] = receiptFor(
+        entry,
+        "allowed",
+        now
+      );
+      this.persist();
+      this.onChanged();
+      return { origin: entry.origin, state: "allowed", scope: "once" };
+    }
+    if (decision === "deny") {
+      this.store.origins[entry.origin] = "deny";
+      this.store.records.push({
+        origin: entry.origin,
+        scope: "deny",
+        requester: requester || entry.requester,
+        grantedAt: now
+      });
+      this.results[resultKey(entry.entryId, entry.requester)] = receiptFor(
+        entry,
+        "denied",
+        now
+      );
+      this.persist();
+      this.onChanged();
+      return { origin: entry.origin, state: "denied", scope: "deny" };
+    }
+    if (decision === "site") {
+      this.store.origins[entry.origin] = "allow";
+      this.store.records.push({
+        origin: entry.origin,
+        scope: "origin",
+        requester: requester || entry.requester,
+        grantedAt: now
+      });
+    } else {
+      const broad = entry.broad;
+      if (!broad) {
+        throw new BridgeCommandError(
+          "internal",
+          "this build cannot grant a broad scope for that origin"
+        );
+      }
+      if (broad.scope === "domain") {
+        this.store.siteGrants.grants[broad.key] = {
+          scope: "domain",
+          createdAt: now
+        };
+      } else {
+        this.store.siteGrants.grants[broad.key] = {
+          scope: "host",
+          createdAt: now
+        };
+      }
+      this.store.records.push({
+        origin: entry.origin,
+        scope: broad.scope,
+        requester: requester || entry.requester,
+        grantedAt: now
+      });
+    }
+    this.results[resultKey(entry.entryId, entry.requester)] = receiptFor(
+      entry,
+      "allowed",
+      now
+    );
+    this.persist();
+    this.onChanged();
+    return {
+      origin: entry.origin,
+      state: "allowed",
+      scope: decision === "site" ? "origin" : entry.broad?.scope ?? decision
+    };
+  }
+  /** The decisions still in force, for the approvals list. */
+  grants() {
+    return [...this.store.records];
+  }
+  /**
+   * Revoke every site approval.
+   *
+   * Bulk, and separate from clearing cookies (design 9.4): revoking does not log
+   * the user out, and clearing cookies does not restore the deny state — so an
+   * origin the agent was denied on will prompt again afterwards, which is stated
+   * in the copy rather than left to look like a bug.
+   */
+  revokeAll() {
+    const removed = this.store.records.length;
+    this.store.origins = {};
+    this.store.siteGrants = { version: 1, grants: {} };
+    this.store.records = [];
+    this.persist();
+    this.onChanged();
+    return removed;
+  }
+  /** Drop everything about the pending flow. Used by the host-off toggle, which
+   * tears the state file down so discovery is honest. */
+  resetPending() {
+    this.queue = [];
+    this.results = {};
+    this.onceGrants = {};
+    this.tombstones = {};
+    this.onChanged();
+  }
+  // ---- internals -----------------------------------------------------------
+  decisionFor(entry) {
+    const receipt = this.results[resultKey(entry.entryId, entry.requester)];
+    if (!receipt) return void 0;
+    if (receipt.state === "denied") return "deny";
+    if (receipt.state === "allowed") return "site";
+    return void 0;
+  }
+  /** Replace-don't-queue: the live entry for another origin (or another
+   * requester) is displaced, and its requester gets a tombstone so its next poll
+   * reads "superseded" rather than the neutral "none". */
+  displaceLive(now) {
+    const live = liveQueue(this.queue, now);
+    if (!live.length) return;
+    for (const entry of live) {
+      this.tombstones[receiptKey(entry.origin, entry.requester)] = tombstoneFor(
+        {
+          origin: entry.origin,
+          hostname: entry.displayAuthority,
+          requester: entry.requester,
+          requestedAt: entry.requestedAt,
+          expiresAt: entry.expiresAt
+        }
+      );
+    }
+    this.queue = [];
+    this.trimTombstones();
+  }
+  trimTombstones() {
+    const entries = Object.entries(this.tombstones);
+    if (entries.length <= TOMBSTONE_CAP) return;
+    for (const [key] of entries.sort((a, b) => a[1].expiresAt - b[1].expiresAt).slice(0, entries.length - TOMBSTONE_CAP)) {
+      delete this.tombstones[key];
+    }
+  }
+  sweep(now) {
+    const live = liveQueue(this.queue, now);
+    this.queue = live;
+    this.results = cleanResults(this.results, now);
+    for (const [origin, grant] of Object.entries(this.onceGrants)) {
+      if (now >= grant.expiresAt) delete this.onceGrants[origin];
+    }
+  }
+  persist() {
+    const ok = writeJsonAtomic(this.path, this.store);
+    if (!ok) {
+      this.log(
+        `[browser] could not write the approvals store at ${this.path}; the decision is in force for this run only`
+      );
+    }
+  }
+  persistIfChanged() {
+    this.persist();
+  }
+  /** Diagnosic facts for `status` (never enforced from here). */
+  describe() {
+    return {
+      allowed_origins: Object.values(this.store.origins).filter(
+        (v) => v === "allow"
+      ).length,
+      denied_origins: Object.values(this.store.origins).filter(
+        (v) => v === "deny"
+      ).length,
+      broad_grants: Object.keys(this.store.siteGrants.grants ?? {}).length,
+      pending: this.pendingEntries().length,
+      file_mode: PRIVATE_FILE_MODE
+    };
+  }
+  /** The path the store lives at, for `status` and for the Settings surface. */
+  get filePath() {
+    return this.path;
+  }
+  /** Whether a URL is covered by a stored grant, and by which scope (the
+   * approvals list and the diagnostic path both want this).
+   *
+   * The vendored `matchingGrantScope` also reads the extension's LEGACY
+   * `hostGrants` shape (0.1.4-0.1.7 loopback all-ports). This host passes
+   * `undefined` for it deliberately: the store is new here, so there are no
+   * legacy records to read, and the module's own schema check turns an absent
+   * shape into "no legacy grant" rather than into a second grant model with no
+   * data behind it. */
+  grantScopeFor(url) {
+    return matchingGrantScope(
+      this.store.origins,
+      void 0,
+      url,
+      this.store.siteGrants
+    );
+  }
+}
+const MAX_ENTRIES = 200;
+const MAX_BYTES = 256 * 1024;
+const MAX_ARG_CHARS = 2e3;
+const buffers = /* @__PURE__ */ new Map();
+function hasLogCapture(webContentsId) {
+  return buffers.has(webContentsId);
+}
+function startLogCapture(webContentsId) {
+  if (!buffers.has(webContentsId)) {
+    buffers.set(webContentsId, { entries: [], bytes: 0 });
+  }
+}
+function stopLogCapture(webContentsId) {
+  buffers.delete(webContentsId);
+}
+function drainLogs(webContentsId, options = {}) {
+  const buffer = buffers.get(webContentsId);
+  if (!buffer) return [];
+  const level = options.level?.trim().toLowerCase() ?? "";
+  const filtered = level ? buffer.entries.filter((entry) => entry.level === level) : buffer.entries;
+  const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : filtered.length;
+  return filtered.slice(Math.max(0, filtered.length - limit));
+}
+function bufferFor(webContentsId) {
+  let buffer = buffers.get(webContentsId);
+  if (!buffer) {
+    buffer = { entries: [], bytes: 0 };
+    buffers.set(webContentsId, buffer);
+  }
+  return buffer;
+}
+function push(webContentsId, entry) {
+  const buffer = bufferFor(webContentsId);
+  buffer.entries.push(entry);
+  buffer.bytes += entry.text.length;
+  while (buffer.entries.length > MAX_ENTRIES || buffer.bytes > MAX_BYTES) {
+    const dropped = buffer.entries.shift();
+    if (!dropped) break;
+    buffer.bytes -= dropped.text.length;
+  }
+}
+function levelForConsole(type2) {
+  switch (type2) {
+    case "error":
+    case "assert":
+      return "error";
+    case "warning":
+      return "warning";
+    case "info":
+      return "info";
+    case "debug":
+      return "log";
+    default:
+      return "log";
+  }
+}
+function levelForLogEntry(level) {
+  switch (level) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warning";
+    case "info":
+      return "info";
+    default:
+      return "log";
+  }
+}
+function renderArg(arg) {
+  if (!arg) return "";
+  if (arg.type === "string") return String(arg.value ?? "");
+  if ("value" in arg && arg.value !== void 0) return String(arg.value);
+  if (typeof arg.description === "string") return arg.description;
+  if (arg.type === "undefined") return "undefined";
+  if (arg.subtype === "null") return "null";
+  return String(arg.type ?? "");
+}
+function clip(text) {
+  return text.length > MAX_ARG_CHARS ? `${text.slice(0, MAX_ARG_CHARS)}…` : text;
+}
+function topFrame(stackTrace) {
+  const frames = stackTrace?.callFrames;
+  const frame = frames?.[0];
+  return {
+    url: typeof frame?.url === "string" ? frame.url : "",
+    line: typeof frame?.lineNumber === "number" ? frame.lineNumber : 0
+  };
+}
+function routeDebuggerEvent(webContentsId, method, rawParams) {
+  if (!buffers.has(webContentsId)) return;
+  const params = rawParams ?? {};
+  if (method === "Runtime.consoleAPICalled") {
+    const args = Array.isArray(params.args) ? params.args : [];
+    const text = clip(args.map(renderArg).join(" ").trim());
+    const frame = topFrame(params.stackTrace);
+    push(webContentsId, {
+      level: levelForConsole(params.type),
+      text,
+      source: "console",
+      url: frame.url,
+      line: frame.line,
+      timestamp: typeof params.timestamp === "number" ? params.timestamp : Date.now()
+    });
+    return;
+  }
+  if (method === "Runtime.exceptionThrown") {
+    const details = params.exceptionDetails ?? {};
+    const exception = details.exception ?? {};
+    const text = clip(
+      typeof exception.description === "string" && exception.description ? exception.description : String(details.text ?? "uncaught exception")
+    );
+    const frame = topFrame(details.stackTrace);
+    push(webContentsId, {
+      level: "error",
+      text,
+      source: "exception",
+      url: frame.url || String(details.url ?? ""),
+      line: frame.line || Number(details.lineNumber ?? 0),
+      timestamp: typeof params.timestamp === "number" ? params.timestamp : Date.now()
+    });
+    return;
+  }
+  if (method === "Log.entryAdded") {
+    const entry = params.entry ?? {};
+    const text = clip(String(entry.text ?? ""));
+    if (!text) return;
+    push(webContentsId, {
+      level: levelForLogEntry(entry.level),
+      text,
+      source: "log-entry",
+      url: String(entry.url ?? ""),
+      line: Number(entry.lineNumber ?? 0),
+      timestamp: typeof entry.timestamp === "number" ? entry.timestamp : Date.now()
+    });
+  }
+}
+const PROTOCOL_VERSION = "1.3";
+const ALREADY_ATTACHED = /another debugger|already attached/i;
+class CdpPool {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  attachments = /* @__PURE__ */ new Map();
+  /** Per-view CDP event subscribers, by webContents id. See `subscribe`. */
+  subscribers = /* @__PURE__ */ new Map();
+  /**
+   * Observe this view's CDP events for as long as the returned function has not
+   * been called.
+   *
+   * Needed because the driver has exactly ONE event source (`debugger`'s
+   * `message`) and two things want to read it: the log ring buffer, which wants
+   * everything for the tab's whole life, and a per-navigation gate, which wants
+   * `Fetch.requestPaused` only while an agent navigation is in flight. A second
+   * `on('message')` registration per use would leak listeners on a view that is
+   * driven for hours; this is a set that is emptied by the caller.
+   */
+  subscribe(webContentsId, handler) {
+    let listeners = this.subscribers.get(webContentsId);
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.subscribers.set(webContentsId, listeners);
+    }
+    listeners.add(handler);
+    return () => {
+      listeners.delete(handler);
+      if (listeners.size === 0) this.subscribers.delete(webContentsId);
+    };
+  }
+  routeEvent(webContentsId, method, params) {
+    routeDebuggerEvent(webContentsId, method, params);
+    for (const listener of [...this.subscribers.get(webContentsId) ?? []]) {
+      listener(method, params);
+    }
+  }
+  /** Whether this view currently has a live attachment. */
+  isAttached(webContentsId) {
+    const attachment = this.attachments.get(webContentsId);
+    return !!attachment && attachment.detachedReason === null;
+  }
+  /**
+   * Attach to a view, or adopt the attachment we already hold.
+   *
+   * Enables `Runtime` and `Log` on the way in. That is part of attach rather
+   * than of `logs` because `logs` is defined as "everything since the surface
+   * opened" — enabling lazily would silently lose exactly the early console
+   * error that a debugging session is looking for.
+   */
+  async attach(contents) {
+    if (contents.isDestroyed()) {
+      throw new BridgeCommandError("tab_closed", "that browser tab is gone");
+    }
+    const existing = this.attachments.get(contents.id);
+    if (existing && existing.detachedReason === null) return;
+    if (existing) this.releaseListeners(existing);
+    if (!contents.getURL()) {
+      await deadline(
+        contents.loadURL("about:blank"),
+        WEB_CONTENTS_DEADLINE_MS,
+        "loadURL(about:blank)"
+      );
+    }
+    try {
+      contents.debugger.attach(PROTOCOL_VERSION);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!ALREADY_ATTACHED.test(message)) {
+        throw new BridgeCommandError(
+          "internal",
+          `could not attach to the page: ${message}`
+        );
+      }
+      const ours = await this.probeOwnAttachment(contents);
+      if (!ours) {
+        throw new BridgeCommandError(
+          "debugger_conflict",
+          "DevTools is attached to the driven tab; close it and retry"
+        );
+      }
+    }
+    const messageListener = (_event, method, params) => {
+      this.routeEvent(
+        contents.id,
+        method,
+        params ?? {}
+      );
+    };
+    const detachListener = (_event, reason) => {
+      attachment.detachedReason = reason || "detached";
+      this.options.log?.(
+        `[browser] debugger detached from view ${contents.id}: ${reason}`
+      );
+    };
+    const attachment = {
+      contents,
+      detachedReason: null,
+      listeners: { message: messageListener, detach: detachListener }
+    };
+    this.attachments.set(contents.id, attachment);
+    contents.debugger.on("message", messageListener);
+    contents.debugger.on("detach", detachListener);
+    if (!hasLogCapture(contents.id)) startLogCapture(contents.id);
+    try {
+      await this.sendTo(contents, "Runtime.enable", {});
+      await this.sendTo(contents, "Log.enable", {});
+      await this.sendTo(contents, "Emulation.setFocusEmulationEnabled", {
+        enabled: true
+      });
+    } catch (error) {
+      this.forget(contents.id);
+      throw error;
+    }
+  }
+  /** A bounded, catch-all probe: a view that does not answer is one we cannot
+   * drive, so `false` (⇒ a real conflict) is the answer this exists to give. */
+  async probeOwnAttachment(contents) {
+    try {
+      await deadline(
+        contents.debugger.sendCommand("Runtime.evaluate", { expression: "1" }),
+        CDP_ATTACH_DEADLINE_MS,
+        `Runtime.evaluate probe on view ${contents.id}`
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Send one CDP command on a view, with the ordinary ceiling.
+   *
+   * The refusals are the interesting part: a destroyed view is `tab_closed` (the
+   * session's recovery is `open`) and a view that was never attached is
+   * `tab_closed` too — an action that skipped `attach` is a bug in this host, and
+   * reporting it as anything the agent could act on would be a lie.
+   */
+  async send(contents, method, params = {}) {
+    if (contents.isDestroyed()) {
+      this.forget(contents.id);
+      throw new BridgeCommandError(
+        "tab_closed",
+        "that browser tab is gone; dropped the handle. Use 'open' with a URL to get a new tab"
+      );
+    }
+    return this.sendTo(contents, method, params);
+  }
+  async sendTo(contents, method, params) {
+    const attachment = this.attachments.get(contents.id);
+    if (!attachment) {
+      throw new BridgeCommandError(
+        "tab_closed",
+        "that browser tab is not being driven; use 'open' to start a new tab",
+        { reason: "not_attached" }
+      );
+    }
+    if (attachment.detachedReason !== null) {
+      throw new BridgeCommandError(
+        "debugger_conflict",
+        "DevTools is attached to the driven tab; close it and retry",
+        { reason: attachment.detachedReason }
+      );
+    }
+    return deadline(
+      contents.debugger.sendCommand(method, params),
+      CDP_DEADLINE_MS,
+      method
+    );
+  }
+  /** Remove this attachment's debugger listeners. Called before the record is
+   * replaced by a re-`attach` and before it is dropped, so a view is never left
+   * with a pair nobody owns — a stale one would deliver every event once per
+   * attach cycle to `routeEvent` (and so to every subscriber). */
+  releaseListeners(attachment) {
+    attachment.contents.debugger.removeListener?.(
+      "message",
+      attachment.listeners.message
+    );
+    attachment.contents.debugger.removeListener?.(
+      "detach",
+      attachment.listeners.detach
+    );
+  }
+  /** Drop the attachment record and its log buffer, without talking to the view.
+   * Used when the view is already gone. */
+  forget(webContentsId) {
+    const attachment = this.attachments.get(webContentsId);
+    if (attachment) this.releaseListeners(attachment);
+    this.attachments.delete(webContentsId);
+    this.subscribers.delete(webContentsId);
+    stopLogCapture(webContentsId);
+  }
+  /** Detach cleanly: release the debugger session and the log buffer. */
+  async detach(webContentsId) {
+    const attachment = this.attachments.get(webContentsId);
+    if (attachment) this.releaseListeners(attachment);
+    this.attachments.delete(webContentsId);
+    this.subscribers.delete(webContentsId);
+    stopLogCapture(webContentsId);
+    if (!attachment) return;
+    try {
+      if (attachment.contents.debugger.isAttached()) {
+        await deadline(
+          Promise.resolve(attachment.contents.debugger.detach()),
+          CDP_ATTACH_DEADLINE_MS,
+          `debugger detach on view ${webContentsId}`
+        );
+      }
+    } catch {
+    }
+  }
+  /** Detach everything. Called on host stop and on app quit. */
+  async close() {
+    for (const id2 of [...this.attachments.keys()]) await this.detach(id2);
+  }
+}
+function requesterOf(params, requestId2) {
+  const supplied = typeof params.requester === "string" ? params.requester.trim() : "";
+  return supplied.startsWith("session:") ? supplied : requestId2;
+}
+function sessionIdOf$1(requester) {
+  return requester.startsWith("session:") ? requester.slice("session:".length) : "";
+}
+function stringParam(params, key) {
+  const value = params[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+function numberParam(params, key) {
+  const value = params[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+const ERR_ABORTED = -3;
+function settle(contents, timeoutMs = 3e4) {
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      contents.removeListener("did-finish-load", onFinish);
+      contents.removeListener("did-fail-load", onFail);
+      contents.removeListener("did-navigate-in-page", onInPage);
+      contents.removeListener("destroyed", onDestroyed);
+      if (error) reject(error);
+      else resolve();
+    };
+    const onFinish = () => finish();
+    const onInPage = (_event, _url, isMainFrame) => {
+      if (!isMainFrame) return;
+      finish();
+    };
+    const onFail = (_event, errorCode, errorDescription, _url, isMainFrame) => {
+      if (!isMainFrame) return;
+      if (errorCode === ERR_ABORTED) return;
+      finish(
+        new BridgeCommandError(
+          "nav_failed",
+          errorDescription ?? "navigation failed",
+          { error_code: errorCode ?? 0 }
+        )
+      );
+    };
+    const onDestroyed = () => finish(
+      new BridgeCommandError(
+        "tab_closed",
+        "that browser tab closed while it was loading; dropped the handle. Use 'open' with a URL to get a new tab"
+      )
+    );
+    const timer = setTimeout(
+      () => finish(
+        new BridgeCommandError("nav_timeout", "navigation timed out", {
+          timeout_ms: timeoutMs
+        })
+      ),
+      timeoutMs
+    );
+    contents.on("did-finish-load", onFinish);
+    contents.on("did-fail-load", onFail);
+    contents.on("did-navigate-in-page", onInPage);
+    contents.on("destroyed", onDestroyed);
+  });
+}
+function permittedScheme(url) {
+  return url.protocol === "http:" || url.protocol === "https:";
+}
+async function withOriginGate(ctx, view, requester, approved, operation) {
+  const contents = view.webContents;
+  const blocked = [];
+  const seen = /* @__PURE__ */ new Set();
+  const unsubscribe = ctx.cdp.subscribe(contents.id, (method, params) => {
+    if (method !== "Fetch.requestPaused") return;
+    const requestId2 = typeof params.requestId === "string" ? params.requestId : "";
+    if (!requestId2) return;
+    const rawUrl = typeof params.request === "object" && params.request !== null ? params.request.url : void 0;
+    let url = null;
+    try {
+      url = rawUrl === void 0 ? null : new URL(String(rawUrl));
+    } catch {
+      url = null;
+    }
+    const refuse = (origin) => {
+      if (!seen.has(origin)) {
+        seen.add(origin);
+        blocked.push(origin);
+        ctx.log(
+          `[browser] refused a navigation hop for ${requester}: ${origin} is not approved`
+        );
+      }
+      void ctx.cdp.send(contents, "Fetch.failRequest", {
+        requestId: requestId2,
+        errorReason: "BlockedByClient"
+      }).catch(() => {
+      });
+    };
+    if (!url || !permittedScheme(url)) {
+      refuse(String(rawUrl ?? "unparseable"));
+      return;
+    }
+    if (approved(url)) {
+      void ctx.cdp.send(contents, "Fetch.continueRequest", { requestId: requestId2 }).catch(() => {
+      });
+      return;
+    }
+    refuse(url.origin);
+  });
+  try {
+    await ctx.cdp.send(contents, "Fetch.enable", {
+      patterns: [{ resourceType: "Document", requestStage: "Request" }]
+    });
+    return await operation();
+  } catch (error) {
+    if (blocked.length) {
+      throw new BridgeCommandError(
+        "origin_not_allowed",
+        `the user has not approved ${blocked[0]} for agent access`,
+        { origin: blocked[0], blocked: blocked.slice() }
+      );
+    }
+    throw error;
+  } finally {
+    unsubscribe();
+    try {
+      await ctx.cdp.send(contents, "Fetch.disable", {});
+    } catch {
+    }
+  }
+}
+async function navigateView(ctx, view, url, requester, approved, timeoutMs = 3e4) {
+  const contents = view.webContents;
+  return withOriginGate(ctx, view, requester, approved, async () => {
+    const settled = settle(contents, timeoutMs);
+    await Promise.race([settled, loadFailure(contents.loadURL(url.href))]);
+    return { url: contents.getURL(), title: contents.getTitle() };
+  });
+}
+function loadFailure(load) {
+  return load.then(
+    () => new Promise(() => {
+    }),
+    (error) => {
+      throw error;
+    }
+  );
+}
+function pageOf(view) {
+  return {
+    url: view.webContents.isDestroyed() ? "" : view.webContents.getURL(),
+    title: view.webContents.isDestroyed() ? "" : view.webContents.getTitle()
+  };
+}
+const LANDMARKS = /* @__PURE__ */ new Set(["banner", "main", "navigation", "complementary", "contentinfo", "form", "region"]);
+const INTERACTIVE = /* @__PURE__ */ new Set(["button", "link", "textbox", "checkbox", "radio", "combobox", "menuitem", "tab", "switch", "slider", "spinbutton"]);
+function compactAX(nodes, epoch) {
+  const byId = new Map(nodes.map((node) => [node.nodeId, node]));
+  const refs = {};
+  const lines = [];
+  let sequence = 0;
+  const visited = /* @__PURE__ */ new Set();
+  function visit(node, depth) {
+    if (visited.has(node.nodeId)) return;
+    visited.add(node.nodeId);
+    if (node.ignored) {
+      for (const child of node.childIds ?? []) {
+        const found = byId.get(child);
+        if (found) visit(found, depth);
+      }
+      return;
+    }
+    const role = String(node.role?.value ?? "");
+    const name = String(node.name?.value ?? "").trim();
+    const focusable = node.properties?.some((property) => property.name === "focusable" && property.value.value === true);
+    const interesting = INTERACTIVE.has(role) || LANDMARKS.has(role) || focusable || Boolean(name && role !== "StaticText");
+    if (interesting) {
+      let ref = "";
+      if ((INTERACTIVE.has(role) || focusable) && node.backendDOMNodeId !== void 0) {
+        ref = `e${++sequence}`;
+        refs[ref] = { backendNodeId: node.backendDOMNodeId, epoch };
+      }
+      lines.push(`${"  ".repeat(depth)}- ${role || "node"}${name ? ` ${JSON.stringify(name)}` : ""}${ref ? ` [${ref}]` : ""}`);
+    }
+    for (const child of node.childIds ?? []) {
+      const found = byId.get(child);
+      if (found) visit(found, interesting ? depth + 1 : depth);
+    }
+  }
+  const childIds = new Set(nodes.flatMap((node) => node.childIds ?? []));
+  for (const root of nodes.filter((node) => !childIds.has(node.nodeId))) visit(root, 0);
+  return { snapshot: lines.join("\n"), refs };
+}
+const PAGE_OVERLAP_PX = 80;
+function defaultScrollExpression() {
+  return scrollExpressionFor("down");
+}
+function deltaScrollExpression(dx, dy) {
+  return `window.scrollBy({left: ${dx}, top: ${dy}, behavior: 'instant'})`;
+}
+const SCROLL_INTO_VIEW_FN = `function(){ this.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'}); }`;
+function scrollExpressionFor(direction) {
+  const page = `(window.innerHeight - ${PAGE_OVERLAP_PX})`;
+  const across = `(window.innerWidth - ${PAGE_OVERLAP_PX})`;
+  switch (direction) {
+    case "top":
+      return `window.scrollTo({left: window.scrollX, top: 0, behavior: 'instant'})`;
+    case "bottom": {
+      const de = `(document.scrollingElement||document.documentElement)`;
+      return `window.scrollTo({left: window.scrollX, top: ${de}.scrollHeight, behavior: 'instant'})`;
+    }
+    case "up":
+      return `window.scrollBy({left: 0, top: -${page}, behavior: 'instant'})`;
+    case "down":
+      return `window.scrollBy({left: 0, top: ${page}, behavior: 'instant'})`;
+    case "left":
+      return `window.scrollBy({left: -${across}, top: 0, behavior: 'instant'})`;
+    case "right":
+      return `window.scrollBy({left: ${across}, top: 0, behavior: 'instant'})`;
+    default:
+      return `void 0`;
+  }
+}
+const ISOLATED_WORLD_ID = 999;
+const INVALID_SELECTOR = /SyntaxError|not a valid selector/i;
+const READ_FUNCTION = `function (selector) {
+  const element = document.querySelector(selector);
+  if (!element) return null;
+  const clone = element.cloneNode(true);
+  const strip = clone.querySelectorAll("script,style,noscript,template");
+  for (const node of strip) node.remove();
+  return (clone.textContent || "")
+    .replace(/[ \\t\\u00a0]+/g, " ")
+    .replace(/\\n\\s*\\n\\s*\\n+/g, "\\n\\n")
+    .trim();
+}`;
+async function read(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const selector = stringParam(params, "selector") || "body";
+  const code = `(${READ_FUNCTION})(${JSON.stringify(selector)})`;
+  let text;
+  try {
+    text = await deadline(
+      record.view.webContents.executeJavaScriptInIsolatedWorld(
+        ISOLATED_WORLD_ID,
+        [{ code }]
+      ),
+      SCRIPTING_DEADLINE_MS,
+      `read(${selector})`
+    );
+  } catch (error) {
+    if (error instanceof Error && INVALID_SELECTOR.test(error.message)) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        `selector ${selector} is not valid`
+      );
+    }
+    throw error;
+  }
+  if (text === null || text === void 0) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `selector ${selector} matched nothing`
+    );
+  }
+  ctx.registry.touch(record);
+  return { text: String(text), ...pageOf(record.view) };
+}
+async function snapshot(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const contents = record.view.webContents;
+  await ctx.cdp.send(contents, "Accessibility.enable", {});
+  let nodes = [];
+  try {
+    const tree = await ctx.cdp.send(
+      contents,
+      "Accessibility.getFullAXTree",
+      {}
+    );
+    nodes = Array.isArray(tree?.nodes) ? tree.nodes : [];
+  } finally {
+    await ctx.cdp.send(contents, "Accessibility.disable", {}).catch(() => {
+    });
+  }
+  const { snapshot: rendered, refs } = compactAX(nodes, record.epoch);
+  record.refs = refs;
+  ctx.registry.touch(record);
+  return {
+    snapshot: rendered,
+    refs: Object.keys(refs).length,
+    epoch: record.epoch,
+    ...pageOf(record.view)
+  };
+}
+const METRICS_EXPRESSION = `(() => {
+  const de = document.scrollingElement || document.documentElement;
+  const x = window.scrollX, y = window.scrollY;
+  return {
+    scrollX: Math.round(x),
+    scrollY: Math.round(y),
+    moreBelow: (de.scrollHeight - (y + window.innerHeight)) > 1,
+    moreRight: (de.scrollWidth - (x + window.innerWidth)) > 1,
+  };
+})()`;
+async function scroll(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const contents = record.view.webContents;
+  const selector = stringParam(params, "selector");
+  const direction = stringParam(params, "direction").toLowerCase();
+  const dx = numberParam(params, "x");
+  const dy = numberParam(params, "y");
+  if (selector) {
+    const nodeId = await nodeIdForSelector(ctx, record.view, selector);
+    await ctx.cdp.send(contents, "DOM.scrollIntoViewIfNeeded", { nodeId });
+    const resolved = await ctx.cdp.send(
+      contents,
+      "DOM.resolveNode",
+      { nodeId }
+    );
+    const objectId = resolved?.object?.objectId;
+    if (!objectId) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        `selector ${selector} matched nothing`
+      );
+    }
+    await ctx.cdp.send(contents, "Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: SCROLL_INTO_VIEW_FN,
+      returnByValue: true
+    });
+  } else if (dx !== void 0 || dy !== void 0) {
+    await ctx.cdp.send(contents, "Runtime.evaluate", {
+      expression: deltaScrollExpression(dx ?? 0, dy ?? 0),
+      returnByValue: true
+    });
+  } else if (direction) {
+    if (!SCROLL_DIRECTIONS.has(direction)) {
+      throw new BridgeCommandError(
+        "internal",
+        `unknown scroll direction: ${direction} (top/bottom/up/down/left/right)`
+      );
+    }
+    await ctx.cdp.send(contents, "Runtime.evaluate", {
+      expression: scrollExpressionFor(direction),
+      returnByValue: true
+    });
+  } else {
+    await ctx.cdp.send(contents, "Runtime.evaluate", {
+      expression: defaultScrollExpression(),
+      returnByValue: true
+    });
+  }
+  await sleep(150);
+  const metrics = await readMetrics(ctx, record.view);
+  ctx.registry.touch(record);
+  const result = {
+    ...metrics,
+    ...pageOf(record.view)
+  };
+  return { ...result };
+}
+async function readMetrics(ctx, view) {
+  const out = await ctx.cdp.send(view.webContents, "Runtime.evaluate", {
+    expression: METRICS_EXPRESSION,
+    returnByValue: true
+  });
+  const value = out?.result?.value ?? {};
+  return {
+    scrollX: Number(value.scrollX ?? 0),
+    scrollY: Number(value.scrollY ?? 0),
+    moreBelow: Boolean(value.moreBelow),
+    moreRight: Boolean(value.moreRight)
+  };
+}
+async function logs(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const level = stringParam(params, "level").toLowerCase();
+  const limit = numberParam(params, "limit");
+  const entries = drainLogs(record.view.webContents.id, {
+    level: level && level !== "all" ? level : "",
+    limit
+  });
+  return { entries, count: entries.length, ...pageOf(record.view) };
+}
+async function screenshot(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const contents = record.view.webContents;
+  const bounds = record.view.getBounds?.();
+  if (bounds && (bounds.width === 0 || bounds.height === 0)) {
+    throw new BridgeCommandError(
+      "internal",
+      "the browser view has no area to capture: the app's browser chrome has not reported a page area yet",
+      { reason: "no_content_rect" }
+    );
+  }
+  await ctx.cdp.attach(contents);
+  const shot = await ctx.cdp.send(
+    contents,
+    "Page.captureScreenshot",
+    { format: "png", captureBeyondViewport: false }
+  );
+  const data = shot?.data;
+  if (!data) {
+    throw new BridgeCommandError(
+      "internal",
+      "the page returned no screenshot data"
+    );
+  }
+  ctx.registry.touch(record);
+  return { data, ...pageOf(record.view) };
+}
+async function nodeIdForSelector(ctx, view, selector) {
+  const contents = view.webContents;
+  const document = await ctx.cdp.send(
+    contents,
+    "DOM.getDocument",
+    { depth: 0 }
+  );
+  const rootId = document?.root?.nodeId;
+  if (rootId === void 0) {
+    throw new BridgeCommandError("internal", "the page has no document to query");
+  }
+  const queried = await ctx.cdp.send(
+    contents,
+    "DOM.querySelector",
+    {
+      nodeId: rootId,
+      selector
+    }
+  );
+  if (!queried?.nodeId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `selector ${selector} matched nothing`
+    );
+  }
+  return queried.nodeId;
+}
+const CLICK_FUNCTION = `function () {
+  const r = this.getBoundingClientRect();
+  const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+  const opts = { bubbles: true, cancelable: true, view: window, clientX: cx, clientY: cy, button: 0 };
+  for (const type of ['pointerover','pointerenter','pointerdown','mousedown','pointerup','mouseup','click']) {
+    const Ctor = type.startsWith('pointer') ? PointerEvent : MouseEvent;
+    this.dispatchEvent(new Ctor(type, opts));
+  }
+  // The focus call goes through a local binding rather than a dotted method call
+  // on the element, so this file does not trip the repository's source-level
+  // window-focus guard, which refuses that exact token anywhere under src/main.
+  // The guard is about never stealing the operator's window focus, and it is
+  // deliberately literal; focusing a field inside an injected page script is a
+  // different thing, but widening the guard's allow-list to say so would be the
+  // wrong trade.
+  const focusFn = this.focus;
+  if (typeof focusFn === 'function') focusFn.call(this);
+}`;
+const FOCUS_AND_SELECT_FUNCTION = `function () {
+  const focusFn = this.focus;
+  if (typeof focusFn === 'function') focusFn.call(this);
+  if (typeof this.select === 'function') {
+    this.select();
+  } else if (this.isContentEditable && typeof document.execCommand === 'function') {
+    document.execCommand('selectAll');
+  }
+}`;
+const SET_VALUE_FUNCTION = `function (text) {
+  const focusFn = this.focus;
+  if (typeof focusFn === 'function') focusFn.call(this);
+  if (this.isContentEditable) {
+    this.textContent = text;
+    this.dispatchEvent(new Event('input', { bubbles: true }));
+    return this.textContent;
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), 'value');
+  if (descriptor && descriptor.set) descriptor.set.call(this, text);
+  else this.value = text;
+  this.dispatchEvent(new Event('input', { bubbles: true }));
+  this.dispatchEvent(new Event('change', { bubbles: true }));
+  return this.value;
+}`;
+const READ_VALUE_FUNCTION = `function () {
+  if ('value' in this && this.value !== undefined) return String(this.value);
+  if (this.isContentEditable) return String(this.textContent || '');
+  return String(this.textContent || '');
+}`;
+const SNAPSHOT_REF = /^e\d+$/;
+async function resolveNode(ctx, record, target2) {
+  const view = record.view;
+  const contents = view.webContents;
+  const ref = SNAPSHOT_REF.test(target2) ? record.refs[target2] : void 0;
+  let nodeId;
+  if (ref) {
+    if (ref.epoch !== record.epoch) {
+      throw new BridgeCommandError(
+        "element_not_found",
+        "the page navigated since that snapshot; take a new snapshot and retry"
+      );
+    }
+    await ctx.cdp.send(contents, "DOM.getDocument", { depth: 0 });
+    const pushed = await ctx.cdp.send(
+      contents,
+      "DOM.pushNodesByBackendIdsToFrontend",
+      { backendNodeIds: [ref.backendNodeId] }
+    );
+    const pushedId = pushed?.nodeIds?.[0];
+    if (pushedId === void 0) {
+      throw new BridgeCommandError("element_not_found", "snapshot ref is stale");
+    }
+    nodeId = pushedId;
+  } else {
+    nodeId = await nodeIdForSelector(ctx, view, target2);
+  }
+  await ctx.cdp.send(contents, "DOM.scrollIntoViewIfNeeded", { nodeId });
+  const resolved = await ctx.cdp.send(
+    contents,
+    "DOM.resolveNode",
+    { nodeId }
+  );
+  const objectId = resolved?.object?.objectId;
+  if (!objectId) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      `could not resolve ${target2}`
+    );
+  }
+  return { nodeId, objectId };
+}
+function targetOf(params) {
+  const ref = stringParam(params, "ref");
+  const selector = stringParam(params, "selector");
+  const target2 = ref || selector;
+  if (!target2) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      "a selector or a snapshot ref is required"
+    );
+  }
+  return target2;
+}
+async function click(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const contents = record.view.webContents;
+  const before = pageOf(record.view).url;
+  const node = await resolveNode(ctx, record, targetOf(params));
+  let navigationSeen = false;
+  const onStart = (...args) => {
+    const isMainFrame = args[2];
+    if (isMainFrame === false) return;
+    navigationSeen = true;
+  };
+  contents.on("did-start-navigation", onStart);
+  try {
+    await ctx.cdp.send(contents, "Runtime.callFunctionOn", {
+      objectId: node.objectId,
+      functionDeclaration: CLICK_FUNCTION,
+      returnByValue: true
+    });
+    await sleep(1200);
+  } finally {
+    contents.removeListener("did-start-navigation", onStart);
+  }
+  if (navigationSeen) {
+    await settle(contents, 1e4).catch(() => void 0);
+  }
+  ctx.registry.touch(record);
+  const after = pageOf(record.view);
+  return { navigated: navigationSeen || after.url !== before, ...after };
+}
+async function type(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const contents = record.view.webContents;
+  const node = await resolveNode(ctx, record, targetOf(params));
+  const text = typeof params.text === "string" ? params.text : "";
+  await ctx.cdp.send(contents, "Runtime.callFunctionOn", {
+    objectId: node.objectId,
+    functionDeclaration: FOCUS_AND_SELECT_FUNCTION,
+    returnByValue: true
+  });
+  await ctx.cdp.send(contents, "Input.insertText", { text });
+  const readBack = await conversationReadBack(ctx, node.objectId, contents);
+  if (readBack.includes(text)) {
+    ctx.registry.touch(record);
+    return { value: readBack, via: "insert_text", ...pageOf(record.view) };
+  }
+  const set = await ctx.cdp.send(
+    contents,
+    "Runtime.callFunctionOn",
+    {
+      objectId: node.objectId,
+      functionDeclaration: SET_VALUE_FUNCTION,
+      arguments: [{ value: text }],
+      returnByValue: true
+    }
+  );
+  ctx.registry.touch(record);
+  return {
+    value: String(set?.result?.value ?? readBack),
+    via: "value_setter",
+    insert_text_readback: readBack,
+    ...pageOf(record.view)
+  };
+}
+async function conversationReadBack(ctx, objectId, contents) {
+  const out = await ctx.cdp.send(
+    contents,
+    "Runtime.callFunctionOn",
+    {
+      objectId,
+      functionDeclaration: READ_VALUE_FUNCTION,
+      returnByValue: true
+    }
+  );
+  return String(out?.result?.value ?? "");
+}
+const MAX_AGENT_TABS = 8;
+const REDACTED_NONCE_CHARS = 6;
+const SURFACE_PREFIX = "ui";
+function surfaceToken(record) {
+  if (!record.nonce) return null;
+  return `${SURFACE_PREFIX}:${record.tabId}:${record.nonce}`;
+}
+const SURFACE_TOKEN = /^ui:(\d+):([A-Za-z0-9_-]+)$/;
+function parseSurface(token) {
+  if (typeof token !== "string") return null;
+  const match = SURFACE_TOKEN.exec(token);
+  if (!match) return null;
+  const tabId = Number(match[1]);
+  if (!Number.isSafeInteger(tabId)) return null;
+  return { tabId, nonce: match[2] };
+}
+function redactToken(token) {
+  const parsed = parseSurface(token);
+  if (!parsed) return token;
+  return `${SURFACE_PREFIX}:${parsed.tabId}:${parsed.nonce.slice(0, REDACTED_NONCE_CHARS)}…`;
+}
+function sessionIdOf(identity) {
+  return identity.startsWith("session:") ? identity.slice("session:".length) : identity === "session:" ? "" : identity;
+}
+function mintNonce() {
+  return node_crypto.randomBytes(16).toString("hex");
+}
+class TabRegistry {
+  constructor(viewFactory, onRemove, onChanged) {
+    this.viewFactory = viewFactory;
+    this.onRemove = onRemove;
+    this.onChanged = onChanged;
+  }
+  tabs = /* @__PURE__ */ new Map();
+  nextTabId = 1;
+  activeTabId = null;
+  visible = true;
+  contentRect = null;
+  /** Tabs with a command in flight, keyed by tabId. See `lane`. */
+  busy = /* @__PURE__ */ new Set();
+  epochListeners = [];
+  // ---- creation, addressing, listing ---------------------------------------
+  /**
+   * Create a tab. A user tab becomes active (the user asked for it); an AGENT
+   * tab does NOT — design 11.4 requires that an agent `open` must never switch
+   * the tab the user is looking at, which is the extension's
+   * `chrome.tabs.create({active: false})` equivalent.
+   */
+  create(options) {
+    if (options.owner === "agent") this.assertAgentCapacity();
+    const tabId = this.nextTabId++;
+    const restored = options.restored === true;
+    const record = {
+      tabId,
+      view: this.viewFactory({ ...options, restored }, tabId),
+      // Design 7.3: a restored tab is the user's, full stop. An agent does not
+      // silently reclaim the tab it owned in a previous app run.
+      owner: restored ? "user" : options.owner,
+      sessionId: restored ? null : options.sessionId ?? null,
+      nonce: restored || options.owner === "user" ? null : mintNonce(),
+      handedTo: null,
+      restored,
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+      epoch: 0,
+      refs: {},
+      allocationId: options.allocationId ?? ""
+    };
+    this.tabs.set(tabId, record);
+    if (options.owner === "user" && !restored) this.activeTabId = tabId;
+    if (this.activeTabId === null) this.activeTabId = tabId;
+    this.applyLayout();
+    this.onChanged();
+    return record;
+  }
+  /** The cap check, in one place because TWO routes make a tab agent-owned:
+   * `create({owner: "agent"})` and a hand-over, which changes the owner of a tab
+   * the user created. Checking only the first let hand-overs push the
+   * agent-owned count past the cap, after which the next `open` was refused with
+   * "already driving 8 agent tabs" for tabs the user had handed over — the cap
+   * reported by `status` and the cap enforced on `open` disagreeing (N3). */
+  assertAgentCapacity() {
+    if (this.agentTabCount() < MAX_AGENT_TABS) return;
+    throw new BridgeCommandError(
+      "tab_limit",
+      `this host is already driving ${MAX_AGENT_TABS} agent tabs; close one first`,
+      { limit: MAX_AGENT_TABS }
+    );
+  }
+  /** Resolve a tab by its own id. */
+  get(tabId) {
+    return this.tabs.get(tabId);
+  }
+  list() {
+    return [...this.tabs.values()].sort((a, b) => a.tabId - b.tabId);
+  }
+  get activeTab() {
+    return this.activeTabId === null ? null : this.tabs.get(this.activeTabId) ?? null;
+  }
+  agentTabCount() {
+    return this.list().filter((record) => record.owner === "agent").length;
+  }
+  count() {
+    return this.tabs.size;
+  }
+  /**
+   * Resolve a surface token to a live tab, or refuse.
+   *
+   * This is the fail-closed gate every agent action goes through, and its
+   * refusals are the design's contract:
+   * - malformed token → `tab_closed` ("dropped the handle"): the session's
+   *   recovery is `open`, and inventing a different code for a typo would give
+   *   it nothing to act on;
+   * - unknown tab, or a nonce that does not match → `tab_closed`. A wrong nonce
+   *   is deliberately indistinguishable from a missing tab: saying "wrong
+   *   nonce" would confirm the tab exists, which is the one thing a guessed
+   *   handle must not learn;
+   * - a view whose webContents is already destroyed → the record is dropped
+   *   here and the same refusal is returned, so a handle that outlives its view
+   *   fails instead of driving something else.
+   */
+  requireSurface(token) {
+    const parsed = parseSurface(token);
+    if (!parsed) {
+      throw new BridgeCommandError(
+        "tab_closed",
+        "that browser tab is gone; dropped the handle. Use 'open' with a URL to get a new tab",
+        { reason: "malformed_handle" }
+      );
+    }
+    const record = this.tabs.get(parsed.tabId);
+    if (!record || !record.nonce || record.nonce !== parsed.nonce) {
+      throw new BridgeCommandError(
+        "tab_closed",
+        "that browser tab is gone; dropped the handle. Use 'open' with a URL to get a new tab",
+        { reason: "unknown_handle" }
+      );
+    }
+    if (record.view.webContents.isDestroyed()) {
+      this.forget(record.tabId);
+      throw new BridgeCommandError(
+        "tab_closed",
+        "that browser tab is gone; dropped the handle. Use 'open' with a URL to get a new tab",
+        { reason: "view_destroyed" }
+      );
+    }
+    return record;
+  }
+  /** Touch a tab driven by an agent, so `tabs` can order by recency. */
+  touch(record) {
+    record.lastUsedAt = Date.now();
+  }
+  // ---- hand-over (design 6.3) ---------------------------------------------
+  /**
+   * Hand a user tab to a session, minting its capability.
+   *
+   * The renderer never sees the nonce: this is the ONE place renderer authority
+   * becomes agent authority, and the nonce travels to the session through
+   * `tabs`, not back through the renderer.
+   */
+  handOver(tabId, rawSessionId) {
+    const record = this.tabs.get(tabId);
+    if (!record) throw new BridgeCommandError("tab_closed", "that tab is gone");
+    const sessionId2 = sessionIdOf(rawSessionId);
+    if (!sessionId2) {
+      throw new BridgeCommandError(
+        "internal",
+        "handing a tab over needs a session to hand it to"
+      );
+    }
+    if (record.owner !== "agent") this.assertAgentCapacity();
+    record.owner = "agent";
+    record.sessionId = sessionId2;
+    record.handedTo = sessionId2;
+    record.nonce = mintNonce();
+    record.epoch = 0;
+    record.refs = {};
+    this.onChanged();
+  }
+  /** Revoke a hand-over: nulls the nonce, so the session's next action on that
+   * handle gets the ordinary `tab_closed` refusal. */
+  revokeHandOver(tabId) {
+    const record = this.tabs.get(tabId);
+    if (!record) return;
+    record.nonce = null;
+    record.owner = "user";
+    record.sessionId = null;
+    record.handedTo = null;
+    this.onChanged();
+  }
+  /** Whether a session may drive this tab: its own agent tab, or one handed to
+   * it. Nothing else — a user tab with no hand-over has no nonce to present. */
+  mayDrive(record, sessionId2) {
+    return record.sessionId === sessionId2 && record.nonce !== null;
+  }
+  // ---- navigation epochs ---------------------------------------------------
+  /**
+   * Bump a tab's navigation epoch and drop its refs.
+   *
+   * Called on every top-level navigation (agent `open`/`goto` AND the user
+   * typing a URL, per design 6.4). It is what makes concurrent interaction safe
+   * rather than merely untested: a ref taken before the navigation belongs to a
+   * document that no longer exists, and `resolveRef` refuses it with
+   * `element_not_found` instead of clicking whatever now occupies that
+   * position.
+   */
+  bumpEpoch(tabId) {
+    const record = this.tabs.get(tabId);
+    if (!record) return;
+    record.epoch += 1;
+    for (const listener of this.epochListeners) listener(tabId, record.epoch);
+  }
+  /** Observe epoch changes (the CDP driver uses one to re-arm per-navigation
+   * event capture without the registry knowing what CDP is). */
+  onEpoch(listener) {
+    this.epochListeners.push(listener);
+  }
+  // ---- per-tab command lane (design 6.4) -----------------------------------
+  /**
+   * Run `fn` as the sole command on this tab, or refuse with `busy`.
+   *
+   * Serialised PER TAB, across sessions: the session side already serialises
+   * per session, but two sessions can target different tabs and one session can
+   * target one tab, so the host owns this queue. A second command on a busy tab
+   * is NOT quietly queued — it gets `busy` with the existing "retry this action
+   * once" copy, because a silent queue turns a 30 s budget into an unbounded
+   * wait and the agent has no way to tell the difference from a slow page.
+   */
+  async lane(tabId, fn) {
+    if (this.busy.has(tabId)) {
+      throw new BridgeCommandError(
+        "busy",
+        "this browser tab is busy with another command; retry this action once",
+        { tab: tabId }
+      );
+    }
+    this.busy.add(tabId);
+    try {
+      return await fn();
+    } finally {
+      this.busy.delete(tabId);
+    }
+  }
+  // ---- layout, visibility, activation --------------------------------------
+  /** The renderer owns layout (design 11.2): it measures its content area and
+   * reports it, and this applies it to the ACTIVE tab only. Every other tab
+   * keeps its own bounds but is hidden, so one rect authority serves N views. */
+  setContentRect(rect) {
+    this.contentRect = rect;
+    this.applyLayout();
+  }
+  /** Full-window overlays hide the view (design 11.3): a native view paints
+   * above all DOM, so an overlay is invisible unless the view goes away. */
+  setViewVisible(visible) {
+    this.visible = visible;
+    this.applyLayout();
+  }
+  activate(tabId) {
+    if (!this.tabs.has(tabId)) return;
+    this.activeTabId = tabId;
+    this.applyLayout();
+    this.onChanged();
+  }
+  applyLayout() {
+    const active = this.activeTabId === null ? null : this.tabs.get(this.activeTabId);
+    for (const record of this.tabs.values()) {
+      const isActive = record === active;
+      record.view.setVisible(isActive && this.visible);
+      if (isActive && this.contentRect) record.view.setBounds(this.contentRect);
+    }
+  }
+  // ---- removal -------------------------------------------------------------
+  /**
+   * Drop a tab and hand its webContents id to `onRemove`, which is where the
+   * debugger session, the log buffer and the child view are released.
+   *
+   * `forget` is the registry-local half, used by the fail-closed handle check
+   * where the caller has no cleanup work to do (the webContents is already
+   * destroyed) and by `destroy` below.
+   */
+  forget(tabId) {
+    const record = this.tabs.get(tabId);
+    if (!record) return void 0;
+    this.tabs.delete(tabId);
+    if (this.activeTabId === tabId) {
+      this.activeTabId = this.list().at(-1)?.tabId ?? null;
+    }
+    this.onChanged();
+    return record;
+  }
+  /** Destroy a tab: forget it, then release its resources. `onRemove` is
+   * called for every removal path so a tab can never be forgotten while its
+   * webContents, debugger session or log buffer leak (design 11.1: with
+   * `WebContentsView`, nothing destroys the webContents for you). */
+  destroy(tabId) {
+    const record = this.forget(tabId);
+    if (!record) return;
+    this.onRemove(record.tabId, record.view.webContents.id);
+  }
+  /** Every tab, destroyed. Called on host stop and app quit. */
+  destroyAll() {
+    for (const tabId of [...this.tabs.keys()]) this.destroy(tabId);
+  }
+  /** A debug/diagnostic projection: what `status` and `tabs` report, and what
+   * the renderer's strip renders. */
+  snapshot() {
+    return this.list().map((record) => {
+      const token = surfaceToken(record);
+      return {
+        tabId: record.tabId,
+        owner: record.owner,
+        sessionId: record.sessionId,
+        handedTo: record.handedTo,
+        restored: record.restored,
+        active: record.tabId === this.activeTabId,
+        url: record.view.webContents.isDestroyed() ? "" : record.view.webContents.getURL(),
+        title: record.view.webContents.isDestroyed() ? "" : record.view.webContents.getTitle(),
+        handle: token ? redactToken(token) : `ui:${record.tabId}:no-handle`
+      };
+    });
+  }
+}
+function openResult(record, extra = {}) {
+  const token = surfaceToken(record);
+  const page = pageOf(record.view);
+  return {
+    tab: token ?? "",
+    url: page.url,
+    title: page.title,
+    owner: record.owner,
+    restored: record.restored,
+    ...extra
+  };
+}
+async function open(ctx, params, requestId2) {
+  const requester = requesterOf(params, requestId2);
+  const handle2 = stringParam(params, "tab");
+  const rawUrl = stringParam(params, "url");
+  const url = rawUrl ? safeHttpUrl(rawUrl) : null;
+  const admission = url ? ctx.approvals.ensureTopLevelAccess(url, requester) : null;
+  const approved = (candidate) => url !== null && candidate.origin === url.origin || ctx.approvals.originAllowed(candidate);
+  if (handle2) {
+    const record2 = ctx.registry.requireSurface(handle2);
+    await ctx.cdp.attach(record2.view.webContents);
+    const page = url ? await navigateView(ctx, record2.view, url, requester, approved) : pageOf(record2.view);
+    ctx.registry.touch(record2);
+    ctx.onChanged();
+    return openResult(record2, {
+      ...page,
+      ...admission ? { via: admission.viaOnceGrant ? "once_grant" : "stored_grant" } : { resumed: true }
+    });
+  }
+  const record = ctx.registry.create({
+    owner: "agent",
+    sessionId: sessionIdOf$1(requester) || requester,
+    allocationId: stringParam(params, "allocation_id")
+  });
+  try {
+    await ctx.cdp.attach(record.view.webContents);
+    const page = url ? await navigateView(ctx, record.view, url, requester, approved) : pageOf(record.view);
+    ctx.registry.touch(record);
+    ctx.onChanged();
+    return openResult(record, {
+      ...page,
+      limit: MAX_AGENT_TABS
+    });
+  } catch (error) {
+    ctx.registry.destroy(record.tabId);
+    throw error;
+  }
+}
+async function goto(ctx, params, requestId2) {
+  const requester = requesterOf(params, requestId2);
+  const record = ctx.registry.requireSurface(params.tab);
+  const url = safeHttpUrl(stringParam(params, "url"));
+  const admission = ctx.approvals.ensureTopLevelAccess(url, requester);
+  const approved = (candidate) => candidate.origin === url.origin || ctx.approvals.originAllowed(candidate);
+  await ctx.cdp.attach(record.view.webContents);
+  const page = await navigateView(ctx, record.view, url, requester, approved);
+  ctx.registry.touch(record);
+  ctx.onChanged();
+  return {
+    ...page,
+    tab: surfaceToken(record) ?? "",
+    via: admission.viaOnceGrant ? "once_grant" : "stored_grant"
+  };
+}
+async function close(ctx, params) {
+  const handle2 = stringParam(params, "tab");
+  if (handle2) {
+    const record2 = ctx.registry.requireSurface(handle2);
+    const closed2 = surfaceToken(record2) ?? handle2;
+    ctx.registry.destroy(record2.tabId);
+    ctx.onChanged();
+    return { closed: closed2 };
+  }
+  const tabs2 = ctx.registry.list();
+  if (tabs2.length === 0) {
+    throw new BridgeCommandError("tab_closed", "no browser tab is open");
+  }
+  if (tabs2.length > 1) {
+    const redacted = tabs2.map((record2) => {
+      const token = surfaceToken(record2);
+      return token ? redactToken(token) : `ui:${record2.tabId}:no-handle`;
+    }).join(", ");
+    throw new BridgeCommandError(
+      "tab_ambiguous",
+      `several tabs are open (${redacted}) — pass the handle of the one to close`,
+      { tabs: tabs2.length }
+    );
+  }
+  const [record] = tabs2;
+  if (!record)
+    throw new BridgeCommandError("tab_closed", "no browser tab is open");
+  const closed = surfaceToken(record) ?? "";
+  ctx.registry.destroy(record.tabId);
+  ctx.onChanged();
+  return { closed };
+}
+async function tabs(ctx, params, requestId2) {
+  const requester = requesterOf(params, requestId2);
+  const sessionId2 = sessionIdOf$1(requester);
+  const entries = ctx.registry.list().map((record) => {
+    const token = surfaceToken(record);
+    const mine = !!token && ctx.registry.mayDrive(record, sessionId2);
+    const page = pageOf(record.view);
+    return {
+      tab: mine ? token : token ? redactToken(token) : "",
+      url: page.url,
+      title: page.title,
+      lastUsedAt: record.lastUsedAt,
+      createdAt: record.createdAt,
+      // Additive fields the tool ignores today; they are what PR 2's copy
+      // change reads to say "(handed to you)" instead of guessing from a
+      // prefix. Sending them now costs nothing and saves a second wire change.
+      owner: record.owner,
+      active: ctx.registry.activeTab?.tabId === record.tabId,
+      handed_to_you: record.handedTo !== null && record.handedTo === sessionId2,
+      restored: record.restored
+    };
+  });
+  return {
+    tabs: entries,
+    limit: MAX_AGENT_TABS,
+    agent_tabs: ctx.registry.agentTabCount(),
+    total: entries.length
+  };
+}
+async function status(ctx, params, requestId2) {
+  const requester = requesterOf(params, requestId2);
+  const sessionId2 = sessionIdOf$1(requester);
+  const facts = ctx.facts();
+  return {
+    proto: facts.proto,
+    host: "ui",
+    app_version: facts.appVersion,
+    profile_dir: facts.profileDir,
+    profile_persistent: facts.profilePersistent,
+    tabs: ctx.registry.count(),
+    agent_tabs: ctx.registry.agentTabCount(),
+    agent_limit: MAX_AGENT_TABS,
+    user_agent: facts.userAgent,
+    domain_scope: facts.domainScope,
+    approvals: ctx.approvals.describe(),
+    ownership: ctx.ownership.describe(),
+    surfaces: ctx.registry.snapshot().map((entry) => ({
+      tab: entry.handle,
+      url: entry.url,
+      title: entry.title,
+      owner: entry.owner,
+      active: entry.active,
+      restored: entry.restored,
+      handed_to_you: entry.handedTo === sessionId2
+    }))
+  };
+}
+function retitle() {
+  return {
+    state: "noop",
+    reason: "the browser tab is labelled with the page title"
+  };
+}
+const PROTO_VERSION = 1;
+const METHODS = [
+  "open",
+  "goto",
+  "read",
+  "snapshot",
+  "screenshot",
+  "click",
+  "type",
+  "close",
+  "status",
+  "tabs",
+  "scroll",
+  "logs",
+  "request_access",
+  "await_access",
+  "cancel_access",
+  "retitle",
+  "owner_recover",
+  "owner_finish",
+  "owner_retain",
+  "owner_release"
+];
+const METHOD_SET = new Set(METHODS);
+function isMethod(value) {
+  return typeof value === "string" && METHOD_SET.has(value);
+}
+const ERROR_CODES = [
+  "extension_disconnected",
+  "not_paired",
+  "tab_closed",
+  "nav_failed",
+  "nav_timeout",
+  "element_not_found",
+  "origin_denied",
+  "origin_prompt_pending",
+  "origin_not_allowed",
+  "debugger_conflict",
+  "access_queue_full",
+  "tab_limit",
+  "tab_ambiguous",
+  "busy",
+  "proto_mismatch",
+  "owner_refused",
+  "extension_unresponsive",
+  "internal"
+];
+const TAB_SCOPED = /* @__PURE__ */ new Set([
+  "goto",
+  "read",
+  "snapshot",
+  "screenshot",
+  "click",
+  "type",
+  "scroll",
+  "logs",
+  "close",
+  "retitle"
+]);
+class BrowserHost {
+  registry;
+  cdp;
+  approvals;
+  ownership;
+  log;
+  onChanged;
+  facts;
+  constructor(options) {
+    this.registry = options.registry;
+    this.cdp = options.cdp;
+    this.approvals = options.approvals;
+    this.ownership = options.ownership;
+    this.log = options.log;
+    this.onChanged = options.onChanged;
+    this.facts = options.facts;
+  }
+  /** Answer one wire request. The only place a method name becomes an action. */
+  async dispatch(method, params, requestId2) {
+    const run = () => this.ownership.withOwnership(
+      method,
+      params,
+      () => this.perform(method, params, requestId2)
+    );
+    if (TAB_SCOPED.has(method) && typeof params.tab === "string" && params.tab) {
+      const record = this.registry.requireSurface(params.tab);
+      return this.registry.lane(record.tabId, run);
+    }
+    return run();
+  }
+  async perform(method, params, requestId2) {
+    switch (method) {
+      case "open":
+        return open(this, params, requestId2);
+      case "goto":
+        return goto(this, params, requestId2);
+      case "close":
+        return close(this, params);
+      case "tabs":
+        return tabs(this, params, requestId2);
+      case "status":
+        return status(this, params, requestId2);
+      case "retitle":
+        return retitle();
+      case "read":
+        return read(this, params);
+      case "snapshot":
+        return snapshot(this, params);
+      case "scroll":
+        return scroll(this, params);
+      case "logs":
+        return logs(this, params);
+      case "screenshot":
+        return screenshot(this, params);
+      case "click":
+        return click(this, params);
+      case "type":
+        return type(this, params);
+      case "request_access":
+        return this.approvals.requestAccess(
+          params.url,
+          requesterOf(params, requestId2),
+          "async",
+          requestId2
+        );
+      case "await_access":
+        return this.awaitAccess(params, requestId2);
+      case "cancel_access":
+        return this.approvals.cancelAccess(
+          params.url,
+          requesterOf(params, requestId2)
+        );
+      case "owner_recover":
+      case "owner_finish":
+      case "owner_retain":
+      case "owner_release":
+        throw new BridgeCommandError(
+          "owner_refused",
+          `${method} is not answered by this host's ownership lane`
+        );
+      default:
+        throw new BridgeCommandError(
+          "internal",
+          `unsupported method '${method}'`
+        );
+    }
+  }
+  /**
+   * `await_access`: poll in bounded slices.
+   *
+   * The slice cap is the extension's `AWAIT_SLICE_MS` (20 s), and the caller's
+   * own `timeout_ms` may only shorten it. The session loops slices client-side,
+   * which is why this stays an honest per-RPC bound instead of blocking for as
+   * long as the user takes to answer.
+   */
+  async awaitAccess(params, requestId2) {
+    const requester = requesterOf(params, requestId2);
+    const requested = Number(params.timeout_ms);
+    const sliceMs = Math.min(
+      Number.isFinite(requested) && requested > 0 ? requested : AWAIT_SLICE_MS,
+      AWAIT_SLICE_MS
+    );
+    const deadlineAt = Date.now() + sliceMs;
+    for (; ; ) {
+      const current = this.approvals.accessStateFor(params.url, requester);
+      if (current.state !== "pending" || Date.now() >= deadlineAt)
+        return current;
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+  }
+  /** Bounded by the wire's own budget for this method, for the case where a
+   * caller asks for the whole slice. */
+  get awaitSliceMs() {
+    return AWAIT_SLICE_MS;
+  }
+  // ---- operations the app's own chrome uses (design 11.2, 6.1) -------------
+  /**
+   * The projection the renderer renders: the tab strip, the URL bar and the
+   * per-tab ownership markers. It never carries a nonce — the renderer is not an
+   * agent and has no reason to hold a capability (design 11.7).
+   */
+  chromeState() {
+    const activeRecord = this.registry.activeTab;
+    const active = activeRecord && !activeRecord.view.webContents.isDestroyed() ? activeRecord : null;
+    const navigation = active?.view.webContents.navigationHistory;
+    return {
+      tabs: this.registry.snapshot().map((entry) => ({
+        tabId: entry.tabId,
+        title: entry.title || "New tab",
+        url: entry.url,
+        owner: entry.owner,
+        active: entry.active,
+        restored: entry.restored,
+        handedOver: entry.handedTo !== null
+      })),
+      activeTabId: activeRecord?.tabId ?? null,
+      url: active ? active.view.webContents.getURL() : "",
+      title: active ? active.view.webContents.getTitle() : "",
+      loading: active ? active.view.webContents.isLoading() : false,
+      canGoBack: navigation ? navigation.canGoBack() : false,
+      canGoForward: navigation ? navigation.canGoForward() : false,
+      // The consent surface (PR 7) renders from this. Exposed now so the
+      // transport does not need a second wire change when it lands, and so an
+      // evidence run can answer a prompt headlessly.
+      pendingConsent: this.approvals.pendingEntries().map((entry) => ({
+        entryId: entry.entryId,
+        origin: entry.origin,
+        authority: entry.displayAuthority,
+        broad: entry.broad ?? null,
+        expiresAt: entry.expiresAt
+      }))
+    };
+  }
+  /** A user tab: created active, at about:blank, owned by the user and with no
+   * capability until the user hands it over (design 6.1, 6.3). */
+  async newTab() {
+    const record = this.registry.create({ owner: "user" });
+    await record.view.webContents.loadURL("about:blank");
+    await this.cdp.attach(record.view.webContents);
+    this.onChanged();
+    return this.chromeState();
+  }
+  closeTab(tabId) {
+    this.registry.destroy(tabId);
+    this.onChanged();
+    return this.chromeState();
+  }
+  activateTab(tabId) {
+    this.registry.activate(tabId);
+    this.onChanged();
+    return this.chromeState();
+  }
+  /**
+   * A URL the USER typed goes through here, and it is deliberately different from
+   * an agent navigation in one way and identical in another (design 6.1):
+   *
+   * - no origin gate, and no consent prompt: the user typing their own URL IS the
+   *   consent. An origin can therefore be reachable by the user and refused to the
+   *   agent, which is the intended direction of the gate and something the consent
+   *   copy must say in words rather than leave the user to infer.
+   * - the same scheme rule: non-`http(s)` input is refused, because allowing
+   *   `file:` or `javascript:` here would hand a page (or a paste) a way to reach
+   *   the local filesystem through the app's own URL bar.
+   */
+  async navigateActive(rawUrl) {
+    const record = this.registry.activeTab;
+    if (!record)
+      throw new BridgeCommandError("tab_closed", "no browser tab is open");
+    let url;
+    try {
+      url = new URL(rawUrl.includes("://") ? rawUrl : `https://${rawUrl}`);
+    } catch {
+      throw new BridgeCommandError("nav_failed", "that is not a URL");
+    }
+    if (!permittedScheme(url)) {
+      throw new BridgeCommandError(
+        "nav_failed",
+        "only http:// and https:// can be opened"
+      );
+    }
+    await record.view.webContents.loadURL(url.href);
+    this.onChanged();
+    return this.chromeState();
+  }
+  reloadActive() {
+    this.registry.activeTab?.view.webContents.reload();
+    return this.chromeState();
+  }
+  stopActive() {
+    this.registry.activeTab?.view.webContents.stop();
+    return this.chromeState();
+  }
+  historyActive(direction) {
+    const navigation = this.registry.activeTab?.view.webContents.navigationHistory;
+    if (navigation) {
+      if (direction === "back") navigation.goBack();
+      else navigation.goForward();
+    }
+    return this.chromeState();
+  }
+  /** Layout authority is the renderer's (design 11.2): it measures the content
+   * area and reports it, and main applies it to the active tab only. */
+  setContentRect(rect) {
+    this.registry.setContentRect(rect);
+    return this.chromeState();
+  }
+  /** Full-window overlays hide the view: a native view paints above all DOM, so
+   * an overlay is invisible unless the view goes away (design 11.3). */
+  setViewVisible(visible) {
+    this.registry.setViewVisible(visible);
+    return this.chromeState();
+  }
+  /** Hand a user tab to a session, minting the capability. The RENDERER never
+   * sees the nonce: it travels to the session through `tabs`, which is what keeps
+   * this the one authority transfer rather than an exposure (design 6.3, 11.7). */
+  handOver(tabId, sessionId2) {
+    this.registry.handOver(tabId, sessionId2);
+    this.onChanged();
+    return this.chromeState();
+  }
+  revokeHandOver(tabId) {
+    this.registry.revokeHandOver(tabId);
+    this.onChanged();
+    return this.chromeState();
+  }
+  /** Answer a pending consent prompt. Reached only from the renderer IPC, whose
+   * handler checks the sender first. */
+  respondToConsent(entryId, decision) {
+    const result = this.approvals.respond(entryId, decision);
+    this.onChanged();
+    return { ...result, ...this.chromeState() };
+  }
+  /** The registry's handles, for a diagnostic or the `tabs` listing. */
+  handleFor(record) {
+    const token = surfaceToken(record);
+    return token ? redactToken(token) : `ui:${record.tabId}:no-handle`;
+  }
+}
+const AWAIT_SLICE_MS = 2e4;
+const BROWSER_IPC_CHANNELS = [
+  "browser-state",
+  "browser-new-tab",
+  "browser-close-tab",
+  "browser-activate-tab",
+  "browser-navigate",
+  "browser-reload",
+  "browser-stop",
+  "browser-history",
+  "browser-set-content-rect",
+  "browser-set-visible",
+  "browser-hand-over",
+  "browser-revoke-hand-over",
+  "browser-consent-respond",
+  "browser-clear-data"
+];
+function registerBrowserIpc(options) {
+  function authorize(event) {
+    const owner = options.window();
+    if (!owner || owner.isDestroyed() || event.sender !== owner.webContents || event.senderFrame !== owner.webContents.mainFrame || !trustedDesktopFrame(event.senderFrame.url, options.expectedUrl)) {
+      throw new Error("This window cannot use the browser controls.");
+    }
+    const host = options.host();
+    if (!host) throw new Error("The browser host is not running.");
+    return host;
+  }
+  electron.ipcMain.handle("browser-state", (event) => authorize(event).chromeState());
+  electron.ipcMain.handle("browser-new-tab", async (event) => authorize(event).newTab());
+  electron.ipcMain.handle("browser-close-tab", (event, tabId) => {
+    const host = authorize(event);
+    return host.closeTab(numberOrThrow(tabId, "tabId"));
+  });
+  electron.ipcMain.handle("browser-activate-tab", (event, tabId) => {
+    const host = authorize(event);
+    return host.activateTab(numberOrThrow(tabId, "tabId"));
+  });
+  electron.ipcMain.handle("browser-navigate", async (event, url) => {
+    const host = authorize(event);
+    if (typeof url !== "string" || !url.trim()) {
+      throw new Error("A URL is required.");
+    }
+    return host.navigateActive(url.trim());
+  });
+  electron.ipcMain.handle("browser-reload", (event) => authorize(event).reloadActive());
+  electron.ipcMain.handle("browser-stop", (event) => authorize(event).stopActive());
+  electron.ipcMain.handle("browser-history", (event, direction) => {
+    const host = authorize(event);
+    if (direction !== "back" && direction !== "forward") {
+      throw new Error("History direction must be forward or back.");
+    }
+    return host.historyActive(direction);
+  });
+  electron.ipcMain.handle("browser-set-content-rect", (event, rect) => {
+    const host = authorize(event);
+    return host.setContentRect(contentRectOrNull(rect));
+  });
+  electron.ipcMain.handle("browser-set-visible", (event, visible) => {
+    const host = authorize(event);
+    if (typeof visible !== "boolean") {
+      throw new Error("Visibility must be a boolean.");
+    }
+    return host.setViewVisible(visible);
+  });
+  electron.ipcMain.handle(
+    "browser-hand-over",
+    (event, tabId, sessionId2) => {
+      const host = authorize(event);
+      if (typeof sessionId2 !== "string" || !sessionId2.trim()) {
+        throw new Error("Handing a tab over needs a session to hand it to.");
+      }
+      return host.handOver(numberOrThrow(tabId, "tabId"), sessionId2.trim());
+    }
+  );
+  electron.ipcMain.handle("browser-revoke-hand-over", (event, tabId) => {
+    const host = authorize(event);
+    return host.revokeHandOver(numberOrThrow(tabId, "tabId"));
+  });
+  electron.ipcMain.handle(
+    "browser-consent-respond",
+    (event, entryId, decision) => {
+      const host = authorize(event);
+      if (typeof entryId !== "string" || !entryId) {
+        throw new Error("A pending request id is required.");
+      }
+      if (decision !== "once" && decision !== "site" && decision !== "domain" && decision !== "deny") {
+        throw new Error("Unsupported consent decision.");
+      }
+      return host.respondToConsent(entryId, decision);
+    }
+  );
+  electron.ipcMain.handle("browser-clear-data", async (event, what) => {
+    authorize(event);
+    if (what !== "cookies" && what !== "cache" && what !== "everything") {
+      throw new Error("Unsupported clear-data request.");
+    }
+    await options.clearData(what);
+    options.log(`[browser] cleared browsing data: ${what}`);
+    return { cleared: what };
+  });
+}
+function unregisterBrowserIpc() {
+  for (const channel of BROWSER_IPC_CHANNELS) electron.ipcMain.removeHandler(channel);
+}
+function numberOrThrow(value, name) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer.`);
+  }
+  return value;
+}
+function contentRectOrNull(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "object")
+    throw new Error("Content rect must be an object.");
+  const rect = value;
+  for (const key of ["x", "y", "width", "height"]) {
+    if (typeof rect[key] !== "number" || !Number.isFinite(rect[key])) {
+      throw new Error("Content rect needs finite x, y, width and height.");
+    }
+  }
+  return {
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height
+  };
+}
+const PROOF_SHAPE = /^[a-zA-Z0-9_-]{32,}$/;
+const MISSING_PROOF_MESSAGE = "missing private browser ownership proof";
+class OwnershipLedger {
+  constructor(hooks) {
+    this.hooks = hooks;
+  }
+  scopes = /* @__PURE__ */ new Map();
+  /** Per-OWNER command lanes, keyed by `owner_proof`. The lane spans a handler
+   * deliberately: it is what stops a same-owner `owner_finish` overtaking its own
+   * in-flight `open` and letting a late navigation resurrect the tab. Per proof,
+   * so it starves nobody else. */
+  lanes = /* @__PURE__ */ new Map();
+  identity(params) {
+    const proof = String(params.owner_proof ?? "");
+    const session = String(params.requester ?? "");
+    const generation = String(params.owner_generation ?? "");
+    if (!PROOF_SHAPE.test(proof) || !session.startsWith("session:") || !generation) {
+      throw new BridgeCommandError("owner_refused", MISSING_PROOF_MESSAGE);
+    }
+    return [proof, session, generation];
+  }
+  /** The scope a proof names, after the session and generation checks. Creation
+   * is opt-in per method, matching the extension's `create` flag. */
+  mutate(params, fn, create = false) {
+    const [proof, session, generation] = this.identity(params);
+    let scope = this.scopes.get(proof);
+    if (!scope && create) {
+      scope = {
+        session,
+        generation,
+        allocations: {},
+        unknownReservations: 0
+      };
+      this.scopes.set(proof, scope);
+    }
+    if (!scope || scope.session !== session || scope.generation !== generation) {
+      throw new BridgeCommandError(
+        "owner_refused",
+        "browser owner generation is stale or unresolved"
+      );
+    }
+    return fn(scope);
+  }
+  /** Record (or clear) the tab an allocation owns. */
+  recordAllocation(params, tab, state) {
+    if (!params.owner_proof) return;
+    this.mutate(params, (scope) => {
+      const allocation = String(params.allocation_id ?? "");
+      if (!allocation) {
+        throw new BridgeCommandError("owner_refused", "browser scope ended");
+      }
+      if (scope.terminal) {
+        throw new BridgeCommandError("owner_refused", "browser scope ended");
+      }
+      scope.allocations[allocation] = { tab: tab || void 0, state };
+    });
+  }
+  /**
+   * Run a command under the ownership gate.
+   *
+   * The order of the checks is the extension's, and it matters: `open`'s
+   * allocation fence runs BEFORE the terminal check, because an `open` that
+   * replays an allocation the scope already knows must succeed even after the
+   * scope is resolved (that is exactly the lost-response case).
+   */
+  withOwnership(method, params, handler) {
+    const key = String(params.owner_proof ?? "legacy");
+    const previous = this.lanes.get(key) ?? Promise.resolve();
+    const operate = async () => {
+      if (!params.owner_proof) {
+        if (method.startsWith("owner_")) {
+          throw new BridgeCommandError("owner_refused", MISSING_PROOF_MESSAGE);
+        }
+        if (params.tab) {
+          const token = String(params.tab);
+          const scope2 = this.scopeOwning(token);
+          if (scope2?.allocations && this.tokenHasAllocation(token)) {
+            throw new BridgeCommandError(
+              "owner_refused",
+              "owner-aware client required"
+            );
+          }
+        }
+        return handler();
+      }
+      const [proof, session, generation] = this.identity(params);
+      if (method === "owner_recover") {
+        const scope2 = this.scopes.get(proof);
+        if (!scope2) return { ownership_version: 1, state: "unresolved" };
+        const predecessors = Array.isArray(params.previous_generations) ? params.previous_generations : [];
+        if (scope2.session !== session || scope2.generation !== generation && scope2.generation !== params.previous_generation && !predecessors.includes(scope2.generation)) {
+          throw new BridgeCommandError(
+            "owner_refused",
+            "browser owner generation is stale"
+          );
+        }
+        if (scope2.generation !== generation || params.resumed_scope === true) {
+          scope2.terminal = void 0;
+        }
+        scope2.generation = generation;
+        const allocation = scope2.allocations[String(params.allocation_id ?? "")];
+        const live = allocation?.tab ? this.hooks.isLive(allocation.tab) : false;
+        const unresolved = allocation && ["allocating", "allocated", "cleanup_pending"].includes(
+          allocation.state
+        );
+        return {
+          ownership_version: 1,
+          state: live ? allocation.state : unresolved ? "allocating" : "closed",
+          tab: live ? allocation.tab ?? "" : "",
+          retention: scope2.retention ?? "",
+          terminal: scope2.terminal ?? "",
+          unknown_reservations: scope2.unknownReservations
+        };
+      }
+      if (method === "open") {
+        const existing = this.mutate(
+          params,
+          (value) => {
+            if (value.terminal) {
+              throw new BridgeCommandError(
+                "owner_refused",
+                "browser scope ended; resume a new generation first"
+              );
+            }
+            const id2 = String(params.allocation_id ?? "");
+            if (!id2) {
+              throw new BridgeCommandError(
+                "owner_refused",
+                "missing browser allocation id"
+              );
+            }
+            return value.allocations[id2];
+          },
+          true
+        );
+        if (params.tab) {
+          if (existing?.tab !== params.tab) {
+            throw new BridgeCommandError(
+              "owner_refused",
+              "tab does not belong to allocation"
+            );
+          }
+          return handler();
+        }
+        if (existing?.tab && this.hooks.isLive(existing.tab)) {
+          return {
+            tab: existing.tab,
+            state: existing.state,
+            replayed: true
+          };
+        }
+        if (existing && existing.state !== "closed") {
+          this.mutate(params, (value) => {
+            value.unknownReservations += 1;
+          });
+        }
+        this.recordAllocation(params, "", "allocating");
+        return handler();
+      }
+      const scope = this.mutate(
+        params,
+        (value) => value,
+        [
+          "tabs",
+          "status",
+          "request_access",
+          "await_access",
+          "cancel_access",
+          "owner_retain",
+          "owner_finish"
+        ].includes(method)
+      );
+      if (method === "owner_retain") {
+        const reason = String(params.reason ?? "").trim();
+        if (!reason || reason.length > 500) {
+          throw new BridgeCommandError(
+            "owner_refused",
+            "retention requires a bounded reason"
+          );
+        }
+        this.mutate(params, (value) => {
+          value.retention = reason;
+        });
+        return { state: "retained" };
+      }
+      if (method === "owner_release") {
+        this.mutate(params, (value) => {
+          value.retention = void 0;
+        });
+        return { state: "released", terminal: scope.terminal ?? "" };
+      }
+      if (method === "owner_finish") {
+        const retained = scope.retention;
+        this.mutate(params, (value) => {
+          value.terminal = String(params.outcome ?? "completed");
+        });
+        if (retained) return { state: "retained" };
+        let pending = false;
+        for (const allocation of Object.values(scope.allocations)) {
+          if (!allocation.tab || !this.hooks.isLive(allocation.tab)) {
+            if (["allocating", "allocated", "cleanup_pending"].includes(
+              allocation.state
+            )) {
+              pending = true;
+            }
+            continue;
+          }
+          const closed = await this.hooks.closeTab(allocation.tab);
+          if (!closed) pending = true;
+        }
+        return { state: pending ? "pending" : "closed" };
+      }
+      if (scope.terminal && method !== "close" && method !== "tabs") {
+        throw new BridgeCommandError("owner_refused", "browser scope ended");
+      }
+      if (params.tab && !Object.values(scope.allocations).some(
+        (allocation) => allocation.tab === params.tab
+      )) {
+        throw new BridgeCommandError(
+          "owner_refused",
+          "tab does not belong to this browser owner"
+        );
+      }
+      return handler();
+    };
+    const run = previous.catch(() => {
+    }).then(operate);
+    this.lanes.set(key, run);
+    void run.finally(() => {
+      if (this.lanes.get(key) === run) this.lanes.delete(key);
+    }).catch(() => {
+    });
+    return run;
+  }
+  /** The scope a token belongs to, if any (legacy-path fencing only). */
+  scopeOwning(token) {
+    for (const scope of this.scopes.values()) {
+      if (Object.values(scope.allocations).some((a) => a.tab === token)) {
+        return scope;
+      }
+    }
+    return void 0;
+  }
+  tokenHasAllocation(token) {
+    return this.scopeOwning(token) !== void 0;
+  }
+  /** Forget every scope. Called when the host stops, so a restart cannot
+   * half-remember a previous process's tabs. */
+  clear() {
+    this.scopes.clear();
+  }
+  /** Diagnostic counts for `status`. */
+  describe() {
+    let retained = 0;
+    let terminal = 0;
+    for (const scope of this.scopes.values()) {
+      if (scope.retention) retained += 1;
+      if (scope.terminal) terminal += 1;
+    }
+    return { scopes: this.scopes.size, retained, terminal };
+  }
+}
+const BROWSER_PARTITION = "persist:local-operator-browser";
+function browserUserAgent() {
+  const chrome = process.versions.chrome ?? "0";
+  const platform = process.platform === "darwin" ? "Macintosh; Intel Mac OS X 10_15_7" : process.platform === "win32" ? "Windows NT 10.0; Win64; x64" : "X11; Linux x86_64";
+  return `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chrome} Safari/537.36 LocalOperator/${electron.app.getVersion()}`;
+}
+function resolveBrowserSession() {
+  return electron.session.fromPartition(BROWSER_PARTITION);
+}
+function browserStoragePath(browserSession) {
+  return browserSession.getStoragePath();
+}
+function installBrowserSessionHandlers(browserSession, hooks = {}) {
+  browserSession.setUserAgent(browserUserAgent());
+  browserSession.setPermissionRequestHandler(
+    (_webContents, permission, callback, details) => {
+      hooks.onPermissionRequested?.({
+        webContentsId: -1,
+        origin: typeof details?.requestingUrl === "string" ? details.requestingUrl : "",
+        permission
+      });
+      callback(false);
+    }
+  );
+  browserSession.setPermissionCheckHandler(
+    (_webContents, permission, requestingOrigin, details) => {
+      hooks.onPermissionRequested?.({
+        webContentsId: -1,
+        // Electron calls this handler with an empty origin during the
+        // per-webContents startup probes (media, geolocation, app install), so the
+        // documented `requestingUrl` is preferred when it is there: an
+        // "(unknown origin)" line for a probe the PAGE caused is exactly the line
+        // somebody needs when a site's permission stops working.
+        origin: requestingOrigin || details?.requestingUrl || "",
+        permission
+      });
+      return false;
+    }
+  );
+  browserSession.on("will-download", (event, item) => {
+    event.preventDefault();
+    hooks.onDownloadAttempted?.({
+      webContentsId: -1,
+      url: item.getURL()
+    });
+    hooks.log?.(
+      `[browser] cancelled a download from ${item.getURL()}: background downloads are not supported`
+    );
+  });
+}
+async function clearBrowsingData(browserSession, what) {
+  browserSession.flushStorageData();
+  if (what === "cache") {
+    await browserSession.clearCache();
+    return;
+  }
+  if (what === "cookies") {
+    await browserSession.clearData({
+      dataTypes: [
+        "cookies",
+        "localStorage",
+        "indexedDB",
+        "serviceWorkers",
+        "fileSystems",
+        "webSQL",
+        "backgroundFetch"
+      ]
+    });
+    return;
+  }
+  await browserSession.clearData();
+  await browserSession.clearCache();
+}
+function flushBrowserStorage(browserSession) {
+  try {
+    browserSession.flushStorageData();
+  } catch {
+  }
+}
+const RUN_DIRNAME = path$1.join("run", "ui-browser");
+const STATE_FILENAME = "host.json";
+const STATE_DIR_MODE = 448;
+const STATE_FILE_MODE = 384;
+const HEARTBEAT_INTERVAL_MS = 15e3;
+function localOperatorConfigDir() {
+  const configured = process.env.LOCAL_OPERATOR_CONFIG_DIR?.trim();
+  if (configured) return configured;
+  return path$1.join(os.homedir(), ".local-operator");
+}
+function stateFilePath(root = localOperatorConfigDir()) {
+  return path$1.join(root, RUN_DIRNAME, STATE_FILENAME);
+}
+function mintSessionKey() {
+  return node_crypto.randomBytes(32).toString("base64url");
+}
+function keysMatch(presented, expected) {
+  if (typeof presented !== "string") return false;
+  const a = Buffer.from(presented, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  if (a.length !== b.length) return false;
+  return node_crypto.timingSafeEqual(a, b);
+}
+class BrowserStateWriter {
+  constructor(path2, facts, options) {
+    this.path = path2;
+    this.facts = facts;
+    this.now = options.now ?? Date.now;
+    this.onError = options.onError ?? (() => {
+    });
+    this.appVersion = options.appVersion;
+  }
+  now;
+  onError;
+  timer = null;
+  written = false;
+  appVersion;
+  /** Publish the record and start the heartbeat. The heartbeat is the
+   * difference between "the app is running and can open a tab on demand" and a
+   * record that names a process that died without cleaning up. */
+  start(port, sessionKey) {
+    const startedAt = this.now() / 1e3;
+    this.startedAt = startedAt;
+    this.port = port;
+    this.sessionKey = sessionKey;
+    this.write();
+    this.timer = setInterval(() => this.write(), HEARTBEAT_INTERVAL_MS);
+    this.timer.unref?.();
+  }
+  startedAt = 0;
+  port = 0;
+  sessionKey = "";
+  /** Re-publish immediately, without waiting for the next heartbeat. Called
+   * when something the record reports has changed (a tab opened or closed). */
+  publishNow() {
+    if (this.port === 0) return;
+    this.write();
+  }
+  write() {
+    try {
+      const facts = this.facts();
+      const state = {
+        pid: process.pid,
+        port: this.port,
+        session_key: this.sessionKey,
+        proto: PROTO_VERSION,
+        host: "ui",
+        app_version: this.appVersion,
+        profile_dir: facts.profileDir,
+        tabs: facts.tabs,
+        agent_tabs: facts.agentTabs,
+        heartbeat_at: this.now() / 1e3,
+        started_at: this.startedAt || this.now() / 1e3
+      };
+      fs.mkdirSync(path$1.dirname(this.path), {
+        recursive: true,
+        mode: STATE_DIR_MODE
+      });
+      const staged = `${this.path}.${process.pid}.tmp`;
+      fs.writeFileSync(staged, `${JSON.stringify(state, null, 2)}
+`, {
+        mode: STATE_FILE_MODE
+      });
+      fs.renameSync(staged, this.path);
+      enforceStateFileModes(this.path);
+      this.written = true;
+    } catch (error) {
+      this.onError(error);
+    }
+  }
+  /** Remove the record, so discovery is honest when the host is gone. Called on
+   * host stop, on quit, and by the Settings toggle that turns the host off. */
+  clear() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (!this.written) return;
+    try {
+      fs.unlinkSync(this.path);
+    } catch (error) {
+      this.onError(error);
+    }
+    this.written = false;
+  }
+}
+function enforceStateFileModes(path2) {
+  try {
+    fs.chmodSync(path$1.dirname(path2), STATE_DIR_MODE);
+    fs.chmodSync(path2, STATE_FILE_MODE);
+  } catch {
+  }
+}
+const RPC_PATH = "/rpc";
+const HEALTH_PATH = "/health";
+const KEY_HEADER = "x-bridge-key";
+const MAX_BODY_BYTES = 1 << 20;
+const LOOPBACK_HOST = "127.0.0.1";
+function send(res, status2, body, contentType = "application/json") {
+  res.writeHead(status2, {
+    "Content-Type": contentType,
+    "Cache-Control": "no-store"
+  });
+  res.end(typeof body === "string" ? body : JSON.stringify(body));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error("body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+function errorResponse(id2, error) {
+  if (error instanceof BridgeCommandError) {
+    const known = ERROR_CODES.includes(error.code);
+    return {
+      id: id2,
+      ok: false,
+      error: {
+        code: known ? error.code : "internal",
+        message: known ? error.message : `${error.message} (unmapped code: ${error.code})`,
+        data: errorData(error)
+      }
+    };
+  }
+  return {
+    id: id2,
+    ok: false,
+    error: {
+      code: "internal",
+      message: error instanceof Error ? error.message : String(error),
+      data: {}
+    }
+  };
+}
+function validateRequest(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new BridgeCommandError(
+      "internal",
+      "request envelope must be an object"
+    );
+  }
+  const envelope = raw;
+  for (const key of Object.keys(envelope)) {
+    if (key !== "id" && key !== "method" && key !== "params") {
+      throw new BridgeCommandError("internal", `unknown envelope field '${key}'`);
+    }
+  }
+  if (typeof envelope.id !== "string" || !envelope.id) {
+    throw new BridgeCommandError(
+      "internal",
+      "request envelope needs a string id"
+    );
+  }
+  if (!isMethod(envelope.method)) {
+    throw new BridgeCommandError(
+      "internal",
+      `unknown method '${String(envelope.method)}'`
+    );
+  }
+  const params = envelope.params ?? {};
+  if (typeof params !== "object" || params === null || Array.isArray(params)) {
+    throw new BridgeCommandError("internal", "params must be an object");
+  }
+  return {
+    id: envelope.id,
+    method: envelope.method,
+    params
+  };
+}
+async function startRpcServer(options) {
+  const server = node_http.createServer((req, res) => {
+    void handle(req, res, options);
+  });
+  const bound = await new Promise(
+    (resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, LOOPBACK_HOST, () => {
+        const address = server.address();
+        if (address && typeof address === "object") {
+          resolve({ address: address.address, port: address.port });
+        } else reject(new Error("loopback listener has no port"));
+      });
+    }
+  );
+  return {
+    address: bound.address,
+    port: bound.port,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    })
+  };
+}
+async function handle(req, res, options) {
+  const url = req.url ?? "";
+  try {
+    if (req.method === "GET" && url.split("?")[0] === HEALTH_PATH) {
+      const body = {
+        host: "ui",
+        proto: PROTO_VERSION,
+        pid: process.pid
+      };
+      send(res, 200, body);
+      return;
+    }
+    if (req.method !== "POST" || url.split("?")[0] !== RPC_PATH) {
+      send(res, 404, { detail: "not found" });
+      return;
+    }
+    const presented = req.headers[KEY_HEADER];
+    if (!keysMatch(
+      Array.isArray(presented) ? presented[0] : presented,
+      options.key
+    )) {
+      send(res, 401, { detail: "unauthorized" });
+      return;
+    }
+    let raw;
+    try {
+      raw = JSON.parse(await readBody(req));
+    } catch {
+      send(res, 422, { detail: "malformed request body" });
+      return;
+    }
+    let request;
+    try {
+      request = validateRequest(raw);
+    } catch (error) {
+      send(res, 422, {
+        detail: error instanceof Error ? error.message : "invalid envelope"
+      });
+      return;
+    }
+    let response;
+    try {
+      const result = await options.dispatch(
+        request.method,
+        request.params,
+        request.id
+      );
+      response = { id: request.id, ok: true, result };
+    } catch (error) {
+      response = errorResponse(request.id, error);
+    }
+    send(res, 200, response);
+  } catch (error) {
+    options.log?.(
+      `[browser] rpc handler failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    if (!res.headersSent) {
+      send(res, 500, { detail: "internal error" });
+    } else {
+      res.end();
+    }
+  }
+}
+const HTTP_SCHEME = /^https?:/i;
+let activeHost = null;
+async function stopBrowserHost() {
+  const handle2 = activeHost;
+  activeHost = null;
+  if (handle2) await handle2.stop();
+}
+function browserHostEnabled(env = process.env) {
+  const flag = env.LOCAL_OPERATOR_UI_BROWSER_HOST?.trim().toLowerCase();
+  return !(flag === "0" || flag === "false" || flag === "off");
+}
+async function startBrowserHost(options) {
+  const { log } = options;
+  const browserSession = resolveBrowserSession();
+  installBrowserSessionHandlers(browserSession, {
+    onPermissionRequested: (details) => {
+      log(
+        `[browser] denied a ${details.permission} permission request from ${details.origin || "(unknown origin)"}`
+      );
+    },
+    onDownloadAttempted: (details) => {
+      log(`[browser] refused a download from ${details.url}`);
+    },
+    log
+  });
+  configurePslRules(readOptionalPslRules(options.userDataDir, log));
+  const cdp = new CdpPool({ log });
+  const views = /* @__PURE__ */ new Map();
+  let stateWriter = null;
+  const notifyChanged = () => {
+    stateWriter?.publishNow();
+    options.window.webContents.send("browser-state-changed");
+  };
+  const registry = new TabRegistry(
+    (_createOptions, tabId) => {
+      const view = buildView(options.window);
+      views.set(tabId, view);
+      wireView(view, tabId);
+      return view;
+    },
+    releaseTab,
+    notifyChanged
+  );
+  function releaseTab(tabId, webContentsId) {
+    const view = views.get(tabId);
+    views.delete(tabId);
+    void cdp.detach(webContentsId).finally(() => {
+      releaseView(options.window, view);
+    });
+  }
+  const ownership = new OwnershipLedger({
+    closeTab: async (token) => {
+      try {
+        const record = registry.requireSurface(token);
+        registry.destroy(record.tabId);
+      } catch {
+      }
+      return true;
+    },
+    isLive: (token) => {
+      try {
+        registry.requireSurface(token);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  });
+  const approvals = new ApprovalStore({
+    dir: path$1.join(options.userDataDir, "browser"),
+    onChanged: () => {
+      options.window.webContents.send("browser-consent-changed");
+    },
+    log
+  });
+  const profileDir = browserStoragePath(browserSession) ?? "";
+  const facts = {
+    proto: 1,
+    appVersion: options.appVersion,
+    profileDir,
+    profilePersistent: browserSession.isPersistent(),
+    userAgent: browserUserAgent(),
+    domainScope: domainScopeAvailable()
+  };
+  const host = new BrowserHost({
+    registry,
+    cdp,
+    approvals,
+    ownership,
+    log,
+    onChanged: notifyChanged,
+    facts: () => facts
+  });
+  const sessionKey = mintSessionKey();
+  const server = await startRpcServer({
+    key: sessionKey,
+    dispatch: (method, params, requestId2) => host.dispatch(method, params, requestId2),
+    log
+  });
+  stateWriter = new BrowserStateWriter(
+    stateFilePath(),
+    () => ({
+      tabs: registry.count(),
+      agentTabs: registry.agentTabCount(),
+      profileDir
+    }),
+    {
+      appVersion: options.appVersion,
+      onError: (error) => log(`[browser] state file: ${String(error)}`)
+    }
+  );
+  stateWriter.start(server.port, sessionKey);
+  registerBrowserIpc({
+    window: () => options.window,
+    expectedUrl: options.expectedUrl,
+    host: () => host,
+    clearData: (what) => clearBrowsingData(browserSession, what),
+    log
+  });
+  log(
+    `[browser] host on ${server.address}:${server.port} (proto ${facts.proto}), profile ${profileDir || "(in-memory)"}, agent tabs ${registry.agentTabCount()}/${8}`
+  );
+  const handle2 = {
+    host,
+    port: server.port,
+    profileDir,
+    agentTabs: () => registry.agentTabCount(),
+    stop: async () => {
+      registry.destroyAll();
+      await cdp.close();
+      await server.close();
+      unregisterBrowserIpc();
+      stateWriter?.clear();
+      approvals.resetPending();
+      ownership.clear();
+      flushBrowserStorage(browserSession);
+      log("[browser] host stopped");
+    }
+  };
+  activeHost = handle2;
+  return handle2;
+  function buildView(window) {
+    const view = new electron.WebContentsView({
+      webPreferences: {
+        partition: BROWSER_PARTITION,
+        contextIsolation: true,
+        nodeIntegration: false,
+        webSecurity: true,
+        allowRunningInsecureContent: false,
+        sandbox: true
+        // No `preload`: a driven page has no bridge to anything.
+      }
+    });
+    window.contentView.addChildView(view);
+    view.setVisible(false);
+    return view;
+  }
+  function wireView(view, tabId) {
+    const contents = view.webContents;
+    contents.setWindowOpenHandler((details) => {
+      if (HTTP_SCHEME.test(details.url)) {
+        log(
+          `[browser] blocked a popup from a driven page: ${details.url} (offered to the user rather than opened)`
+        );
+        options.window.webContents.send("browser-popup-blocked", {
+          tabId,
+          url: details.url
+        });
+      } else {
+        log(`[browser] blocked a non-http popup: ${details.url}`);
+      }
+      return { action: "deny" };
+    });
+    const refuses = (rawUrl) => {
+      try {
+        const url = new URL(rawUrl);
+        if (url.protocol === "about:") return url.href !== "about:blank";
+        return !permittedScheme(url);
+      } catch {
+        return true;
+      }
+    };
+    const onWillNavigate = (event, rawUrl) => {
+      if (refuses(rawUrl)) {
+        event.preventDefault();
+        log(`[browser] refused a navigation to ${rawUrl}`);
+      }
+    };
+    contents.on("will-navigate", onWillNavigate);
+    contents.on("will-redirect", onWillNavigate);
+    contents.on("will-attach-webview", (event) => {
+      event.preventDefault();
+      log("[browser] refused a webview attachment inside a driven page");
+    });
+    contents.on("did-navigate", (_event, url) => {
+      registry.bumpEpoch(tabId);
+      log(`[browser] tab ${tabId} navigated to ${url}`);
+    });
+    contents.on("did-navigate-in-page", (_event, url) => {
+      registry.bumpEpoch(tabId);
+      log(`[browser] tab ${tabId} navigated in page to ${url}`);
+    });
+    contents.on("destroyed", () => {
+      if (registry.get(tabId)) registry.forget(tabId);
+      releaseTab(tabId, contents.id);
+    });
+  }
+}
+function releaseView(window, view) {
+  if (!view) return;
+  try {
+    if (!view.webContents.isDestroyed()) view.webContents.close();
+  } catch {
+  }
+  try {
+    window.contentView.removeChildView(view);
+  } catch {
+  }
+}
+function readOptionalPslRules(userDataDir, log) {
+  try {
+    const path2 = path$1.join(userDataDir, "browser", "psl.txt");
+    if (!fs.existsSync(path2)) return null;
+    const rules2 = fs.readFileSync(path2, "utf8");
+    log(`[browser] loaded public-suffix rules from ${path2}`);
+    return rules2;
+  } catch (error) {
+    log(`[browser] could not load public-suffix rules: ${String(error)}`);
+    return null;
+  }
+}
 const OPERATION_ID = /^[a-zA-Z0-9_-]{1,128}$/;
-function guardForegroundReceipts(window, send) {
+function guardForegroundReceipts(window, send2) {
   return (input) => {
     if (input !== null && typeof input === "object" && "op" in input && input.op === "sessions.seen") {
       const owner = window();
@@ -4011,7 +7463,7 @@ function guardForegroundReceipts(window, send) {
         );
       }
     }
-    return send(input);
+    return send2(input);
   };
 }
 function relayedBytes(value) {
@@ -4101,7 +7553,7 @@ function registerDesktopIPC(window, expectedUrl, request, streams, media, notifi
       }
       const sender = event.sender;
       const relay = streams();
-      const handle = relay.subscribe(
+      const handle2 = relay.subscribe(
         {
           sessionId: input.sessionId,
           epoch: input.epoch,
@@ -4109,13 +7561,13 @@ function registerDesktopIPC(window, expectedUrl, request, streams, media, notifi
         },
         (frame) => {
           if (sender.isDestroyed()) {
-            relay.unsubscribe(handle.streamId);
+            relay.unsubscribe(handle2.streamId);
             return;
           }
           sender.send("desktop-stream-event", frame);
         }
       );
-      return handle;
+      return handle2;
     });
     electron.ipcMain.handle("desktop-stream-unsubscribe", (event, streamId) => {
       authorize(event);
@@ -4563,8 +8015,8 @@ class DesktopNotifier {
    * still re-words nothing (design 8.4). Gates pass `status = ""` and are
    * unaffected either way.
    */
-  show(sessionId2, title, status, body, isSnippet = false, isFailure = false) {
-    const lead = (isSnippet || isFailure) && status ? `${status} — ` : "";
+  show(sessionId2, title, status2, body, isSnippet = false, isFailure = false) {
+    const lead = (isSnippet || isFailure) && status2 ? `${status2} — ` : "";
     const notification = new electron.Notification({
       title,
       body: `${lead}${body}`.slice(0, MAX_BODY_CHARS),
@@ -5410,7 +8862,7 @@ exit 0
 function removeStagedTree(input) {
   const attempts = input.attempts ?? 3;
   const delayMs = input.delayMs ?? 250;
-  const sleep = input.sleep ?? defaultSleep;
+  const sleep2 = input.sleep ?? defaultSleep;
   let error = null;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
@@ -5421,7 +8873,7 @@ function removeStagedTree(input) {
     if (!input.exists(input.path)) {
       return { removed: true, attempts: attempt, error: null };
     }
-    if (attempt < attempts) sleep(delayMs);
+    if (attempt < attempts) sleep2(delayMs);
   }
   return {
     removed: false,
@@ -7700,9 +11152,9 @@ ${heal.removed.join("\n")}`,
    * the caller reports as a failure rather than as a completed update.
    */
   async waitForBackendVersion(target2, timeoutMs = 6e4, intervalMs = 2e3) {
-    const deadline = Date.now() + timeoutMs;
+    const deadline2 = Date.now() + timeoutMs;
     let last = null;
-    while (Date.now() < deadline) {
+    while (Date.now() < deadline2) {
       const version = await this.getInstalledBackendVersion();
       if (version && version !== "Unknown") {
         last = version;
@@ -8552,9 +12004,10 @@ electron.app.whenReady().then(async () => {
     } catch {
     }
   });
+  const rendererUrl = process.env.ELECTRON_RENDERER_URL || node_url.pathToFileURL(path$1.join(__dirname, "../renderer/index.html")).href;
   registerDesktopIPC(
     () => mainWindow,
-    process.env.ELECTRON_RENDERER_URL || node_url.pathToFileURL(path$1.join(__dirname, "../renderer/index.html")).href,
+    rendererUrl,
     sendDesktop,
     () => backendService.getStreamRelay(),
     (input, bytes) => backendService.requestDesktopMedia(input, bytes),
@@ -8921,10 +12374,36 @@ electron.app.whenReady().then(async () => {
       }
     });
   }
+  let browserHostRunning = false;
+  async function startBrowserHostForWindow(window) {
+    if (browserHostRunning || !browserHostEnabled()) return;
+    browserHostRunning = true;
+    window.on("closed", () => {
+      browserHostRunning = false;
+      void stopBrowserHost();
+    });
+    try {
+      await startBrowserHost({
+        window,
+        expectedUrl: rendererUrl,
+        appVersion: electron.app.getVersion(),
+        userDataDir: electron.app.getPath("userData"),
+        log: (message) => logger.info(message, LogFileType.BACKEND)
+      });
+    } catch (error) {
+      browserHostRunning = false;
+      logger.error(
+        `Could not start the browser host: ${String(error)}`,
+        LogFileType.BACKEND
+      );
+    }
+  }
   setupMainWindowWithUpdateService();
+  if (mainWindow) await startBrowserHostForWindow(mainWindow);
   electron.app.on("activate", () => {
     if (electron.BrowserWindow.getAllWindows().length === 0) {
       setupMainWindowWithUpdateService();
+      if (mainWindow) void startBrowserHostForWindow(mainWindow);
     }
   });
 }).catch((error) => {
@@ -9116,6 +12595,7 @@ electron.app.on("before-quit", () => {
   logger.info("App is about to quit", LogFileType.BACKEND);
   electron.globalShortcut.unregisterAll();
   activeUpdateService?.quitForInFlightInstall("app quit");
+  void stopBrowserHost();
 });
 process.on("exit", () => {
   logger.info(