local-operator-ui 0.23.1 → 0.23.3

package/out/main/index.js

@@ -13,6 +13,8 @@ const os = require("node:os");
 const node_util = require("node:util");
 const dotenv = require("dotenv");
 const electronLog = require("electron-log");
+const promises = require("node:fs/promises");
+const node_net = require("node:net");
 const node_http = require("node:http");
 const https = require("node:https");
 const electronUpdater = require("electron-updater");
@@ -84,7 +86,16 @@ const teamFields = zod.z.object({
 }).strict();
 const chains = zod.z.record(zod.z.array(zod.z.string().max(1024)).max(100));
 const scheduleUnit = zod.z.enum(["minutes", "hours", "days"]);
-const variableKey = zod.z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
+function isAddressableVariableKey(key) {
+  return !/^\.+$/.test(key);
+}
+const variableKey = zod.z.string().min(1).max(128).refine(
+  (key) => [...key].every(
+    (character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127 && character !== "/" && character !== "\\"
+  )
+).refine(isAddressableVariableKey);
+const variableType = zod.z.enum(["str", "int", "float", "bool", "list", "dict"]);
+const variableValue = zod.z.string().max(16384);
 const scheduleWrite = zod.z.object({
   is_active: zod.z.boolean().nullish(),
   one_time: zod.z.boolean().nullish(),
@@ -278,6 +289,89 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
   // `desktopRequestByteBudget`. Firing it costs the control budget and a
   // 2-byte body, which is what lets the renderer issue it from a keystroke.
   zod.z.object({ op: zod.z.literal("sessions.warm"), sessionId }).strict(),
+  /*
+   * A session's code memory: the names the session's own cells have left in its
+   * eval namespace.
+   *
+   * Session-addressed, because the runtime is what holds a namespace and the
+   * kernel it lives in is keyed by session id. The legacy
+   * `/v1/agents/{id}/execution-variables` route answered through the agent
+   * registry instead, which resolves agent-directory UUIDs - so a canonical
+   * session id could only ever 404 there, and the panel that taught "code
+   * memory" never loaded once.
+   */
+  zod.z.object({ op: zod.z.literal("sessions.variables.list"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.create"),
+    sessionId,
+    key: variableKey,
+    value: variableValue,
+    type: variableType
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.update"),
+    sessionId,
+    key: variableKey,
+    value: variableValue,
+    type: variableType
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.delete"),
+    sessionId,
+    key: variableKey
+  }).strict(),
+  // Machine-wide desktop presence. NOT a watch lease and deliberately not
+  // shaped like one: it names no session, because the fact it carries is
+  // "somebody is at this machine's screen and this app can raise a banner",
+  // which is a property of the app rather than of any conversation. The
+  // backend reads it to decide whether a BACKGROUND completion is worth a
+  // banner here at all (a session runtime with no surface to present on
+  // otherwise toasts on its own host, where nobody may be).
+  //
+  // `subscription_id` is the LIVE feed subscription the presence belongs to,
+  // not a per-session watch subscription: the server holds the lease against
+  // that socket, so a dropped feed revokes the claim without waiting for a
+  // heartbeat to go stale. That is the whole reason presence is a route on the
+  // feed rather than a local file - a desktop paired to a backend on another
+  // host cannot write to that host's disk.
+  zod.z.object({
+    op: zod.z.literal("sessions.presence"),
+    subscriptionId: zod.z.string().regex(/^[a-f0-9]{1,64}$/),
+    canNotify: zod.z.boolean(),
+    /*
+     * WHY THE CLAIM CARRIES MORE THAN "a desktop is connected".
+     *
+     * The backend's delivery lease answers two separate questions from
+     * this one beat, and a claim that names neither is a claim that
+     * delivers NOTHING:
+     *
+     * - `can_notify_kinds` is what `delivers(kind)` reads. Empty (the
+     *   default for a client that forgot) means rung 2 is never eligible
+     *   for any completion, so rung 4 raises the runtime's own banner —
+     *   earlier, and its claim advances the read watermark, so the
+     *   clickable banner this app exists to raise never composes.
+     *   The backend's own test for this is
+     *   `test_a_claim_with_no_kinds_claims_nothing`: an app that does not
+     *   advertise must not win the rung.
+     * - `window` (with `session_id`) is what `attended` reads. Without it
+     *   this app counts as watching NOTHING, so a completion in the
+     *   conversation on screen raises a banner — the inverse of rung 1,
+     *   and a regression against the per-session flag it replaces.
+     *
+     * `window` is sent even when there is no window: a windowless app
+     * (macOS, alive in the dock) can still raise a banner but cannot be
+     * displaying anything, which is why `session_id` must be "" there
+     * rather than the last conversation the closed window held.
+     */
+    canNotifyKinds: zod.z.array(zod.z.enum(["complete", "error"])).max(4),
+    sessionId: zod.z.string().regex(/^([a-f0-9]{12})?$/),
+    window: zod.z.object({
+      exists: zod.z.boolean(),
+      focused: zod.z.boolean(),
+      visible: zod.z.boolean(),
+      minimized: zod.z.boolean()
+    }).strict()
+  }).strict(),
   // The legacy surface, reached through the same authenticated vocabulary as
   // everything else. These routes are gated in managed mode (agent inventory,
   // cwd paths, job history and conversation content are the same tenant's data
@@ -384,28 +478,6 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     systemPrompt: zod.z.string().max(DESKTOP_SYSTEM_PROMPT_MAX_CHARS)
   }).strict(),
   zod.z.object({ op: zod.z.literal("legacy.agent.download"), agentId: id$1 }).strict(),
-  zod.z.object({ op: zod.z.literal("legacy.agent.variables.list"), agentId: id$1 }).strict(),
-  zod.z.object({
-    op: zod.z.literal("legacy.agent.variables.create"),
-    agentId: id$1,
-    variable: zod.z.record(zod.z.unknown())
-  }).strict(),
-  zod.z.object({
-    op: zod.z.literal("legacy.agent.variables.get"),
-    agentId: id$1,
-    key: variableKey
-  }).strict(),
-  zod.z.object({
-    op: zod.z.literal("legacy.agent.variables.update"),
-    agentId: id$1,
-    key: variableKey,
-    variable: zod.z.record(zod.z.unknown())
-  }).strict(),
-  zod.z.object({
-    op: zod.z.literal("legacy.agent.variables.delete"),
-    agentId: id$1,
-    key: variableKey
-  }).strict(),
   zod.z.object({ op: zod.z.literal("legacy.job.cancel"), jobId: id$1 }).strict(),
   zod.z.object({ op: zod.z.literal("commands.list") }).strict(),
   zod.z.object({
@@ -492,6 +564,25 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     asideId: requestId
   }).strict(),
   zod.z.object({ op: zod.z.literal("mcp.list"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("mcp.credentials.store"),
+    sessionId,
+    name: zod.z.string().min(1).max(256),
+    values: zod.z.record(zod.z.string().min(1).max(128), zod.z.string().min(1).max(32768)).refine(
+      (secrets) => Object.keys(secrets).length <= 32 && Object.values(secrets).reduce(
+        (total, value) => total + value.length,
+        0
+      ) <= 65536,
+      // Mirrors the owner's own bound (`local_operator/mcp/credentials.py`),
+      // so an oversized paste is refused as a sentence rather than
+      // serialized into a request the control budget rejects as an
+      // opaque 413.
+      {
+        message: "Too many secret values, or too much secret text, for one MCP credential write."
+      }
+    ),
+    confirmedReplace: zod.z.array(zod.z.string().min(1).max(128)).max(32)
+  }).strict(),
   zod.z.object({
     op: zod.z.literal("mcp.control"),
     sessionId,
@@ -795,6 +886,27 @@ function desktopEndpoint(request) {
           can_notify: request.canNotify
         }
       };
+    case "sessions.presence":
+      return {
+        path: "/v1/desktop/presence",
+        method: "POST",
+        body: {
+          subscription_id: request.subscriptionId,
+          // The three fields the delivery lease reads beside it. Sent
+          // snake_case like the route's own model, and always sent: a
+          // defaulted claim is what made this app ineligible.
+          can_notify_kinds: request.canNotifyKinds,
+          session_id: request.sessionId,
+          window: request.window,
+          // `can_notify` means "can ATTEMPT delivery", never "the user will
+          // be reached": `Notification.isSupported()` knows nothing about
+          // macOS Focus/DND, Windows Focus Assist or a denied permission.
+          // The backend's suppression reads it as eligibility to try, and a
+          // claim never advances the read watermark, so a suppressed banner
+          // still leaves the durable unseen mark intact.
+          can_notify: request.canNotify
+        }
+      };
     case "sessions.warm":
       return {
         path: `/v1/desktop/sessions/${request.sessionId}/warm`,
@@ -805,6 +917,31 @@ function desktopEndpoint(request) {
         // makes a legal call answer 422.
         body: {}
       };
+    case "sessions.variables.list":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/variables`,
+        method: "GET"
+      };
+    case "sessions.variables.create":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/variables`,
+        method: "POST",
+        // The route's own body shape, not the op's: `{key, value, type}` on
+        // create and `{value, type}` on update, because the key is in the path
+        // once the variable exists and is immutable after that.
+        body: { key: request.key, value: request.value, type: request.type }
+      };
+    case "sessions.variables.update":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/variables/${encodeURIComponent(request.key)}`,
+        method: "PATCH",
+        body: { value: request.value, type: request.type }
+      };
+    case "sessions.variables.delete":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/variables/${encodeURIComponent(request.key)}`,
+        method: "DELETE"
+      };
     case "legacy.models": {
       const query = new URLSearchParams();
       if (request.provider) query.set("provider", request.provider);
@@ -918,33 +1055,6 @@ function desktopEndpoint(request) {
       };
     case "legacy.agent.download":
       return { path: `/v1/agents/${request.agentId}/download`, method: "GET" };
-    case "legacy.agent.variables.list":
-      return {
-        path: `/v1/agents/${request.agentId}/execution-variables`,
-        method: "GET"
-      };
-    case "legacy.agent.variables.create":
-      return {
-        path: `/v1/agents/${request.agentId}/execution-variables`,
-        method: "POST",
-        body: request.variable
-      };
-    case "legacy.agent.variables.get":
-      return {
-        path: `/v1/agents/${request.agentId}/execution-variables/${request.key}`,
-        method: "GET"
-      };
-    case "legacy.agent.variables.update":
-      return {
-        path: `/v1/agents/${request.agentId}/execution-variables/${request.key}`,
-        method: "PATCH",
-        body: request.variable
-      };
-    case "legacy.agent.variables.delete":
-      return {
-        path: `/v1/agents/${request.agentId}/execution-variables/${request.key}`,
-        method: "DELETE"
-      };
     case "legacy.job.cancel":
       return { path: `/v1/jobs/${request.jobId}`, method: "DELETE" };
     case "commands.list":
@@ -1055,6 +1165,16 @@ function desktopEndpoint(request) {
         path: `/v1/desktop/sessions/${request.sessionId}/mcp`,
         method: "GET"
       };
+    case "mcp.credentials.store":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/mcp/credentials`,
+        method: "POST",
+        body: {
+          name: request.name,
+          values: request.values,
+          confirmed_replace: request.confirmedReplace
+        }
+      };
     case "mcp.control":
       return {
         path: `/v1/desktop/sessions/${request.sessionId}/mcp`,
@@ -1137,6 +1257,341 @@ function desktopEndpoint(request) {
 }
 const MAX_PROBE_PATHS = 64;
 const MAX_FILE_READ_BYTES = 64 * 1024 * 1024;
+const OPEN_SESSION_FLAG = "--open-session";
+const OPEN_CATALOGUE_FLAG = "--open-catalogue";
+const SESSION_ID$2 = /^[a-f0-9]{12}$/;
+function readOpenSessionArgv(argv) {
+  let found = null;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === OPEN_SESSION_FLAG) {
+      const next = argv[index + 1];
+      if (next !== void 0) found = next;
+      continue;
+    }
+    if (argument.startsWith(`${OPEN_SESSION_FLAG}=`)) {
+      found = argument.slice(OPEN_SESSION_FLAG.length + 1);
+    }
+  }
+  return found !== null && SESSION_ID$2.test(found) ? found : null;
+}
+function readLaunchTarget(argv) {
+  const sessionId2 = readOpenSessionArgv(argv);
+  if (sessionId2) return { kind: "session", sessionId: sessionId2 };
+  if (argv.includes(OPEN_CATALOGUE_FLAG)) return { kind: "catalogue" };
+  return { kind: "restore" };
+}
+const FEED_NOTIFIABLE_KINDS = ["complete", "error"];
+const DEFAULT_HEARTBEAT_SECONDS = 15;
+const MIN_HEARTBEAT_SECONDS = 1;
+const MAX_HEARTBEAT_SECONDS = 60;
+const MISSED_HEARTBEATS = 3;
+const RECONNECT_MIN_MS = 1e3;
+const RECONNECT_MAX_MS = 3e4;
+const PRESENCE_INTERVAL_MS = 15e3;
+const WATCHDOG_TICK_MS$1 = 1e3;
+const SSE_DATA_PREFIX = /^ /;
+const MAX_FRAME_BYTES$2 = 8 * 1024 * 1024;
+class DesktopFeedRelay {
+  constructor(backendUrl, token, options) {
+    this.backendUrl = backendUrl;
+    this.token = token;
+    this.options = options;
+  }
+  controller = null;
+  /**
+   * The live body reader, so the watchdog can END the read rather than only
+   * signal the fetch.
+   *
+   * Aborting the controller is not enough on its own to be sure of this: it
+   * aborts a fetch in flight, and whether that also rejects a body read already
+   * in progress is the platform's business (undici does; a test double need
+   * not). `cancel()` is the reader's own guarantee — the pending `read()`
+   * resolves `done` and the pump reconnects — so the watchdog does not depend
+   * on a behaviour it cannot assert here.
+   */
+  reader = null;
+  running = false;
+  stopped = false;
+  connected = false;
+  subscriptionId = null;
+  heartbeatMs = DEFAULT_HEARTBEAT_SECONDS * 1e3;
+  lastFrameAt = 0;
+  watchdog = null;
+  presence = null;
+  reconnectTimer = null;
+  /**
+   * Settles the promise `pause()` is parked on.
+   *
+   * The timer IS the only thing that would resolve it, so a `stop()` that only
+   * cleared the timer left `pump()` awaiting a promise nothing could settle — a
+   * leak nobody would find later (the relay refuses to restart, so it had no
+   * visible symptom). Held so teardown ends the wait explicitly.
+   */
+  reconnectResolve = null;
+  attempt = 0;
+  /**
+   * Single observer per kind, not a subscriber set.
+   *
+   * The relay has exactly two consumers and both are main's: one fan-out that
+   * puts a frame in front of the notifier and (when a window exists) in front
+   * of the renderer, and one that mirrors the connection state to the sidebar.
+   * A set would suggest that consumers can come and go independently, and the
+   * lifecycle here is the opposite of that — the observers are re-attached
+   * whenever the relay is rebuilt for a rotated backend URL, which is a thing
+   * this class cannot do for itself.
+   */
+  frameObserver = null;
+  stateObserver = null;
+  get isConnected() {
+    return this.connected;
+  }
+  /** True when this relay can authenticate at all. */
+  get available() {
+    return Boolean(this.token);
+  }
+  observe(observer) {
+    this.frameObserver = observer;
+  }
+  watchState(observer) {
+    this.stateObserver = observer;
+    observer?.({ connected: this.connected });
+  }
+  /**
+   * Open the feed if the backend supports it. Idempotent, and safe to call
+   * again on every backend-ready transition: a restart or an
+   * external-backend rotation re-runs the capability gate against the backend
+   * that is actually there now.
+   */
+  async start() {
+    if (this.running || this.stopped) return;
+    if (!this.token) {
+      this.setConnected(false);
+      return;
+    }
+    this.running = true;
+    let features;
+    try {
+      const response = await this.options.request({ op: "capabilities" });
+      const body = response.body;
+      features = body?.result?.features;
+    } catch {
+      this.running = false;
+      this.setConnected(false);
+      return;
+    }
+    if (this.stopped) return;
+    if (!(Number(features?.desktop_feed ?? 0) >= 1)) {
+      this.running = false;
+      this.setConnected(false);
+      return;
+    }
+    void this.pump();
+  }
+  /** Tear everything down. Idempotent. */
+  stop() {
+    this.stopped = true;
+    this.running = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.reconnectResolve?.();
+    this.reconnectResolve = null;
+    this.endSocket();
+    this.setConnected(false);
+  }
+  /** Abort the socket and its timers, leaving `stopped` alone. */
+  endSocket() {
+    if (this.watchdog) {
+      clearInterval(this.watchdog);
+      this.watchdog = null;
+    }
+    if (this.presence) {
+      clearInterval(this.presence);
+      this.presence = null;
+    }
+    this.subscriptionId = null;
+    this.controller?.abort();
+    this.controller = null;
+  }
+  /** Read until the socket ends, then pace a reconnect. */
+  async pump() {
+    while (!this.stopped) {
+      await this.readOnce();
+      if (this.stopped) return;
+      this.setConnected(false);
+      await this.pause();
+    }
+  }
+  pause() {
+    const delay = Math.min(
+      RECONNECT_MAX_MS,
+      RECONNECT_MIN_MS * 2 ** Math.min(this.attempt, 5)
+    );
+    this.attempt += 1;
+    return new Promise((resolve) => {
+      this.reconnectResolve = resolve;
+      this.reconnectTimer = setTimeout(() => {
+        this.reconnectTimer = null;
+        this.reconnectResolve = null;
+        resolve();
+      }, delay);
+      this.reconnectTimer.unref?.();
+    });
+  }
+  async readOnce() {
+    const controller = new AbortController();
+    this.controller = controller;
+    const url = new URL("/v1/desktop/events", this.backendUrl);
+    try {
+      const response = await fetch(url, {
+        headers: {
+          Accept: "text/event-stream",
+          Authorization: `Bearer ${this.token}`
+        },
+        redirect: "error",
+        signal: controller.signal
+      });
+      if (!response.ok || !response.body) {
+        return;
+      }
+      this.attempt = 0;
+      this.setConnected(true);
+      this.startWatchdog();
+      const reader = response.body.getReader();
+      this.reader = reader;
+      const decoder = new TextDecoder();
+      let buffer = "";
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        this.lastFrameAt = Date.now();
+        buffer += decoder.decode(value, { stream: true });
+        for (; ; ) {
+          const boundary = buffer.indexOf("\n\n");
+          if (boundary < 0) {
+            if (buffer.length > MAX_FRAME_BYTES$2) {
+              reader.cancel().catch(() => void 0);
+              return;
+            }
+            break;
+          }
+          const record = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          for (const line of record.split("\n")) {
+            if (!line.startsWith("data:")) continue;
+            this.dispatch(line.slice(5).replace(SSE_DATA_PREFIX, ""));
+          }
+        }
+      }
+    } catch {
+    } finally {
+      if (this.controller === controller) this.controller = null;
+      this.reader = null;
+      if (this.watchdog) {
+        clearInterval(this.watchdog);
+        this.watchdog = null;
+      }
+      if (this.presence) {
+        clearInterval(this.presence);
+        this.presence = null;
+      }
+      this.subscriptionId = null;
+    }
+  }
+  dispatch(data) {
+    let frame;
+    try {
+      frame = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (frame.type === "open") {
+      this.subscriptionId = frame.payload.subscription_id;
+      if (typeof frame.payload.heartbeat_seconds === "number") {
+        this.heartbeatMs = Math.min(
+          MAX_HEARTBEAT_SECONDS,
+          Math.max(
+            this.options.heartbeatFloorSeconds ?? MIN_HEARTBEAT_SECONDS,
+            frame.payload.heartbeat_seconds
+          )
+        ) * 1e3;
+      }
+      this.startPresence();
+    }
+    try {
+      this.frameObserver?.(frame);
+    } catch {
+    }
+  }
+  /**
+   * Tear the socket down when it has gone quiet for three heartbeats.
+   *
+   * A half-open socket reports no error, no end and no data: the reader simply
+   * never resolves. Without this the app would look connected while no
+   * completion could reach it, which is the silent-failure state this whole
+   * change exists to remove.
+   */
+  startWatchdog() {
+    this.lastFrameAt = Date.now();
+    if (this.watchdog) clearInterval(this.watchdog);
+    this.watchdog = setInterval(() => {
+      if (Date.now() - this.lastFrameAt < this.heartbeatMs * MISSED_HEARTBEATS)
+        return;
+      void this.reader?.cancel().catch(() => void 0);
+      this.controller?.abort();
+    }, WATCHDOG_TICK_MS$1);
+    this.watchdog.unref?.();
+  }
+  /**
+   * Renew the presence lease for as long as this subscription is live.
+   *
+   * The first beat is immediate: the backend holds the lease against the
+   * subscription, so waiting a full interval would leave a window in which the
+   * app can deliver a banner while the backend still believes nobody is there
+   * and toasts on its own host instead.
+   */
+  startPresence() {
+    if (this.presence) clearInterval(this.presence);
+    const beat = () => {
+      const subscriptionId = this.subscriptionId;
+      if (!subscriptionId) return;
+      const context = this.options.presenceContext?.() ?? {
+        sessionId: "",
+        window: {
+          exists: false,
+          focused: false,
+          visible: false,
+          minimized: false
+        }
+      };
+      void this.options.beatPresence({
+        subscriptionId,
+        canNotify: true,
+        // Always the FEED's kinds, never a window's: this app delivers a
+        // completion window or no window, which is why the feed exists.
+        canNotifyKinds: FEED_NOTIFIABLE_KINDS,
+        sessionId: context.sessionId,
+        window: context.window
+      }).catch(() => void 0);
+    };
+    beat();
+    this.presence = setInterval(
+      beat,
+      this.options.presenceIntervalMs ?? PRESENCE_INTERVAL_MS
+    );
+    this.presence.unref?.();
+  }
+  setConnected(connected) {
+    if (this.connected === connected) return;
+    this.connected = connected;
+    try {
+      this.stateObserver?.({ connected });
+    } catch {
+    }
+  }
+}
 const id = zod.z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
 const MAX_UPLOAD_BYTES = 16 * 1024 * 1024;
 const MAX_DOWNLOAD_BYTES = 32 * 1024 * 1024;
@@ -1333,7 +1788,7 @@ const DESKTOP_STREAM_DETAIL = {
    */
   refusedWithoutStatus: "The event stream was refused."
 };
-const SESSION_ID = /^[a-f0-9]{12}$/;
+const SESSION_ID$1 = /^[a-f0-9]{12}$/;
 const SAFE_ID = /^[a-zA-Z0-9_-]{1,128}$/;
 function transportFailureDetail(error) {
   if (error instanceof Error && error.name === "AbortError") {
@@ -1343,11 +1798,14 @@ function transportFailureDetail(error) {
   if (code === "ECONNREFUSED") return DESKTOP_STREAM_DETAIL.serverDown;
   return DESKTOP_STREAM_DETAIL.connectionFailed;
 }
-const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const SILENCE_TIMEOUT_MS = 45e3;
+const WATCHDOG_TICK_MS = 1e3;
+const MAX_FRAME_BYTES$1 = 8 * 1024 * 1024;
 class DesktopStreamRelay {
-  constructor(backendUrl, token) {
+  constructor(backendUrl, token, timings = {}) {
     this.backendUrl = backendUrl;
     this.token = token;
+    this.timings = timings;
   }
   streams = /* @__PURE__ */ new Map();
   /** Frame observer for main-owned side effects (notifications). It sees
@@ -1362,7 +1820,7 @@ class DesktopStreamRelay {
     return Boolean(this.token);
   }
   subscribe(args, emit) {
-    if (!SESSION_ID.test(args.sessionId)) {
+    if (!SESSION_ID$1.test(args.sessionId)) {
       throw new Error("Invalid session for streaming.");
     }
     if (args.epoch !== void 0 && !SAFE_ID.test(args.epoch)) {
@@ -1419,41 +1877,63 @@ class DesktopStreamRelay {
         emit({
           streamId,
           kind: "error",
-          detail: DESKTOP_STREAM_DETAIL.refused(response.status)
+          detail: DESKTOP_STREAM_DETAIL.refused(response.status),
+          // Carried so the renderer can tell "this conversation is gone"
+          // from "this transport is down". Both are refusals; only one of
+          // them is about the session, and the two need different words.
+          status: response.status
         });
         return;
       }
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
       let buffer = "";
-      for (; ; ) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
+      let lastActivity = Date.now();
+      const silenceTimeoutMs = this.timings.silenceTimeoutMs ?? SILENCE_TIMEOUT_MS;
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastActivity < silenceTimeoutMs) return;
+        clearInterval(watchdog);
+        emit({
+          streamId,
+          kind: "error",
+          detail: DESKTOP_STREAM_DETAIL.ended
+        });
+        void reader.cancel().catch(() => void 0);
+      }, this.timings.watchdogTickMs ?? WATCHDOG_TICK_MS);
+      watchdog.unref?.();
+      try {
         for (; ; ) {
-          const boundary = buffer.indexOf("\n\n");
-          if (boundary < 0) {
-            if (buffer.length > MAX_FRAME_BYTES) {
-              emit({
-                streamId,
-                kind: "error",
-                detail: DESKTOP_STREAM_DETAIL.frameBudget
-              });
-              reader.cancel().catch(() => void 0);
-              return;
+          const { done, value } = await reader.read();
+          if (done) break;
+          lastActivity = Date.now();
+          buffer += decoder.decode(value, { stream: true });
+          for (; ; ) {
+            const boundary = buffer.indexOf("\n\n");
+            if (boundary < 0) {
+              if (buffer.length > MAX_FRAME_BYTES$1) {
+                emit({
+                  streamId,
+                  kind: "error",
+                  detail: DESKTOP_STREAM_DETAIL.frameBudget
+                });
+                reader.cancel().catch(() => void 0);
+                return;
+              }
+              break;
             }
-            break;
-          }
-          const record = buffer.slice(0, boundary);
-          buffer = buffer.slice(boundary + 2);
-          for (const line of record.split("\n")) {
-            if (line.startsWith("data:")) {
-              const data = line.slice(5).replace(/^ /, "");
-              this.observer?.(sessionId2, data);
-              emit({ streamId, kind: "data", data });
+            const record = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            for (const line of record.split("\n")) {
+              if (line.startsWith("data:")) {
+                const data = line.slice(5).replace(/^ /, "");
+                this.observer?.(sessionId2, data);
+                emit({ streamId, kind: "data", data });
+              }
             }
           }
         }
+      } finally {
+        clearInterval(watchdog);
       }
       emit({ streamId, kind: "end" });
     } catch (error) {
@@ -1548,83 +2028,97 @@ function pythonBytecodeCacheDir(userDataDir) {
 }
 function withPythonBytecodeCache(env, userDataDir) {
   const existing = env.PYTHONPYCACHEPREFIX?.trim();
-  if (existing && !insideAppBundle(existing)) return { ...env };
-  return { ...env, PYTHONPYCACHEPREFIX: pythonBytecodeCacheDir(userDataDir) };
-}
-const BUNDLED_PYTHON_TREE_NAMES = ["python", "python_aarch64"];
-function bundledPythonTreePaths(resourcesPath) {
-  return BUNDLED_PYTHON_TREE_NAMES.map((name) => path$1.join(resourcesPath, name));
-}
-const FIND = "/usr/bin/find";
-const CHMOD = "/bin/chmod";
-const DIRECTORY_ACE = "everyone deny add_file,add_subdirectory";
-const BYTECODE_ACE = "everyone deny write,append";
-const MAX_FIND_OUTPUT_BYTES = 16 * 1024 * 1024;
-const PARTIAL_SEAL_NAMED = 3;
-function describePythonTreeSeal(seal) {
-  if (!seal.supported) {
-    return "Bundled interpreter bytecode seal is macOS-only (there is no code seal to protect elsewhere); the bytecode cache prefix still applies";
-  }
-  const trees = seal.sealed.join(", ") || "(none present)";
-  if (seal.failures.length === 0) {
-    return `Bundled interpreter trees sealed against bytecode writes: ${trees}; ${seal.directories} directory path(s) selected and now refusing new entries, ${seal.bytecodeFiles} bytecode file(s) selected and now refusing rewrites`;
-  }
-  const named = seal.failures.slice(0, PARTIAL_SEAL_NAMED).join("; ");
-  const rest = seal.failures.length - PARTIAL_SEAL_NAMED;
-  return `Bundled interpreter bytecode seal INCOMPLETE: ${trees}; ${seal.directories} directory path(s) and ${seal.bytecodeFiles} bytecode file(s) selected, ${seal.failures.length} refused and left with the access they had - bytecode writes into the bundle are not prevented on every path. First refusals: ${named}${rest > 0 ? ` (+${rest} more)` : ""}`;
-}
-function sealPythonInterpreterTrees(trees) {
-  const result = {
-    sealed: [],
-    directories: 0,
-    bytecodeFiles: 0,
-    failures: [],
-    supported: process.platform === "darwin"
+  const prefix = existing && !insideAppBundle(existing) ? existing : pythonBytecodeCacheDir(userDataDir);
+  return {
+    ...env,
+    PYTHONPYCACHEPREFIX: prefix,
+    PYTHONDONTWRITEBYTECODE: "1"
   };
-  if (!result.supported) return result;
-  for (const tree of trees) {
-    let root;
-    try {
-      root = fs.lstatSync(tree);
-    } catch {
-      continue;
+}
+const VENV_BYTECODE_GUARD_FILE = "sitecustomize.py";
+const VENV_BYTECODE_GUARD_SENTINEL = "# Local Operator bytecode guard";
+function venvBytecodeGuardSource() {
+  return `${VENV_BYTECODE_GUARD_SENTINEL}. Do not edit; the app rewrites this file.
+#
+# Why this file exists: this virtual environment is built on the interpreter
+# inside the Local Operator application bundle (see pyvenv.cfg), so every module
+# this python imports has its source - and CPython's bytecode cache for it -
+# inside a code-sealed .app. A __pycache__/*.pyc written there changes a sealed
+# resource, and macOS then answers "the app is damaged" on the next launch and
+# Squirrel refuses the next in-place update with -67028
+# errSecCSBadBundleFormat.
+#
+# PYTHONDONTWRITEBYTECODE and PYTHONPYCACHEPREFIX reach only the processes the
+# app started or that inherited its environment. This file reaches every process
+# that uses this environment, including one started by a shell, a script or
+# launchd, because site.py imports sitecustomize from site-packages on every
+# start.
+#
+# The cost, stated rather than hidden: a process under this flag compiles its
+# imports and caches nothing, so the backend recompiles its import graph on each
+# start. That is the deliberate trade against an application bundle that macOS
+# refuses to open, and it is confined to this venv.
+import sys
+
+sys.dont_write_bytecode = True
+`;
+}
+function venvSitePackages(venvPath) {
+  const candidates = [path$1.join(venvPath, "Lib", "site-packages")];
+  try {
+    for (const entry of fs.readdirSync(path$1.join(venvPath, "lib"))) {
+      if (entry.startsWith("python")) {
+        candidates.push(path$1.join(venvPath, "lib", entry, "site-packages"));
+      }
     }
-    if (!root.isDirectory()) continue;
-    result.sealed.push(tree);
-    result.directories += applyAce(
-      tree,
-      ["-type", "d"],
-      DIRECTORY_ACE,
-      result.failures
-    );
-    result.bytecodeFiles += applyAce(
-      tree,
-      ["-type", "f", "-name", "*.pyc"],
-      BYTECODE_ACE,
-      result.failures
-    );
+  } catch {
   }
-  return result;
+  return candidates.filter((candidate) => fs.existsSync(candidate));
 }
-function applyAce(tree, selector, ace, failures) {
-  const run = node_child_process.spawnSync(
-    FIND,
-    [tree, ...selector, "-exec", CHMOD, "+a", ace, "{}", "+", "-print0"],
-    { encoding: "buffer", maxBuffer: MAX_FIND_OUTPUT_BYTES }
-  );
-  if (run.error) {
-    failures.push(`${tree}: ${String(run.error)}`);
-    return 0;
+function ensureVenvBytecodeGuard(venvPath) {
+  const dirs = venvSitePackages(venvPath);
+  if (dirs.length === 0) {
+    return {
+      path: null,
+      written: false,
+      reason: `no site-packages under ${venvPath} yet, so there is nothing to guard`
+    };
   }
-  for (const line of String(run.stderr).split("\n")) {
-    if (line.trim().length > 0) failures.push(line.trim());
+  const path2 = path$1.join(dirs[0], VENV_BYTECODE_GUARD_FILE);
+  const source = venvBytecodeGuardSource();
+  let existing = null;
+  try {
+    existing = fs.readFileSync(path2, "utf8");
+  } catch {
   }
-  if (run.status !== 0 && String(run.stderr).trim().length === 0) {
-    failures.push(`${tree}: ${FIND} exited ${run.status} with no explanation`);
+  if (existing === source) {
+    return {
+      path: path2,
+      written: false,
+      reason: `${path2} already refuses bytecode writes`
+    };
   }
-  let selected = 0;
-  for (const byte of run.stdout) if (byte === 0) selected += 1;
-  return selected;
+  if (existing !== null && !existing.startsWith(VENV_BYTECODE_GUARD_SENTINEL)) {
+    return {
+      path: path2,
+      written: false,
+      reason: `${path2} is not ours (no "${VENV_BYTECODE_GUARD_SENTINEL}" line), so it was left exactly as it is`
+    };
+  }
+  try {
+    fs.writeFileSync(path2, source);
+  } catch (error) {
+    return {
+      path: path2,
+      written: false,
+      reason: `could not write ${path2}: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  return {
+    path: path2,
+    written: true,
+    reason: `${path2} now sets sys.dont_write_bytecode for every process using this venv`
+  };
 }
 var LogFileType = /* @__PURE__ */ ((LogFileType2) => {
   LogFileType2["INSTALLER"] = "backend-installer.log";
@@ -1839,15 +2333,652 @@ ${formattedErrors}`);
       `Failed to load configuration: ${error instanceof Error ? error.message : String(error)}`,
       LogFileType.BACKEND
     );
-    throw new Error(
-      `Failed to load configuration: ${error instanceof Error ? error.message : String(error)}`
+    throw new Error(
+      `Failed to load configuration: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+const backendConfig = loadConfig();
+const apiConfig = {
+  baseUrl: backendConfig.VITE_LOCAL_OPERATOR_API_URL
+};
+const seedNamespace = "python-runtime-seed";
+const architectures = ["arm64", "x64"];
+const legacyResourceNames = ["python", "python_aarch64"];
+const checkoutSeedNames = { "arm64": "python_aarch64", "x64": "python" };
+const BUNDLED_PYTHON_LAYOUT = {
+  seedNamespace,
+  architectures,
+  legacyResourceNames,
+  checkoutSeedNames
+};
+const execute = node_util.promisify(node_child_process.execFile);
+const APP_BUNDLE_PATH = /\.app(?:\/|$)/i;
+const BYTECODE_EXTENSION = /\.py[co]$/;
+const OTOOL_LOAD_COMMAND = /Load command \d+/;
+const LC_LOAD_COMMAND_KIND = /cmd LC_(?:LOAD|LOAD_WEAK|REEXPORT|LAZY_LOAD|LOAD_UPWARD)_DYLIB\b/;
+const DYLIB_INSTALL_NAME = /\n\s*name (.+?) \(offset/;
+const RUNTIME_ID = /^[a-f0-9]{64}$/;
+const PYVENV_HOME$1 = /^home\s*=\s*(.+)$/m;
+const LOCK_OWNER = /^\s*\d+\s*$/;
+const LEGACY_BUNDLE_PYTHON_PATH = /\.app\/Contents\/Resources\/python(?:_aarch64)?\//;
+const PYTHON_SEED_NAMESPACE = BUNDLED_PYTHON_LAYOUT.seedNamespace;
+const FORMAT = 1;
+const READY = "environment-ready.json";
+const POINTER = "selected-environment.json";
+function inside(root, path2) {
+  const rel = path$1.relative(root, path2);
+  return rel === "" || !rel.startsWith(`..${path$1.sep}`) && rel !== ".." && !path$1.isAbsolute(rel);
+}
+function outsideApp(path2) {
+  if (!path$1.isAbsolute(path2) || APP_BUNDLE_PATH.test(path2)) {
+    throw new Error(
+      `Managed Python must live outside every application bundle: ${path2}`
+    );
+  }
+}
+function realDirectory(path2) {
+  const stat = fs.lstatSync(path2);
+  if (!stat.isDirectory() || stat.isSymbolicLink())
+    throw new Error(`Not a private directory: ${path2}`);
+}
+function isCache(path2) {
+  return path2.split("/").includes("__pycache__") || BYTECODE_EXTENSION.test(path2);
+}
+function runtimeManifest(root, arch, allowCaches = false) {
+  if (!["arm64", "x64"].includes(arch))
+    throw new Error(`Unsupported Python architecture: ${arch}`);
+  realDirectory(root);
+  const realRoot = fs.realpathSync(root);
+  const entries = [
+    { path: ".", mode: fs.lstatSync(root).mode & 511, kind: "directory" }
+  ];
+  function walk(directory) {
+    for (const name of fs.readdirSync(directory).sort()) {
+      const path2 = path$1.join(directory, name);
+      const rel = path$1.relative(root, path2).split(path$1.sep).join("/");
+      if (allowCaches && isCache(rel)) continue;
+      const stat = fs.lstatSync(path2);
+      const mode = stat.mode & 511;
+      if (stat.isSymbolicLink()) {
+        const target2 = fs.readlinkSync(path2);
+        if (path$1.isAbsolute(target2) || !inside(root, path$1.resolve(path$1.dirname(path2), target2)) || !inside(realRoot, fs.realpathSync(path2))) {
+          throw new Error(`Python seed link escapes its runtime: ${rel}`);
+        }
+        entries.push({ path: rel, mode, kind: "symlink", value: target2 });
+      } else if (stat.isDirectory()) {
+        entries.push({ path: rel, mode, kind: "directory" });
+        walk(path2);
+      } else if (stat.isFile() && (allowCaches || stat.nlink === 1)) {
+        entries.push({
+          path: rel,
+          mode,
+          kind: "file",
+          value: node_crypto.createHash("sha256").update(fs.readFileSync(path2)).digest("hex")
+        });
+      } else {
+        throw new Error(
+          `Python seed contains a hardlink or special file: ${rel}`
+        );
+      }
+    }
+  }
+  walk(root);
+  entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return { format: FORMAT, platform: "darwin", arch, entries };
+}
+function runtimeId(manifest) {
+  return node_crypto.createHash("sha256").update(JSON.stringify(manifest)).digest("hex");
+}
+function runtimeIdentity(root, arch) {
+  return runtimeId(runtimeManifest(root, arch, true));
+}
+function firstDifference(expected, actual) {
+  const expectedByPath = new Map(expected.entries.map((e) => [e.path, e]));
+  const actualByPath = new Map(actual.entries.map((e) => [e.path, e]));
+  for (const [path2, entry] of expectedByPath) {
+    const other = actualByPath.get(path2);
+    if (!other) return `${path2} is missing`;
+    if (other.kind !== entry.kind)
+      return `${path2} is a ${other.kind}, not a ${entry.kind}`;
+    if ((other.value ?? "") !== (entry.value ?? ""))
+      return `${path2} does not match the seed`;
+  }
+  for (const path2 of actualByPath.keys())
+    if (!expectedByPath.has(path2)) return `${path2} was added`;
+  return "the two trees differ in a way this message cannot name";
+}
+function managedPythonRoot(options) {
+  outsideApp(options.support);
+  return path$1.join(
+    options.support,
+    "managed-python",
+    options.packaged ? "packaged" : "dev"
+  );
+}
+function seedPath(options) {
+  return options.packaged ? path$1.join(options.resources, PYTHON_SEED_NAMESPACE, options.arch) : path$1.join(
+    options.resources,
+    BUNDLED_PYTHON_LAYOUT.checkoutSeedNames[options.arch]
+  );
+}
+function pythonPath(runtime) {
+  return path$1.join(runtime, "bin", "python3");
+}
+async function verifyMachO(root, manifest) {
+  let binaries = 0;
+  for (const entry of manifest.entries) {
+    if (entry.kind !== "file") continue;
+    const path2 = path$1.join(root, entry.path);
+    const fd = fs.openSync(path2, "r");
+    const magic = Buffer.alloc(4);
+    try {
+      fs.readSync(fd, magic, 0, 4, 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (![
+      "cffaedfe",
+      "cefaedfe",
+      "feedfacf",
+      "feedface",
+      "cafebabe",
+      "bebafeca"
+    ].includes(magic.toString("hex")))
+      continue;
+    binaries++;
+    await execute("/usr/bin/codesign", ["--verify", "--strict", path2], {
+      timeout: 3e4
+    });
+    const { stdout } = await execute("/usr/bin/otool", ["-l", path2], {
+      timeout: 3e4
+    });
+    for (const command of stdout.split(OTOOL_LOAD_COMMAND)) {
+      if (!LC_LOAD_COMMAND_KIND.test(command)) continue;
+      const dependency = DYLIB_INSTALL_NAME.exec(command)?.[1];
+      if (dependency && path$1.isAbsolute(dependency) && !dependency.startsWith("/usr/lib/") && !dependency.startsWith("/System/Library/")) {
+        throw new Error(
+          `Python runtime has an external load dependency: ${dependency}`
+        );
+      }
+    }
+  }
+  if (binaries === 0)
+    throw new Error("Python seed contains no signed Mach-O binaries");
+}
+function runtimesRoot(options) {
+  return path$1.join(managedPythonRoot(options), "runtimes");
+}
+function environmentsRoot(options) {
+  return path$1.join(managedPythonRoot(options), "environments");
+}
+function publishedRuntimeIsReusable(options, published) {
+  try {
+    return runtimeIdentity(published.runtime, options.arch) === runtimeIdentity(seedPath(options), options.arch);
+  } catch {
+    return false;
+  }
+}
+const GENERATION_NAME = /^[a-f0-9]{64}-[0-9a-f-]{8,}$/;
+function usableRuntimeGeneration(options, id2) {
+  let names;
+  try {
+    names = fs.readdirSync(runtimesRoot(options));
+  } catch {
+    return null;
+  }
+  for (const name of names.sort()) {
+    if (!name.startsWith(`${id2}-`)) continue;
+    const candidate = path$1.join(runtimesRoot(options), name);
+    try {
+      if (runtimeIdentity(candidate, options.arch) === id2) return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+async function prepareRuntime(options) {
+  const seed = seedPath(options);
+  const manifest = runtimeManifest(seed, options.arch);
+  const id2 = runtimeIdentity(seed, options.arch);
+  const existing = usableRuntimeGeneration(options, id2);
+  if (existing) return { runtime: existing, id: id2 };
+  await verifyMachO(seed, manifest);
+  const root = runtimesRoot(options);
+  await promises.mkdir(root, { recursive: true, mode: 448 });
+  realDirectory(root);
+  if (!inside(fs.realpathSync(managedPythonRoot(options)), fs.realpathSync(root)))
+    throw new Error("Runtime directory escaped its managed root");
+  const runtime = path$1.join(root, `${id2}-${node_crypto.randomUUID()}`);
+  const staging = await promises.mkdtemp(path$1.join(root, ".preparing-"));
+  await execute("/usr/bin/ditto", ["--noacl", seed, staging], {
+    timeout: 12e4
+  });
+  fs.chmodSync(staging, fs.lstatSync(seed).mode & 511);
+  if (runtimeIdentity(staging, options.arch) !== id2)
+    throw new Error("The Python runtime copy did not match its signed seed");
+  for (const entry of manifest.entries) {
+    if (entry.kind !== "file") continue;
+    const source = fs.statSync(path$1.join(seed, entry.path));
+    const copied = fs.statSync(path$1.join(staging, entry.path));
+    if (source.dev === copied.dev && source.ino === copied.ino)
+      throw new Error(`Runtime copy shares a seed inode: ${entry.path}`);
+  }
+  await verifyMachO(staging, manifest);
+  await promises.rename(staging, runtime);
+  return { runtime, id: id2 };
+}
+function describe$1(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function selectionIsWellFormed(root, selection) {
+  return selection.format === FORMAT && RUNTIME_ID.test(selection.runtimeId) && selection.runtime === path$1.join(root, "runtimes", selection.runtimeId);
+}
+function selectionMatchesGeneration(root, selection) {
+  return selection.format === FORMAT && RUNTIME_ID.test(selection.runtimeId) && path$1.dirname(selection.runtime) === path$1.join(root, "runtimes") && GENERATION_NAME.test(path$1.basename(selection.runtime)) && selection.runtime.startsWith(
+    path$1.join(root, "runtimes", `${selection.runtimeId}-`)
+  ) && path$1.dirname(selection.venv) === path$1.join(root, "environments") && selection.venv.startsWith(
+    path$1.join(root, "environments", `${selection.runtimeId}-`)
+  );
+}
+function inspectManagedSelection(options) {
+  const root = managedPythonRoot(options);
+  const pointer = path$1.join(root, POINTER);
+  let raw;
+  try {
+    raw = fs.readFileSync(pointer, "utf8");
+  } catch {
+    return {
+      kind: "unprepared",
+      detail: `No environment is published for this instance (${pointer})`
+    };
+  }
+  let selection;
+  try {
+    selection = JSON.parse(raw);
+  } catch {
+    return {
+      kind: "unprepared",
+      detail: `The published environment pointer is not readable: ${pointer}`
+    };
+  }
+  if (!selectionIsWellFormed(root, selection) && !selectionMatchesGeneration(root, selection))
+    return {
+      kind: "unprepared",
+      detail: `The published environment pointer does not describe a managed environment: ${pointer}`
+    };
+  const missing = (detail) => ({
+    kind: "missing",
+    detail,
+    published: selection
+  });
+  for (const [what, path2] of [
+    ["Python runtime", selection.runtime],
+    ["environment", selection.venv]
+  ]) {
+    try {
+      realDirectory(path2);
+    } catch (error) {
+      return missing(
+        `The selected ${what} is not there any more (${path2}): ${describe$1(error)}`
+      );
+    }
+  }
+  try {
+    const ready = JSON.parse(
+      fs.readFileSync(path$1.join(selection.venv, READY), "utf8")
+    );
+    if (JSON.stringify(ready) !== JSON.stringify(selection))
+      return missing(
+        `The selected environment does not match the record published with it: ${selection.venv}`
+      );
+  } catch (error) {
+    return missing(
+      `The selected environment is not complete (${selection.venv}): ${describe$1(error)}`
+    );
+  }
+  if (!fs.existsSync(path$1.join(selection.venv, "bin", "local-operator")))
+    return missing(
+      `The selected environment has no backend installed: ${selection.venv}`
+    );
+  let home;
+  try {
+    home = PYVENV_HOME$1.exec(
+      fs.readFileSync(path$1.join(selection.venv, "pyvenv.cfg"), "utf8")
+    )?.[1]?.trim();
+  } catch (error) {
+    return missing(
+      `The selected environment has no readable pyvenv.cfg (${selection.venv}): ${describe$1(error)}`
+    );
+  }
+  if (home !== path$1.join(selection.runtime, "bin"))
+    return missing(
+      `The selected environment does not belong to its external Python runtime (${selection.venv} names ${home ?? "no runtime"})`
+    );
+  let identity;
+  try {
+    identity = runtimeIdentity(selection.runtime, options.arch);
+  } catch (error) {
+    return missing(
+      `The selected Python runtime could not be read (${selection.runtime}): ${describe$1(error)}`
+    );
+  }
+  if (identity !== selection.runtimeId) {
+    let reason;
+    try {
+      reason = firstDifference(
+        runtimeManifest(seedPath(options), options.arch, true),
+        runtimeManifest(selection.runtime, options.arch, true)
+      );
+    } catch {
+      reason = "the two trees could not be compared";
+    }
+    return missing(
+      `The selected Python runtime is no longer the runtime that was published (${reason}); a fresh runtime will be published beside it`
+    );
+  }
+  return { kind: "ready", selection };
+}
+function readManagedSelection(options) {
+  const state = inspectManagedSelection(options);
+  return state.kind === "ready" ? state.selection : null;
+}
+async function managedSelectionReady(options) {
+  return inspectManagedSelection(options).kind === "ready";
+}
+const PREPARATION_LOCK_MS = 12e4;
+function reapSupersededGenerations(options, keep, now = Date.now()) {
+  const removed = [];
+  for (const [root, kept] of [
+    [runtimesRoot(options), keep.runtime],
+    [environmentsRoot(options), keep.venv]
+  ]) {
+    let names;
+    try {
+      names = fs.readdirSync(root);
+    } catch {
+      continue;
+    }
+    const survivors = new Set(kept ? [kept] : []);
+    const generations = [];
+    for (const name of names) {
+      const path2 = path$1.join(root, name);
+      if (name.startsWith(".preparing-")) {
+        try {
+          if (now - fs.statSync(path2).mtimeMs < PREPARATION_LOCK_MS) continue;
+          fs.rmSync(path2, { recursive: true, force: true });
+          removed.push(path2);
+        } catch {
+        }
+        continue;
+      }
+      if (!GENERATION_NAME.test(name) || survivors.has(path2)) continue;
+      try {
+        generations.push({ path: path2, mtimeMs: fs.statSync(path2).mtimeMs });
+      } catch {
+      }
+    }
+    generations.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    if (generations.length > 0) survivors.add(generations[0].path);
+    for (const generation of generations.slice(1)) {
+      try {
+        fs.rmSync(generation.path, { recursive: true, force: true });
+        removed.push(generation.path);
+      } catch {
+      }
+    }
+  }
+  return removed;
+}
+let preparation = Promise.resolve();
+async function locked(root, work) {
+  const previous = preparation;
+  let release = () => {
+  };
+  preparation = new Promise((done) => {
+    release = done;
+  });
+  await previous;
+  const path2 = path$1.join(root, "preparation.lock");
+  let acquired = false;
+  try {
+    await promises.mkdir(root, { recursive: true, mode: 448 });
+    realDirectory(root);
+    outsideApp(fs.realpathSync(root));
+    const deadline2 = Date.now() + PREPARATION_LOCK_MS;
+    while (!acquired) {
+      if (fs.existsSync(path2) && (fs.lstatSync(path2).isSymbolicLink() || !LOCK_OWNER.test(fs.readFileSync(path2, "utf8"))))
+        throw new Error("Unrecognized preparation lock was preserved");
+      try {
+        await execute(
+          "/usr/bin/shlock",
+          ["-p", String(process.pid), "-f", path2],
+          { timeout: 5e3 }
+        );
+        acquired = true;
+      } catch {
+        if (Date.now() >= deadline2)
+          throw new Error(
+            "Another Local Operator instance is preparing its backend. Retry when it finishes."
+          );
+        await new Promise((done) => setTimeout(done, 250));
+      }
+    }
+    return await work();
+  } finally {
+    if (acquired && fs.readFileSync(path2, "utf8").trim() === String(process.pid))
+      fs.unlinkSync(path2);
+    release();
+  }
+}
+const IMPORT_PROBE = `import sys, sysconfig, os, json, encodings, webbrowser, _ssl, _sqlite3
+paths = [sys._base_executable, sys.base_prefix, sysconfig.get_path('stdlib'), encodings.__file__, webbrowser.__file__] + sys.path
+paths += [getattr(m, '__file__', '') for m in (_ssl, _sqlite3)]
+assert all('.app/' not in os.path.realpath(p).lower() for p in paths if p), paths
+print(json.dumps({'base_executable': sys._base_executable, 'base_prefix': sys.base_prefix, 'paths': paths}))`;
+async function smokeEnvironment(venv, env) {
+  const python = path$1.join(venv, "bin", "python");
+  await execute(python, ["-I", "-B", "-c", IMPORT_PROBE], {
+    env,
+    timeout: 3e4
+  });
+  const { stdout: version } = await execute(
+    python,
+    [
+      "-I",
+      "-B",
+      "-c",
+      "import importlib.metadata; print(importlib.metadata.version('local-operator'))"
+    ],
+    { env, timeout: 3e4 }
+  );
+  const home = await promises.mkdtemp(path$1.join(os.tmpdir(), "local-operator-backend-smoke-"));
+  const isolated = withPythonBytecodeCache(
+    {
+      PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+      HOME: home,
+      TMPDIR: home,
+      LANG: "en_US.UTF-8",
+      TERM: "xterm-256color",
+      LOCAL_OPERATOR_HOME: path$1.join(home, ".local-operator"),
+      LOCAL_OPERATOR_CONFIG_DIR: path$1.join(home, "config"),
+      XDG_CONFIG_HOME: path$1.join(home, "config"),
+      XDG_CACHE_HOME: path$1.join(home, "cache"),
+      XDG_DATA_HOME: path$1.join(home, "data")
+    },
+    home
+  );
+  const socket = node_net.createServer();
+  await new Promise((done, reject) => {
+    socket.once("error", reject);
+    socket.listen(0, "127.0.0.1", done);
+  });
+  const address = socket.address();
+  if (!address || typeof address === "string")
+    throw new Error("Could not allocate backend smoke port");
+  await new Promise((done) => socket.close(() => done()));
+  const child = node_child_process.spawn(
+    path$1.join(venv, "bin", "local-operator"),
+    ["serve", "--host", "127.0.0.1", "--port", String(address.port)],
+    { env: isolated, stdio: "ignore" }
+  );
+  let failed = null;
+  child.on("error", (error) => {
+    failed = error;
+  });
+  try {
+    const deadline2 = Date.now() + 6e4;
+    while (Date.now() < deadline2) {
+      if (failed) throw failed;
+      if (child.exitCode !== null)
+        throw new Error(`Backend smoke exited with ${child.exitCode}`);
+      try {
+        const response = await fetch(
+          `http://127.0.0.1:${address.port}/health`,
+          { signal: AbortSignal.timeout(1e3) }
+        );
+        if (response.ok) return version.trim();
+      } catch {
+      }
+      await new Promise((done) => setTimeout(done, 200));
+    }
+    throw new Error(
+      "The prepared backend did not become healthy; the previous selection was preserved"
+    );
+  } finally {
+    if (child.exitCode === null && child.pid) {
+      child.kill("SIGTERM");
+      await Promise.race([
+        new Promise((done) => child.once("exit", done)),
+        new Promise((done) => setTimeout(done, 5e3))
+      ]);
+      if (child.exitCode === null) child.kill("SIGKILL");
+    }
+  }
+}
+async function prepareManagedPython(options, install) {
+  return locked(managedPythonRoot(options), async () => {
+    const state = inspectManagedSelection(options);
+    if (state.kind === "ready") return state.selection;
+    const superseded = state.kind === "missing" ? state.detail : null;
+    const published = state.kind === "missing" ? state.published : void 0;
+    const root = managedPythonRoot(options);
+    reapSupersededGenerations(options, {
+      runtime: published && publishedRuntimeIsReusable(options, published) ? published.runtime : void 0
+    });
+    const { runtime, id: id2 } = await prepareRuntime(options);
+    await promises.mkdir(environmentsRoot(options), { recursive: true, mode: 448 });
+    realDirectory(environmentsRoot(options));
+    const venv = path$1.join(environmentsRoot(options), `${id2}-${node_crypto.randomUUID()}`);
+    if (!await install(venv, pythonPath(runtime)))
+      throw new Error(
+        "Backend preparation did not complete. Your previous environment and data were preserved."
+      );
+    const env = withPythonBytecodeCache({ ...process.env }, options.support);
+    const backendVersion = await smokeEnvironment(venv, env);
+    const selection = {
+      format: FORMAT,
+      runtimeId: id2,
+      runtime,
+      venv,
+      backendVersion
+    };
+    const bytes = `${JSON.stringify(selection)}
+`;
+    await promises.writeFile(path$1.join(venv, READY), bytes, { flag: "wx", mode: 384 });
+    const temporary = path$1.join(root, `.selection-${node_crypto.randomUUID()}.json`);
+    await promises.writeFile(temporary, bytes, { flag: "wx", mode: 384 });
+    await promises.rename(temporary, path$1.join(root, POINTER));
+    reapSupersededGenerations(options, { runtime, venv });
+    if (superseded)
+      console.warn(
+        `Replaced an unusable managed Python selection: ${superseded}`
+      );
+    return selection;
+  });
+}
+function isLegacyManagedCommand(command, support) {
+  const legacy = [
+    path$1.join(support, "local-operator-venv"),
+    path$1.join(support, "local-operator-venv-dev")
+  ];
+  const candidates = [command];
+  try {
+    candidates.push(fs.realpathSync(command));
+  } catch {
+  }
+  try {
+    candidates.push(fs.readFileSync(command, "utf8").slice(0, 4096));
+  } catch {
+  }
+  return candidates.some(
+    (candidate) => legacy.some((path2) => candidate.includes(`${path2}/`)) || LEGACY_BUNDLE_PYTHON_PATH.test(candidate)
+  );
+}
+const PACKAGED_VENV_DIR_NAME = "local-operator-venv";
+const DEV_VENV_DIR_NAME = "local-operator-venv-dev";
+const NO_SELECTION_DIR_NAME = "no-environment-selected";
+function isUnpreparedVenvPath(path2) {
+  return path2.endsWith(`${path$1.sep}${NO_SELECTION_DIR_NAME}`);
+}
+function managedSupportRoot(home) {
+  return path$1.join(home, "Library", "Application Support", "Local Operator");
+}
+function legacyVenvPaths(support) {
+  return [
+    path$1.join(support, PACKAGED_VENV_DIR_NAME),
+    path$1.join(support, DEV_VENV_DIR_NAME)
+  ];
+}
+const VENV_PATH_ENV = "LOCAL_OPERATOR_VENV_PATH";
+const PYVENV_HOME = /^\s*home\s*=\s*(.+?)\s*$/;
+const BUNDLED_INTERPRETER_HOME = /^(.*?\.app)\/Contents\/Resources\/python(?:_aarch64)?\//;
+function managedVenvPath(input) {
+  const name = input.packaged ? PACKAGED_VENV_DIR_NAME : DEV_VENV_DIR_NAME;
+  if (input.platform === "win32") {
+    return path$1.join(input.appDataPath, name);
+  }
+  if (input.platform === "darwin") {
+    const support = managedSupportRoot(input.home);
+    return readManagedSelection({
+      support,
+      resources: "",
+      packaged: input.packaged,
+      arch: process.arch
+    })?.venv ?? path$1.join(
+      support,
+      "managed-python",
+      input.packaged ? "packaged" : "dev",
+      NO_SELECTION_DIR_NAME
+    );
+  }
+  return path$1.join(input.home, ".config", "local-operator", name);
+}
+function venvInterpreter(venvPath) {
+  let config;
+  try {
+    config = fs.readFileSync(path$1.join(venvPath, "pyvenv.cfg"), "utf8");
+  } catch {
+    return { kind: "none" };
+  }
+  const home = config.split("\n").map((line) => line.match(PYVENV_HOME)).find((match) => match != null)?.[1];
+  if (!home) return { kind: "none" };
+  const resourceMarked = home.match(BUNDLED_INTERPRETER_HOME);
+  if (!resourceMarked) return { kind: "none" };
+  const bundle = resourceMarked[1];
+  return fs.existsSync(bundle) ? { kind: "bundled", bundle } : { kind: "missing", bundle };
+}
+function legacyEnvironmentReport(support) {
+  const lines = [];
+  for (const venv of legacyVenvPaths(support)) {
+    const resolution = venvInterpreter(venv);
+    if (resolution.kind === "none") continue;
+    lines.push(
+      resolution.kind === "missing" ? `The pre-split environment at ${venv} names an interpreter bundle that is not on disk (${resolution.bundle}); it is left exactly as it is.` : `The pre-split environment at ${venv} is built on the interpreter inside ${resolution.bundle}; it is left exactly as it is, and this instance does not use it.`
     );
   }
+  return lines;
 }
-const backendConfig = loadConfig();
-const apiConfig = {
-  baseUrl: backendConfig.VITE_LOCAL_OPERATOR_API_URL
-};
 const SHEBANG = /^#!([^\r\n]+)\r?\n/;
 const PYTHON_NAME = /[/\\]python(?:\d+(?:\.\d+)*)?$/;
 const SERVE_ENTRYPOINT = "from local_operator.cli import main; main()";
@@ -2182,6 +3313,27 @@ class BackendServiceManager {
   /** Survives relay recreation so notifications never silently detach
    * when the backend URL rotates. */
   streamObserver = null;
+  /**
+   * The machine-wide desktop feed relay, rebuilt when the backend URL rotates
+   * for the same reason the stream relay is: a subscription must never pin a
+   * stale origin. Held HERE rather than in `index.ts` because the desktop
+   * bearer lives in this class and is never exposed — the feed needs it to
+   * carry an SSE connection and to beat the presence lease.
+   */
+  feedRelay = null;
+  feedRelayUrl = "";
+  /** Both survive relay recreation, so a URL rotation cannot silently detach
+   * the banner path or leave the sidebar reading a stale connection state. */
+  feedFrameObserver = null;
+  feedStateObserver = null;
+  /**
+   * The window/focus/displayed-session answers the presence claim carries.
+   *
+   * Set by main once a window can exist — before that a windowless app is the
+   * honest answer, which is also the reference's own default for a client that
+   * has not said anything yet.
+   */
+  presenceContext = null;
   /**
    * Called every time the backend becomes reachable and authenticated.
    *
@@ -2242,6 +3394,60 @@ class BackendServiceManager {
     this.streamObserver = observer;
     this.streamRelay?.observe(observer);
   }
+  /**
+   * The machine-wide feed, rebuilt when the backend URL rotates.
+   *
+   * Lazily constructed for the same reason `getStreamRelay` is: the desktop
+   * token is minted inside `start()`, so a relay built at `app.whenReady()`
+   * would capture `null` and never authenticate. Callers reach for it from the
+   * backend-ready hook, which is the first moment the token exists.
+   */
+  getDesktopFeedRelay() {
+    if (!this.feedRelay || this.feedRelayUrl !== this.backendUrl) {
+      this.feedRelay?.stop();
+      this.feedRelay = new DesktopFeedRelay(
+        this.backendUrl,
+        this.desktopToken,
+        {
+          request: (input) => this.requestDesktop(input),
+          // The presence beat is a contract op, so it travels the same
+          // authenticated transport as every other control and the token
+          // never leaves this class.
+          beatPresence: (presence) => this.requestDesktop({
+            op: "sessions.presence",
+            ...presence
+          }),
+          // What this app can say about its own window. Supplied by main
+          // (it owns the window and the notifier's displayed session) and
+          // read at each beat rather than captured, so a window that opens
+          // or closes mid-lease is reported without a new relay.
+          presenceContext: () => this.presenceContext?.() ?? null
+        }
+      );
+      this.feedRelay.observe(this.feedFrameObserver);
+      this.feedRelay.watchState(this.feedStateObserver);
+      this.feedRelayUrl = this.backendUrl;
+    }
+    return this.feedRelay;
+  }
+  /**
+   * Supply the presence claim's window state.
+   *
+   * Separate from `observeDesktopFeed` because it is a different question
+   * asked of a different owner: the observers are consumers of frames, and
+   * this is main's answer about itself. Applied to a relay that already
+   * exists, so the ordering between "start the feed" and "make a window" does
+   * not decide whether the claim is complete.
+   */
+  providePresenceContext(context) {
+    this.presenceContext = context;
+  }
+  observeDesktopFeed(frameObserver, stateObserver) {
+    this.feedFrameObserver = frameObserver;
+    this.feedStateObserver = stateObserver;
+    this.feedRelay?.observe(frameObserver);
+    this.feedRelay?.watchState(stateObserver);
+  }
   requestDesktop(input) {
     return requestDesktop(input, this.backendUrl, this.desktopToken);
   }
@@ -2280,24 +3486,12 @@ class BackendServiceManager {
         error
       );
     }
-    if (process.platform === "win32") {
-      this.venvPath = path$1.join(this.appDataPath, "local-operator-venv");
-    } else if (process.platform === "darwin") {
-      this.venvPath = path$1.join(
-        electron.app.getPath("home"),
-        "Library",
-        "Application Support",
-        "Local Operator",
-        "local-operator-venv"
-      );
-    } else {
-      this.venvPath = path$1.join(
-        electron.app.getPath("home"),
-        ".config",
-        "local-operator",
-        "local-operator-venv"
-      );
-    }
+    this.venvPath = managedVenvPath({
+      platform: process.platform,
+      home: electron.app.getPath("home"),
+      appDataPath: this.appDataPath,
+      packaged: electron.app.isPackaged
+    });
     this.loadShellEnvironment();
     logger.info(
       `Backend Service Manager initialized. Disabled: ${this.isDisabled}`,
@@ -2551,6 +3745,21 @@ class BackendServiceManager {
         windowsHide: true
       });
       if (stdout.trim()) {
+        if (process.platform === "darwin" && isLegacyManagedCommand(
+          stdout.trim().split("\n")[0],
+          path$1.join(
+            electron.app.getPath("home"),
+            "Library",
+            "Application Support",
+            "Local Operator"
+          )
+        )) {
+          logger.info(
+            "The PATH command belongs to a legacy managed environment; preparing a separate backend instead",
+            LogFileType.BACKEND
+          );
+          return false;
+        }
         logger.info(
           `local-operator command found at: ${stdout.trim()}`,
           LogFileType.BACKEND
@@ -2720,6 +3929,12 @@ class BackendServiceManager {
     this.desktopToken = node_crypto.randomBytes(32).toString("hex");
     let captured = null;
     try {
+      this.venvPath = managedVenvPath({
+        platform: process.platform,
+        home: electron.app.getPath("home"),
+        appDataPath: this.appDataPath,
+        packaged: electron.app.isPackaged
+      });
       const globalInstall = await this.checkLocalOperatorExists();
       const env = this.backendSpawnEnv();
       let interpreters;
@@ -3106,300 +4321,8 @@ class BackendServiceManager {
     return this.restartPromise;
   }
 }
-const linuxInstallScriptRaw = '#!/bin/bash\n# Local Operator Backend Installation Script for Linux\n# This script sets up a virtual environment for the Local Operator backend\n# without requiring sudo or admin privileges.\n\n# Exit on error, undefined variables, and failed pipe commands\nset -e  # Exit immediately if a command exits with a non-zero status\nset -u  # Error on unset variables\nset -o pipefail  # Fail if any command in a pipe fails\n\n# Configuration\n# Variables APP_NAME and MIN_PYTHON_VERSION removed as they were unused\nVENV_NAME="local-operator-venv"\nAPP_DATA_DIR="${HOME}/.config/local-operator"\nVENV_PATH="${APP_DATA_DIR}/${VENV_NAME}"\nLOG_FILE="${APP_DATA_DIR}/backend-install.log"\nTIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")\n\n# Keep CPython\'s bytecode cache out of the application directory.\n#\n# Same reason as the macOS script: an interpreter writing __pycache__/*.pyc\n# beside its own stdlib sources writes into the installed tree. Linux does not\n# code-seal the app the way macOS does, so this is uniformity and hygiene here\n# rather than the load-bearing fix it is on macOS - but it is also the value a\n# standalone run of this script has to agree with, because the app and the\n# script must not disagree about where bytecode goes.\n: "${PYTHONPYCACHEPREFIX:=${APP_DATA_DIR}/python-bytecode-cache}"\nexport PYTHONPYCACHEPREFIX\n\n# Create app data directory if it doesn\'t exist\nif ! mkdir -p "${APP_DATA_DIR}"; then\n  echo "ERROR: Unable to create app data directory at ${APP_DATA_DIR}"\n  echo "Please check permissions and try again."\n  exit 1\nfi\n\n# Handle cleanup on script exit\ncleanup() {\n  # Remove any temporary files created during execution\n  if [ -f "${APP_DATA_DIR}/get-pip.py" ]; then\n    rm -f "${APP_DATA_DIR}/get-pip.py"\n  fi\n  if [ -n "${FFMPEG_TEMP_ARCHIVE:-}" ] && [ -f "${FFMPEG_TEMP_ARCHIVE}" ]; then\n    log "Removing temporary FFmpeg archive: ${FFMPEG_TEMP_ARCHIVE}"\n    rm -f "${FFMPEG_TEMP_ARCHIVE}"\n  fi\n  echo "$(date): Cleanup completed."\n}\n\n# Set trap only for manual interruption (SIGINT, SIGTERM), not normal exits\ntrap cleanup SIGINT SIGTERM\n\n\n# Start logging\nexec > >(tee -a "${LOG_FILE}") 2>&1\necho "[${TIMESTAMP}]: Starting Local Operator backend installation..."\necho "[${TIMESTAMP}]: System information: $(uname -a)"\n\n# Function to log messages with timestamp (defined later, but used by FFmpeg section)\n_log_internal() {\n  local internal_timestamp\n  internal_timestamp=$(date +"%Y-%m-%d %H:%M:%S")\n  echo "[${internal_timestamp}] $1"\n}\n\n# --- FFmpeg Installation ---\nBIN_DIR="${APP_DATA_DIR}/bin"\nFFMPEG_BIN="${BIN_DIR}/ffmpeg" # Path to ffmpeg binary\n\n_log_internal "Ensuring bin directory exists: ${BIN_DIR}"\nif ! mkdir -p "${BIN_DIR}"; then\n    _log_internal "ERROR: Unable to create bin directory at ${BIN_DIR}"\n    exit 1\nfi\n\n# Check if FFmpeg is already installed and executable\nif [ -f "${FFMPEG_BIN}" ] && [ -x "${FFMPEG_BIN}" ]; then\n    _log_internal "FFmpeg already installed at ${FFMPEG_BIN}. Skipping download."\nelse\n    _log_internal "FFmpeg not found or not executable. Attempting to download and install FFmpeg..."\n\n    FFMPEG_DOWNLOAD_URL=""\n\n    LINUX_ARCH=$(uname -m)\n    if [[ "${LINUX_ARCH}" == "x86_64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-linux-x64"\n    elif [[ "${LINUX_ARCH}" == "aarch64" ]] || [[ "${LINUX_ARCH}" == "arm64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-linux-arm64"\n    else\n        _log_internal "Error: Unsupported CPU architecture for FFmpeg download: ${LINUX_ARCH}"\n        exit 1\n    fi\n\n    _log_internal "Downloading FFmpeg from: ${FFMPEG_DOWNLOAD_URL}"\n    if command -v curl >/dev/null 2>&1; then\n        if ! curl -L "${FFMPEG_DOWNLOAD_URL}" -o "${FFMPEG_BIN}"; then\n            _log_internal "Error: Failed to download FFmpeg using curl from ${FFMPEG_DOWNLOAD_URL}"\n            exit 1\n        fi\n    elif command -v wget >/dev/null 2>&1; then\n        if ! wget -O "${FFMPEG_BIN}" "${FFMPEG_DOWNLOAD_URL}"; then\n            _log_internal "Error: Failed to download FFmpeg using wget from ${FFMPEG_DOWNLOAD_URL}"\n            exit 1\n        fi\n    else\n        _log_internal "Error: Neither curl nor wget found. Cannot download FFmpeg."\n        exit 1\n    fi\n    _log_internal "FFmpeg binary downloaded successfully to ${FFMPEG_BIN}"\n\n    chmod +x "${FFMPEG_BIN}"\n    _log_internal "Set executable permissions for ${FFMPEG_BIN}"\n\n    # Verify FFmpeg is executable after download\n    if [ ! -f "${FFMPEG_BIN}" ] || [ ! -x "${FFMPEG_BIN}" ]; then\n        _log_internal "Error: FFmpeg binary not found or not executable after download."\n        exit 1\n    fi\nfi\n\n_log_internal "FFmpeg installation complete. FFmpeg binary is at: ${FFMPEG_BIN}"\n\n# Function to check if a command exists\ncommand_exists() {\n  command -v "$1" >/dev/null 2>&1\n}\n\n# Function to log messages with timestamp\nlog() {\n  local timestamp\n  timestamp=$(date +"%Y-%m-%d %H:%M:%S")\n  echo "[${timestamp}] $1"\n}\n\n# Function to display error messages and exit\nerror_exit() {\n  log "ERROR: $1" >&2\n  exit "${2:-1}"\n}\n\n# Function to check if Python binary is valid for current architecture\nis_valid_python_binary() {\n  local python_path="$1"\n  \n  # First check if file exists and is executable\n  if [ ! -f "${python_path}" ] || [ ! -x "${python_path}" ]; then\n    return 1\n  fi\n  \n  # Try to run a simple Python command to verify it works on current architecture\n  "${python_path}" -c "print(\'Testing Python executable\')" >/dev/null 2>&1\n  return $?\n}\n\n# Check for network connectivity to key servers\ncheck_connectivity() {\n  log "Checking network connectivity..."\n  local servers=("pypi.org" "bootstrap.pypa.io")\n  local has_connectivity=false\n  \n  for server in "${servers[@]}"; do\n    if command_exists curl; then\n      if curl --connect-timeout 5 -s "https://${server}" -o /dev/null; then\n        has_connectivity=true\n        break\n      fi\n    elif command_exists wget; then\n      if wget --timeout=5 -q --spider "https://${server}"; then\n        has_connectivity=true\n        break\n      fi\n    fi\n  done\n  \n  if [ "$has_connectivity" = false ]; then\n    log "WARNING: Network connectivity issues detected. This may affect installation."\n  else\n    log "Network connectivity confirmed."\n  fi\n}\n\n# Call connectivity check\ncheck_connectivity\n\n# Check if PYTHON_BIN is already set by the installer\nif [ -n "${PYTHON_BIN:-}" ]; then\n  log "Using Python executable provided by installer: ${PYTHON_BIN}"\n  # Verify the provided Python binary works on this architecture\n  if ! is_valid_python_binary "${PYTHON_BIN}"; then\n    log "Warning: The provided Python binary is not compatible with this system architecture."\n    log "Will attempt to find a system Python installation instead."\n    PYTHON_BIN=""\n  fi\nfi\n\n# If PYTHON_BIN is empty or invalid, try to find a suitable Python installation\nif [ -z "${PYTHON_BIN:-}" ] || ! is_valid_python_binary "${PYTHON_BIN:-}"; then\n  # Try to find a suitable Python installation\n  log "Looking for a suitable Python installation..."\n  \n  # Try multiple possible locations to find Python\n  POSSIBLE_PYTHON_PATHS=(\n    # System paths first (more likely to be compatible with current architecture)\n    "/usr/local/bin/python3.12"\n    "/usr/bin/python3.12"\n    "/usr/local/bin/python3"\n    "/usr/bin/python3"\n    # From environment variable (set by the installer)\n    "${ELECTRON_RESOURCE_PATH:-}/python/bin/python3"\n    # Development paths\n    "$(dirname "$0")/../../../resources/python/bin/python3"\n    "$(pwd)/resources/python/bin/python3"\n  )\n\n  # Find the first Python that exists and is version 3.12+ and works on this architecture\n  PYTHON_BIN=""\n  for path in "${POSSIBLE_PYTHON_PATHS[@]}"; do\n    # Skip empty paths that might come from unset environment variables\n    if [ -z "${path}" ]; then\n      continue\n    fi\n    \n    if is_valid_python_binary "${path}"; then\n      # Check Python version\n      if PY_VERSION=$("${path}" -c "import sys; print(f\'{sys.version_info.major}.{sys.version_info.minor}\')" 2>/dev/null); then\n        MAJOR=$(echo "${PY_VERSION}" | cut -d. -f1)\n        MINOR=$(echo "${PY_VERSION}" | cut -d. -f2)\n        if [ "${MAJOR}" -eq 3 ] && [ "${MINOR}" -ge 12 ]; then\n          PYTHON_BIN="${path}"\n          log "Found suitable Python ${PY_VERSION} at ${path}"\n          break\n        else\n          log "Python at ${path} is version ${PY_VERSION}, which is below the required 3.12+"\n        fi\n      fi\n    else\n      if [ -f "${path}" ]; then\n        log "Python at ${path} exists but is not compatible with this system architecture"\n      fi\n    fi\n  done\n\n  # If we couldn\'t find a suitable Python, exit with error\n  if [ -z "${PYTHON_BIN:-}" ]; then\n    error_exit "No suitable Python installation found (version 3.12 or higher required).\\nPlease install Python 3.12 or higher before running this script.\\nYou can install Python from https://www.python.org/downloads/"\n  fi\nfi\n\necho "Using Python: $PYTHON_BIN"\n"$PYTHON_BIN" --version || {\n  echo "Error: Failed to run Python. Please ensure it is executable and accessible."\n  echo "System architecture: $(uname -m)"\n  echo "Python binary architecture: $(file "$PYTHON_BIN" 2>/dev/null || echo \'Unable to determine\')"\n  exit 1\n}\n\n# Detect the Linux distribution to provide specific instructions\nif command_exists lsb_release; then\n  DISTRO=$(lsb_release -is)\n  DISTRO_VERSION=$(lsb_release -rs)\n  echo "Detected Linux distribution: $DISTRO $DISTRO_VERSION"\nelif [ -f /etc/os-release ]; then\n  DISTRO=$(grep -oP \'(?<=^ID=).+\' /etc/os-release | tr -d \'"\')\n  DISTRO_VERSION=$(grep -oP \'(?<=^VERSION_ID=).+\' /etc/os-release | tr -d \'"\')\n  echo "Detected Linux distribution: $DISTRO $DISTRO_VERSION"\nelse\n  DISTRO="unknown"\n  echo "Unable to detect Linux distribution"\nfi\n\n# Check if Python has venv module and ensurepip available\nlog "Checking for venv module and ensurepip availability..."\nVENV_AVAILABLE=0\nENSUREPIP_AVAILABLE=0\n\n"${PYTHON_BIN}" -c "import venv" > /dev/null 2>&1 || VENV_AVAILABLE=1\n"${PYTHON_BIN}" -c "import ensurepip" > /dev/null 2>&1 || ENSUREPIP_AVAILABLE=1\n\n# If venv is still not available, try to use virtualenv as a fallback\nif [ $VENV_AVAILABLE -ne 0 ]; then\n  echo "venv module is not available. Checking for virtualenv as an alternative..."\n  \n  # Check if virtualenv is already installed\n  if "$PYTHON_BIN" -c "import virtualenv" > /dev/null 2>&1; then\n    echo "virtualenv is available, will use it instead of venv"\n  else\n    echo "ERROR: Neither venv nor virtualenv is available."\n    echo "Python 3.12 and venv should be installed as package dependencies."\n    echo "Please ensure Python 3.12 and venv are properly installed on your system."\n    exit 1\n  fi\nfi\n\n# Create virtual environment if it doesn\'t exist\nif [ ! -d "$VENV_PATH" ]; then\n  echo "Creating virtual environment at $VENV_PATH..."\n  # Remove any potentially corrupted virtual environment\n  if [ -e "$VENV_PATH" ]; then\n    echo "Removing existing but potentially corrupted venv directory..."\n    rm -rf "$VENV_PATH"\n  fi\n  \n  # Make sure parent directory exists and is writable\n  mkdir -p "$(dirname "$VENV_PATH")"\n  \n  # Try different methods to create a virtual environment\n  VENV_CREATE_STATUS=1\n  \n  # First try with venv if available\n  if [ $VENV_AVAILABLE -eq 0 ] && [ $ENSUREPIP_AVAILABLE -eq 0 ]; then\n    echo "Creating virtual environment using venv module..."\n    "$PYTHON_BIN" -m venv "$VENV_PATH"\n    VENV_CREATE_STATUS=$?\n  fi\n  \n  # If venv failed, try virtualenv\n  if [ $VENV_CREATE_STATUS -ne 0 ]; then\n    echo "venv creation failed with status $VENV_CREATE_STATUS. Falling back to virtualenv..."\n    if command_exists virtualenv; then\n      virtualenv -p "$PYTHON_BIN" "$VENV_PATH"\n      VENV_CREATE_STATUS=$?\n    elif "$PYTHON_BIN" -m pip list | grep -q virtualenv; then\n      "$PYTHON_BIN" -m virtualenv -p "$PYTHON_BIN" "$VENV_PATH"\n      VENV_CREATE_STATUS=$?\n    else\n      echo "ERROR: Both venv and virtualenv are unavailable or failed."\n      echo "Python 3.12 and venv should be installed as package dependencies."\n      echo "Please ensure Python 3.12 and venv are properly installed on your system."\n      echo "You can install Python 3.12 from https://www.python.org/downloads/"\n      exit 1\n    fi\n  fi\n  \n  # Check if virtual environment creation was successful\n  if [ $VENV_CREATE_STATUS -ne 0 ]; then\n    log "ERROR: Failed to create virtual environment. Exit code: $VENV_CREATE_STATUS"\n    log "Virtual environment path: $VENV_PATH"\n    log "Python binary used: $PYTHON_BIN"\n    ls -la "$(dirname "$VENV_PATH")" || true\n    log "Python executable permissions:"\n    ls -la "$PYTHON_BIN" || true\n    \n    # Check for common issues\n    log "Checking for common virtual environment creation issues..."\n    \n    # Check disk space\n    df -h "$(dirname "$VENV_PATH")" || true\n    \n    # Check if directory is writable\n    if [ ! -w "$(dirname "$VENV_PATH")" ]; then\n      log "ERROR: Directory $(dirname "$VENV_PATH") is not writable"\n    fi\n    \n    # Try to create a minimal virtual environment manually as a last resort\n    log "Attempting to create a minimal virtual environment manually..."\n    mkdir -p "$VENV_PATH/bin" || error_exit "Could not create directory $VENV_PATH/bin"\n    echo "#!/bin/bash" > "$VENV_PATH/bin/activate"\n    echo "export VIRTUAL_ENV=\\"$VENV_PATH\\"" >> "$VENV_PATH/bin/activate"\n    echo "export PATH=\\"$VENV_PATH/bin:\\$PATH\\"" >> "$VENV_PATH/bin/activate"\n    echo "unset PYTHONHOME" >> "$VENV_PATH/bin/activate"\n    chmod +x "$VENV_PATH/bin/activate" || error_exit "Could not set execute permissions on activate script"\n    \n    # Create symlinks to the system Python\n    ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python" || log "WARNING: Failed to create symlink for python"\n    ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python3" || log "WARNING: Failed to create symlink for python3"\n    \n    # Try to bootstrap pip\n    log "Bootstrapping pip in the minimal virtual environment..."\n    if command_exists curl; then\n      curl -s https://bootstrap.pypa.io/get-pip.py -o "$APP_DATA_DIR/get-pip.py" || log "WARNING: Failed to download get-pip.py"\n    elif command_exists wget; then\n      wget -q -O "$APP_DATA_DIR/get-pip.py" https://bootstrap.pypa.io/get-pip.py || log "WARNING: Failed to download get-pip.py"\n    else\n      log "ERROR: Neither curl nor wget available to download get-pip.py"\n      error_exit "Installation cannot continue without being able to download pip"\n    fi\n    \n    # shellcheck disable=SC1090\n    source "$VENV_PATH/bin/activate" && python "$APP_DATA_DIR/get-pip.py" --no-warn-script-location\n    \n    if [ ! -f "$VENV_PATH/bin/pip" ]; then\n      error_exit "Failed to create even a minimal virtual environment."\n    else\n      log "Created a minimal virtual environment as a fallback."\n    fi\n  else\n    log "Successfully created virtual environment"\n  fi\nfi\n\n# Verify the virtual environment structure\necho "Verifying virtual environment structure..."\nif [ ! -f "$VENV_PATH/bin/python" ]; then\n  echo "Python executable missing in virtual environment, creating symlink..."\n  ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python"\nfi\n\nif [ ! -f "$VENV_PATH/bin/pip" ]; then\n  echo "pip missing in virtual environment, attempting to bootstrap it..."\n  curl -s https://bootstrap.pypa.io/get-pip.py -o "$APP_DATA_DIR/get-pip.py"\n  "$VENV_PATH/bin/python" "$APP_DATA_DIR/get-pip.py" --no-warn-script-location\n  \n  if [ ! -f "$VENV_PATH/bin/pip" ]; then\n    echo "ERROR: Failed to bootstrap pip in the virtual environment"\n    exit 1\n  fi\nfi\n\necho "Virtual environment structure verified"\n\n# Activate virtual environment and install local-operator\necho "Installing local-operator in virtual environment..."\nsource "$VENV_PATH/bin/activate"\n\necho "Upgrading pip..."\npython -m pip install --upgrade pip || {\n  echo "WARNING: Failed to upgrade pip. Will try to continue with existing pip version."\n  pip --version\n}\n\n# Check network connectivity to PyPI\necho "Checking network connectivity to PyPI..."\nif command_exists curl; then\n  curl -s https://pypi.org/pypi/local-operator/json -o /dev/null || {\n    echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."\n  }\nelif command_exists wget; then\n  wget -q --spider https://pypi.org/pypi/local-operator/json || {\n    echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."\n  }\nfi\n\necho "Installing local-operator package..."\npython -m pip install --verbose local-operator || {\n  echo "ERROR: Failed to install local-operator package. Exit code: $?"\n  echo "Python version:"\n  python --version\n  echo "pip version:"\n  pip --version\n  echo "Available pip packages:"\n  pip list\n  exit 1\n}\necho "local-operator installation successful"\n\n# Verify installation\nif [ -f "$VENV_PATH/bin/local-operator" ]; then\n  log "Local Operator backend installed successfully!"\n  \n  # Show more information about the installed binary\n  ls -la "$VENV_PATH/bin/local-operator" || true\n  file "$VENV_PATH/bin/local-operator" 2>/dev/null || log "Note: \'file\' command not available"\n  \n  # Try to run the version command with full error output\n  log "Testing local-operator binary..."\n  "$VENV_PATH/bin/local-operator" --version || {\n    log "ERROR: local-operator binary exists but failed to execute. Exit code: $?"\n    log "Binary details:"\n    file "$VENV_PATH/bin/local-operator" 2>/dev/null || log "Note: \'file\' command not available"\n    log "Binary permissions:"\n    ls -la "$VENV_PATH/bin/local-operator" || true\n    log ""\n    log "This could be due to missing dependencies or architecture incompatibility."\n    log "Try running the binary manually to see specific errors."\n    \n    # Don\'t exit here - just warn the user\n    log "WARNING: Installation completed but binary verification failed."\n  }\n  \n  # Create a summary of the installation\n  SUMMARY_FILE="${APP_DATA_DIR}/installation-summary-${TIMESTAMP}.txt"\n  {\n    echo "=== Local Operator Backend Installation Summary ==="\n    echo "Timestamp: $(date)"\n    echo "Python Version: $("${PYTHON_BIN}" --version 2>&1)"\n    echo "Virtual Environment: ${VENV_PATH}"\n    echo "Binary Location: ${VENV_PATH}/bin/local-operator"\n    echo "To activate the virtual environment, run: source ${VENV_PATH}/bin/activate"\n    echo "To test the installation, run: ${VENV_PATH}/bin/local-operator --version"\n    echo "Log file: ${LOG_FILE}"\n    echo "=================================================="\n  } > "${SUMMARY_FILE}"\n  \n  log "Installation summary saved to: ${SUMMARY_FILE}"\nelse\n  log "Error: Failed to install Local Operator backend. Binary not found."\n  log "Contents of bin directory:"\n  ls -la "$VENV_PATH/bin/" || true\n  log "Check the log file for details: ${LOG_FILE}"\n  error_exit "Installation failed. Binary not installed properly."\nfi\n\nlog "Installation completed successfully at $(date)"\n\n# Clean up temporary files now that installation is complete\ncleanup\n\n# Print final instructions\nlog ""\nlog "=== INSTALLATION COMPLETE ==="\nlog "You can now use the Local Operator backend by running: ${VENV_PATH}/bin/local-operator"\nlog "Installation directory: ${VENV_PATH}"\nlog "Log file: ${LOG_FILE}"\nlog "================================"\n';
-const macosInstallScriptRaw = `#!/bin/bash
-# Local Operator Backend Installation Script for macOS
-# This script uses the bundled standalone Python and sets up a virtual environment for the Local Operator backend.
-
-set -e  # Exit immediately if a command exits with a non-zero status
-
-# Configuration
-APP_NAME="Local Operator"
-VENV_NAME="local-operator-venv"
-APP_DATA_DIR="$HOME/Library/Application Support/$APP_NAME"
-VENV_PATH="$APP_DATA_DIR/$VENV_NAME"
-LOG_FILE="$APP_DATA_DIR/backend-install.log"
-
-# Keep CPython's bytecode cache out of the application bundle.
-#
-# The bundled interpreter writes __pycache__/*.pyc beside the stdlib sources it
-# imports, and those sources live inside the code-signed .app - which is the
-# build's own extraResource. Every such write is a change to a sealed resource:
-# measured on an installed 0.17.3, \`codesign --verify --deep\` reported 308
-# \`file added:\` violations, all of them .pyc, and ShipIt then refuses the
-# in-place update with -67028 errSecCSBadBundleFormat. A file codesign reports
-# as *added* can be deleted and the seal comes back; a *modified* one cannot,
-# which is why nothing may ship a .pyc at all. The app sets this variable when
-# it spawns us; defaulting it here keeps a standalone run of this script in
-# agreement with the app about where bytecode goes. It is not a complete answer:
-# the app does not spawn every python that runs this interpreter, and a python
-# started by something else - a shell, a CLI script, an agent - has no prefix at
-# all (measured: a venv over this tree wrote 25 .pyc into it that way). The half
-# that covers those is the app's seal on the tree itself
-# (src/main/python-bytecode-cache.ts), which a standalone run of this script does
-# not apply. $HOME is the right place for the cache for the same reason the venv
-# lives there: it is never inside the thing that gets signed and swapped.
-: "\${PYTHONPYCACHEPREFIX:=$APP_DATA_DIR/python-bytecode-cache}"
-export PYTHONPYCACHEPREFIX
-
-# Determine CPU Architecture and Python Directory Name
-ARCH=$(uname -m)
-PYTHON_DIR_NAME="python" # Default for x86_64
-PYTHON_ARCH_NAME="x86_64" # For logging
-
-if [[ "$ARCH" == "x86_64" ]]; then
-  PYTHON_DIR_NAME="python"
-  PYTHON_ARCH_NAME="x86_64"
-elif [[ "$ARCH" == "arm64" ]] || [[ "$ARCH" == "aarch64" ]]; then # arm64 is what uname -m returns on Apple Silicon
-  PYTHON_DIR_NAME="python_aarch64"
-  PYTHON_ARCH_NAME="aarch64"
-else
-  echo "Error: Unsupported CPU architecture: $ARCH"
-  exit 1
-fi
-echo "Detected CPU architecture: $ARCH, using Python directory name: $PYTHON_DIR_NAME"
-
-# Check if PYTHON_BIN is already set by the installer
-if [[ -n "$PYTHON_BIN" ]]; then
-  echo "Using Python executable provided by installer: $PYTHON_BIN"
-else
-  # Get the path to the bundled Python based on architecture
-  # Try multiple possible locations to find Python
-  POSSIBLE_PYTHON_PATHS=(
-    # From environment variable (set by the installer)
-    "$ELECTRON_RESOURCE_PATH/$PYTHON_DIR_NAME/bin/python3"
-    # Absolute paths for packaged app
-    "/Applications/Local Operator.app/Contents/Resources/$PYTHON_DIR_NAME/bin/python3"
-    "$HOME/Applications/Local Operator.app/Contents/Resources/$PYTHON_DIR_NAME/bin/python3"
-    # Development paths
-    "$(dirname "$0")/../../../resources/$PYTHON_DIR_NAME/bin/python3"
-    "$(pwd)/resources/$PYTHON_DIR_NAME/bin/python3"
-    # System Python as last resort (less ideal as it might not be the version we tested with)
-    "/usr/bin/python3"
-  )
-
-  # Find the first Python that exists
-  PYTHON_BIN=""
-  echo "Searching for Python in the following locations for $PYTHON_ARCH_NAME architecture (using directory $PYTHON_DIR_NAME):"
-  for path in "\${POSSIBLE_PYTHON_PATHS[@]}"; do
-    echo "  - Checking $path"
-    if [[ -f "$path" && -x "$path" ]]; then
-      PYTHON_BIN="$path"
-      echo "Found Python at $path"
-      break
-    else
-      echo "    Not found or not executable."
-    fi
-  done
-
-  # If we couldn't find Python, try to use the system Python
-  if [[ -z "$PYTHON_BIN" ]]; then
-    echo "Bundled Python for $PYTHON_ARCH_NAME not found in directory $PYTHON_DIR_NAME. Attempting to use system Python..."
-    if command -v python3 &>/dev/null; then
-      PYTHON_BIN=$(command -v python3)
-      echo "Warning: Using system Python at $PYTHON_BIN. This may lead to unexpected behavior."
-    else
-      echo "Error: Could not find a suitable Python executable. Tried the following paths for $PYTHON_ARCH_NAME (expected in $PYTHON_DIR_NAME):"
-      for path in "\${POSSIBLE_PYTHON_PATHS[@]}"; do
-        echo "  - $path (failed)"
-      done
-      exit 1
-    fi
-  fi
-fi
-
-# Create app data directory if it doesn't exist
-mkdir -p "$APP_DATA_DIR"
-
-# Start logging - capture everything and ensure it's visible to parent process
-exec > >(tee -a "$LOG_FILE") 2> >(tee -a "$LOG_FILE" >&2)
-echo "=============================================="
-echo "$(date): Starting Local Operator backend installation..."
-echo "=============================================="
-echo "Python bin path: $PYTHON_BIN"
-echo "Virtual environment path: $VENV_PATH"
-echo "App data directory: $APP_DATA_DIR"
-echo "Log file: $LOG_FILE"
-echo "=============================================="
-
-# --- FFmpeg Installation ---
-BIN_DIR="$APP_DATA_DIR/bin"
-FFMPEG_BIN="$BIN_DIR/ffmpeg"
-
-echo "Ensuring bin directory exists: $BIN_DIR"
-mkdir -p "$BIN_DIR"
-
-# Check if FFmpeg is already installed and executable
-if [ -f "$FFMPEG_BIN" ] && [ -x "$FFMPEG_BIN" ]; then
-    echo "FFmpeg already installed at $FFMPEG_BIN. Skipping download."
-else
-    echo "FFmpeg not found or not executable. Attempting to download and install FFmpeg..."
-
-    FFMPEG_DOWNLOAD_URL=""
-
-    if [[ "$ARCH" == "x86_64" ]]; then
-        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-mac-x64"
-    elif [[ "$ARCH" == "arm64" ]] || [[ "$ARCH" == "aarch64" ]]; then
-        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-mac-arm64"
-    else
-        echo "Error: Unsupported CPU architecture for FFmpeg download: $ARCH"
-        exit 1
-    fi
-
-    echo "Downloading FFmpeg from: $FFMPEG_DOWNLOAD_URL"
-    if curl -L "$FFMPEG_DOWNLOAD_URL" -o "$FFMPEG_BIN"; then
-        echo "FFmpeg downloaded successfully to $FFMPEG_BIN"
-        chmod +x "$FFMPEG_BIN"
-        echo "Set executable permissions for $FFMPEG_BIN"
-    else
-        echo "Error: Failed to download FFmpeg from $FFMPEG_DOWNLOAD_URL"
-        exit 1
-    fi
-
-    # Verify FFmpeg is executable after download
-    if [ ! -f "$FFMPEG_BIN" ] || [ ! -x "$FFMPEG_BIN" ]; then
-        echo "Error: FFmpeg binary not found or not executable after download."
-        exit 1
-    fi
-fi
-
-echo "FFmpeg installation complete. FFmpeg binary is at: $FFMPEG_BIN"
-# --- End FFmpeg Installation ---
-
-# Verify bundled Python exists
-if [ ! -f "$PYTHON_BIN" ]; then
-  echo "Error: Bundled Python not found at $PYTHON_BIN"
-  echo "Please ensure standalone Python is properly installed in the application resources."
-  exit 1
-fi
-
-# Make sure Python binary is executable
-chmod +x "$PYTHON_BIN"
-echo "Using bundled Python: $PYTHON_BIN"
-"$PYTHON_BIN" --version
-
-# Check if Python has venv module available
-echo "Checking for venv module availability..."
-"$PYTHON_BIN" -m venv --help > /dev/null 2>&1 || {
-  echo "ERROR: Python venv module not available in the Python installation"
-  echo "Python details:"
-  "$PYTHON_BIN" --version
-  "$PYTHON_BIN" -c "import sys; print('Prefix:', sys.prefix); print('Exec Prefix:', sys.exec_prefix)"
-  "$PYTHON_BIN" -c "import sys; print('Modules path:'); print('\\n'.join(sys.path))"
-  exit 1
-}
-echo "venv module is available"
-
-# Create virtual environment if it doesn't exist
-if [ ! -d "$VENV_PATH" ]; then
-  echo "Creating virtual environment at $VENV_PATH..."
-  # Remove any potentially corrupted virtual environment
-  if [ -e "$VENV_PATH" ]; then
-    echo "Removing existing but potentially corrupted venv directory..."
-    rm -rf "$VENV_PATH"
-  fi
-  
-  # Make sure parent directory exists and is writable
-  mkdir -p "$(dirname "$VENV_PATH")"
-  
-  # Create the virtual environment with verbosity
-  "$PYTHON_BIN" -m venv "$VENV_PATH" || {
-    echo "ERROR: Failed to create virtual environment. Exit code: $?"
-    echo "Virtual environment path: $VENV_PATH"
-    echo "Python binary used: $PYTHON_BIN"
-    ls -la "$(dirname "$VENV_PATH")"
-    echo "Python executable permissions:"
-    ls -la "$PYTHON_BIN"
-    exit 1
-  }
-  echo "Successfully created virtual environment"
-fi
-
-# Verify the virtual environment structure
-echo "Verifying virtual environment structure..."
-if [ ! -f "$VENV_PATH/bin/python" ] || [ ! -f "$VENV_PATH/bin/pip" ]; then
-  echo "ERROR: Virtual environment is missing critical components"
-  echo "Contents of virtual environment directory:"
-  ls -la "$VENV_PATH"
-  if [ -d "$VENV_PATH/bin" ]; then
-    echo "Contents of bin directory:"
-    ls -la "$VENV_PATH/bin"
-  fi
-  exit 1
-fi
-echo "Virtual environment structure verified"
-
-# Activate virtual environment and install local-operator
-echo "Installing local-operator in virtual environment..."
-source "$VENV_PATH/bin/activate"
-
-echo "Upgrading pip..."
-python -m pip install --upgrade pip || {
-  echo "ERROR: Failed to upgrade pip. Exit code: $?"
-  echo "pip version before failing:"
-  pip --version
-  exit 1
-}
-echo "pip upgrade successful:"
-pip --version
-
-# Check network connectivity to PyPI
-echo "Checking network connectivity to PyPI..."
-curl -s https://pypi.org/pypi/local-operator/json -o /dev/null || {
-  echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."
-  echo "Attempting to ping common domains to diagnose network issues:"
-  ping -c 1 google.com || echo "Cannot ping google.com"
-  ping -c 1 pypi.org || echo "Cannot ping pypi.org"
-}
-
-echo "Installing local-operator package..."
-python -m pip install --upgrade --verbose local-operator || {
-  echo "ERROR: Failed to install local-operator package. Exit code: $?"
-  echo "Python version:"
-  python --version
-  echo "pip version:"
-  pip --version
-  echo "Available pip packages:"
-  pip list
-  echo "Pip config:"
-  pip config list
-  echo "Network diagnosis:"
-  curl -I https://pypi.org || echo "Cannot reach PyPI server"
-  exit 1
-}
-echo "local-operator installation successful"
-
-# Verify installation
-if [ -f "$VENV_PATH/bin/local-operator" ]; then
-  echo "Local Operator backend installed successfully!"
-  
-  # Show more information about the installed binary
-  ls -la "$VENV_PATH/bin/local-operator"
-  file "$VENV_PATH/bin/local-operator"
-  
-  # Try to run the version command with full error output
-  echo "Testing local-operator binary..."
-  "$VENV_PATH/bin/local-operator" --version || {
-    echo "ERROR: local-operator binary exists but failed to execute. Exit code: $?"
-    echo "Binary details:"
-    file "$VENV_PATH/bin/local-operator"
-    echo "Binary permissions:"
-    ls -la "$VENV_PATH/bin/local-operator"
-    echo "Dependencies:"
-    if command -v otool >/dev/null; then
-      otool -L "$VENV_PATH/bin/local-operator" || echo "Could not get dependencies with otool"
-    fi
-    exit 1
-  }
-else
-  echo "Error: Failed to install Local Operator backend. Binary not found."
-  echo "Contents of bin directory:"
-  ls -la "$VENV_PATH/bin/"
-  exit 1
-fi
-
-echo "$(date): Installation completed successfully."
-`;
+const linuxInstallScriptRaw = '#!/bin/bash\n# Local Operator Backend Installation Script for Linux\n# This script sets up a virtual environment for the Local Operator backend\n# without requiring sudo or admin privileges.\n\n# Exit on error, undefined variables, and failed pipe commands\nset -e  # Exit immediately if a command exits with a non-zero status\nset -u  # Error on unset variables\nset -o pipefail  # Fail if any command in a pipe fails\n\n# Configuration\n# Variables APP_NAME and MIN_PYTHON_VERSION removed as they were unused\nVENV_NAME="local-operator-venv"\nAPP_DATA_DIR="${HOME}/.config/local-operator"\nVENV_PATH="${APP_DATA_DIR}/${VENV_NAME}"\nLOG_FILE="${APP_DATA_DIR}/backend-install.log"\nTIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")\n\n# Which environment this installs into - the app\'s decision, handed in. See the\n# macOS script for why the script must not re-derive it (a packaged and an\n# unpackaged instance use different environments, and only the app knows which\n# it is); `LOCAL_OPERATOR_VENV_PATH` is set from `managedVenvPath`.\n: "${LOCAL_OPERATOR_VENV_PATH:=$VENV_PATH}"\nVENV_PATH="$LOCAL_OPERATOR_VENV_PATH"\n\n# Keep CPython\'s bytecode cache out of the application directory.\n#\n# Same reason as the macOS script: an interpreter writing __pycache__/*.pyc\n# beside its own stdlib sources writes into the installed tree. Linux does not\n# code-seal the app the way macOS does, so this is uniformity and hygiene here\n# rather than the load-bearing fix it is on macOS - but it is also the value a\n# standalone run of this script has to agree with, because the app and the\n# script must not disagree about where bytecode goes.\n: "${PYTHONPYCACHEPREFIX:=${APP_DATA_DIR}/python-bytecode-cache}"\nexport PYTHONPYCACHEPREFIX\n\n# The refusal half of the pair, set rather than merged with whatever the caller\n# had: CPython reads the flag before its first import, so nothing this script\n# runs - `-m venv`, pip, the venv they create - can write a `__pycache__` at\n# all. Kept in step with the app\'s `withPythonBytecodeCache`, which sets both\n# variables on every python it spawns.\nexport PYTHONDONTWRITEBYTECODE=1\n\n# Create app data directory if it doesn\'t exist\nif ! mkdir -p "${APP_DATA_DIR}"; then\n  echo "ERROR: Unable to create app data directory at ${APP_DATA_DIR}"\n  echo "Please check permissions and try again."\n  exit 1\nfi\n\n# Handle cleanup on script exit\ncleanup() {\n  # Remove any temporary files created during execution\n  if [ -f "${APP_DATA_DIR}/get-pip.py" ]; then\n    rm -f "${APP_DATA_DIR}/get-pip.py"\n  fi\n  if [ -n "${FFMPEG_TEMP_ARCHIVE:-}" ] && [ -f "${FFMPEG_TEMP_ARCHIVE}" ]; then\n    log "Removing temporary FFmpeg archive: ${FFMPEG_TEMP_ARCHIVE}"\n    rm -f "${FFMPEG_TEMP_ARCHIVE}"\n  fi\n  echo "$(date): Cleanup completed."\n}\n\n# Set trap only for manual interruption (SIGINT, SIGTERM), not normal exits\ntrap cleanup SIGINT SIGTERM\n\n\n# Start logging\nexec > >(tee -a "${LOG_FILE}") 2>&1\necho "[${TIMESTAMP}]: Starting Local Operator backend installation..."\necho "[${TIMESTAMP}]: System information: $(uname -a)"\n\n# Function to log messages with timestamp (defined later, but used by FFmpeg section)\n_log_internal() {\n  local internal_timestamp\n  internal_timestamp=$(date +"%Y-%m-%d %H:%M:%S")\n  echo "[${internal_timestamp}] $1"\n}\n\n# --- FFmpeg Installation ---\nBIN_DIR="${APP_DATA_DIR}/bin"\nFFMPEG_BIN="${BIN_DIR}/ffmpeg" # Path to ffmpeg binary\n\n_log_internal "Ensuring bin directory exists: ${BIN_DIR}"\nif ! mkdir -p "${BIN_DIR}"; then\n    _log_internal "ERROR: Unable to create bin directory at ${BIN_DIR}"\n    exit 1\nfi\n\n# Check if FFmpeg is already installed and executable\nif [ -f "${FFMPEG_BIN}" ] && [ -x "${FFMPEG_BIN}" ]; then\n    _log_internal "FFmpeg already installed at ${FFMPEG_BIN}. Skipping download."\nelse\n    _log_internal "FFmpeg not found or not executable. Attempting to download and install FFmpeg..."\n\n    FFMPEG_DOWNLOAD_URL=""\n\n    LINUX_ARCH=$(uname -m)\n    if [[ "${LINUX_ARCH}" == "x86_64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-linux-x64"\n    elif [[ "${LINUX_ARCH}" == "aarch64" ]] || [[ "${LINUX_ARCH}" == "arm64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-linux-arm64"\n    else\n        _log_internal "Error: Unsupported CPU architecture for FFmpeg download: ${LINUX_ARCH}"\n        exit 1\n    fi\n\n    _log_internal "Downloading FFmpeg from: ${FFMPEG_DOWNLOAD_URL}"\n    if command -v curl >/dev/null 2>&1; then\n        if ! curl -L "${FFMPEG_DOWNLOAD_URL}" -o "${FFMPEG_BIN}"; then\n            _log_internal "Error: Failed to download FFmpeg using curl from ${FFMPEG_DOWNLOAD_URL}"\n            exit 1\n        fi\n    elif command -v wget >/dev/null 2>&1; then\n        if ! wget -O "${FFMPEG_BIN}" "${FFMPEG_DOWNLOAD_URL}"; then\n            _log_internal "Error: Failed to download FFmpeg using wget from ${FFMPEG_DOWNLOAD_URL}"\n            exit 1\n        fi\n    else\n        _log_internal "Error: Neither curl nor wget found. Cannot download FFmpeg."\n        exit 1\n    fi\n    _log_internal "FFmpeg binary downloaded successfully to ${FFMPEG_BIN}"\n\n    chmod +x "${FFMPEG_BIN}"\n    _log_internal "Set executable permissions for ${FFMPEG_BIN}"\n\n    # Verify FFmpeg is executable after download\n    if [ ! -f "${FFMPEG_BIN}" ] || [ ! -x "${FFMPEG_BIN}" ]; then\n        _log_internal "Error: FFmpeg binary not found or not executable after download."\n        exit 1\n    fi\nfi\n\n_log_internal "FFmpeg installation complete. FFmpeg binary is at: ${FFMPEG_BIN}"\n\n# Function to check if a command exists\ncommand_exists() {\n  command -v "$1" >/dev/null 2>&1\n}\n\n# Function to log messages with timestamp\nlog() {\n  local timestamp\n  timestamp=$(date +"%Y-%m-%d %H:%M:%S")\n  echo "[${timestamp}] $1"\n}\n\n# Function to display error messages and exit\nerror_exit() {\n  log "ERROR: $1" >&2\n  exit "${2:-1}"\n}\n\n# Function to check if Python binary is valid for current architecture\nis_valid_python_binary() {\n  local python_path="$1"\n  \n  # First check if file exists and is executable\n  if [ ! -f "${python_path}" ] || [ ! -x "${python_path}" ]; then\n    return 1\n  fi\n  \n  # Try to run a simple Python command to verify it works on current architecture\n  "${python_path}" -c "print(\'Testing Python executable\')" >/dev/null 2>&1\n  return $?\n}\n\n# Check for network connectivity to key servers\ncheck_connectivity() {\n  log "Checking network connectivity..."\n  local servers=("pypi.org" "bootstrap.pypa.io")\n  local has_connectivity=false\n  \n  for server in "${servers[@]}"; do\n    if command_exists curl; then\n      if curl --connect-timeout 5 -s "https://${server}" -o /dev/null; then\n        has_connectivity=true\n        break\n      fi\n    elif command_exists wget; then\n      if wget --timeout=5 -q --spider "https://${server}"; then\n        has_connectivity=true\n        break\n      fi\n    fi\n  done\n  \n  if [ "$has_connectivity" = false ]; then\n    log "WARNING: Network connectivity issues detected. This may affect installation."\n  else\n    log "Network connectivity confirmed."\n  fi\n}\n\n# Call connectivity check\ncheck_connectivity\n\n# Check if PYTHON_BIN is already set by the installer\nif [ -n "${PYTHON_BIN:-}" ]; then\n  log "Using Python executable provided by installer: ${PYTHON_BIN}"\n  # Verify the provided Python binary works on this architecture\n  if ! is_valid_python_binary "${PYTHON_BIN}"; then\n    log "Warning: The provided Python binary is not compatible with this system architecture."\n    log "Will attempt to find a system Python installation instead."\n    PYTHON_BIN=""\n  fi\nfi\n\n# If PYTHON_BIN is empty or invalid, try to find a suitable Python installation\nif [ -z "${PYTHON_BIN:-}" ] || ! is_valid_python_binary "${PYTHON_BIN:-}"; then\n  # Try to find a suitable Python installation\n  log "Looking for a suitable Python installation..."\n  \n  # Try multiple possible locations to find Python\n  POSSIBLE_PYTHON_PATHS=(\n    # System paths first (more likely to be compatible with current architecture)\n    "/usr/local/bin/python3.12"\n    "/usr/bin/python3.12"\n    "/usr/local/bin/python3"\n    "/usr/bin/python3"\n    # From environment variable (set by the installer)\n    "${ELECTRON_RESOURCE_PATH:-}/python/bin/python3"\n    # Development paths\n    "$(dirname "$0")/../../../resources/python/bin/python3"\n    "$(pwd)/resources/python/bin/python3"\n  )\n\n  # Find the first Python that exists and is version 3.12+ and works on this architecture\n  PYTHON_BIN=""\n  for path in "${POSSIBLE_PYTHON_PATHS[@]}"; do\n    # Skip empty paths that might come from unset environment variables\n    if [ -z "${path}" ]; then\n      continue\n    fi\n    \n    if is_valid_python_binary "${path}"; then\n      # Check Python version\n      if PY_VERSION=$("${path}" -c "import sys; print(f\'{sys.version_info.major}.{sys.version_info.minor}\')" 2>/dev/null); then\n        MAJOR=$(echo "${PY_VERSION}" | cut -d. -f1)\n        MINOR=$(echo "${PY_VERSION}" | cut -d. -f2)\n        if [ "${MAJOR}" -eq 3 ] && [ "${MINOR}" -ge 12 ]; then\n          PYTHON_BIN="${path}"\n          log "Found suitable Python ${PY_VERSION} at ${path}"\n          break\n        else\n          log "Python at ${path} is version ${PY_VERSION}, which is below the required 3.12+"\n        fi\n      fi\n    else\n      if [ -f "${path}" ]; then\n        log "Python at ${path} exists but is not compatible with this system architecture"\n      fi\n    fi\n  done\n\n  # If we couldn\'t find a suitable Python, exit with error\n  if [ -z "${PYTHON_BIN:-}" ]; then\n    error_exit "No suitable Python installation found (version 3.12 or higher required).\\nPlease install Python 3.12 or higher before running this script.\\nYou can install Python from https://www.python.org/downloads/"\n  fi\nfi\n\necho "Using Python: $PYTHON_BIN"\n"$PYTHON_BIN" --version || {\n  echo "Error: Failed to run Python. Please ensure it is executable and accessible."\n  echo "System architecture: $(uname -m)"\n  echo "Python binary architecture: $(file "$PYTHON_BIN" 2>/dev/null || echo \'Unable to determine\')"\n  exit 1\n}\n\n# Detect the Linux distribution to provide specific instructions\nif command_exists lsb_release; then\n  DISTRO=$(lsb_release -is)\n  DISTRO_VERSION=$(lsb_release -rs)\n  echo "Detected Linux distribution: $DISTRO $DISTRO_VERSION"\nelif [ -f /etc/os-release ]; then\n  DISTRO=$(grep -oP \'(?<=^ID=).+\' /etc/os-release | tr -d \'"\')\n  DISTRO_VERSION=$(grep -oP \'(?<=^VERSION_ID=).+\' /etc/os-release | tr -d \'"\')\n  echo "Detected Linux distribution: $DISTRO $DISTRO_VERSION"\nelse\n  DISTRO="unknown"\n  echo "Unable to detect Linux distribution"\nfi\n\n# Check if Python has venv module and ensurepip available\nlog "Checking for venv module and ensurepip availability..."\nVENV_AVAILABLE=0\nENSUREPIP_AVAILABLE=0\n\n"${PYTHON_BIN}" -c "import venv" > /dev/null 2>&1 || VENV_AVAILABLE=1\n"${PYTHON_BIN}" -c "import ensurepip" > /dev/null 2>&1 || ENSUREPIP_AVAILABLE=1\n\n# If venv is still not available, try to use virtualenv as a fallback\nif [ $VENV_AVAILABLE -ne 0 ]; then\n  echo "venv module is not available. Checking for virtualenv as an alternative..."\n  \n  # Check if virtualenv is already installed\n  if "$PYTHON_BIN" -c "import virtualenv" > /dev/null 2>&1; then\n    echo "virtualenv is available, will use it instead of venv"\n  else\n    echo "ERROR: Neither venv nor virtualenv is available."\n    echo "Python 3.12 and venv should be installed as package dependencies."\n    echo "Please ensure Python 3.12 and venv are properly installed on your system."\n    exit 1\n  fi\nfi\n\n# Create virtual environment if it doesn\'t exist\nif [ ! -d "$VENV_PATH" ]; then\n  echo "Creating virtual environment at $VENV_PATH..."\n  # Remove any potentially corrupted virtual environment\n  if [ -e "$VENV_PATH" ]; then\n    echo "Removing existing but potentially corrupted venv directory..."\n    rm -rf "$VENV_PATH"\n  fi\n  \n  # Make sure parent directory exists and is writable\n  mkdir -p "$(dirname "$VENV_PATH")"\n  \n  # Try different methods to create a virtual environment\n  VENV_CREATE_STATUS=1\n  \n  # First try with venv if available\n  if [ $VENV_AVAILABLE -eq 0 ] && [ $ENSUREPIP_AVAILABLE -eq 0 ]; then\n    echo "Creating virtual environment using venv module..."\n    "$PYTHON_BIN" -m venv "$VENV_PATH"\n    VENV_CREATE_STATUS=$?\n  fi\n  \n  # If venv failed, try virtualenv\n  if [ $VENV_CREATE_STATUS -ne 0 ]; then\n    echo "venv creation failed with status $VENV_CREATE_STATUS. Falling back to virtualenv..."\n    if command_exists virtualenv; then\n      virtualenv -p "$PYTHON_BIN" "$VENV_PATH"\n      VENV_CREATE_STATUS=$?\n    elif "$PYTHON_BIN" -m pip list | grep -q virtualenv; then\n      "$PYTHON_BIN" -m virtualenv -p "$PYTHON_BIN" "$VENV_PATH"\n      VENV_CREATE_STATUS=$?\n    else\n      echo "ERROR: Both venv and virtualenv are unavailable or failed."\n      echo "Python 3.12 and venv should be installed as package dependencies."\n      echo "Please ensure Python 3.12 and venv are properly installed on your system."\n      echo "You can install Python 3.12 from https://www.python.org/downloads/"\n      exit 1\n    fi\n  fi\n  \n  # Check if virtual environment creation was successful\n  if [ $VENV_CREATE_STATUS -ne 0 ]; then\n    log "ERROR: Failed to create virtual environment. Exit code: $VENV_CREATE_STATUS"\n    log "Virtual environment path: $VENV_PATH"\n    log "Python binary used: $PYTHON_BIN"\n    ls -la "$(dirname "$VENV_PATH")" || true\n    log "Python executable permissions:"\n    ls -la "$PYTHON_BIN" || true\n    \n    # Check for common issues\n    log "Checking for common virtual environment creation issues..."\n    \n    # Check disk space\n    df -h "$(dirname "$VENV_PATH")" || true\n    \n    # Check if directory is writable\n    if [ ! -w "$(dirname "$VENV_PATH")" ]; then\n      log "ERROR: Directory $(dirname "$VENV_PATH") is not writable"\n    fi\n    \n    # Try to create a minimal virtual environment manually as a last resort\n    log "Attempting to create a minimal virtual environment manually..."\n    mkdir -p "$VENV_PATH/bin" || error_exit "Could not create directory $VENV_PATH/bin"\n    echo "#!/bin/bash" > "$VENV_PATH/bin/activate"\n    echo "export VIRTUAL_ENV=\\"$VENV_PATH\\"" >> "$VENV_PATH/bin/activate"\n    echo "export PATH=\\"$VENV_PATH/bin:\\$PATH\\"" >> "$VENV_PATH/bin/activate"\n    echo "unset PYTHONHOME" >> "$VENV_PATH/bin/activate"\n    chmod +x "$VENV_PATH/bin/activate" || error_exit "Could not set execute permissions on activate script"\n    \n    # Create symlinks to the system Python\n    ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python" || log "WARNING: Failed to create symlink for python"\n    ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python3" || log "WARNING: Failed to create symlink for python3"\n    \n    # Try to bootstrap pip\n    log "Bootstrapping pip in the minimal virtual environment..."\n    if command_exists curl; then\n      curl -s https://bootstrap.pypa.io/get-pip.py -o "$APP_DATA_DIR/get-pip.py" || log "WARNING: Failed to download get-pip.py"\n    elif command_exists wget; then\n      wget -q -O "$APP_DATA_DIR/get-pip.py" https://bootstrap.pypa.io/get-pip.py || log "WARNING: Failed to download get-pip.py"\n    else\n      log "ERROR: Neither curl nor wget available to download get-pip.py"\n      error_exit "Installation cannot continue without being able to download pip"\n    fi\n    \n    # shellcheck disable=SC1090\n    source "$VENV_PATH/bin/activate" && python "$APP_DATA_DIR/get-pip.py" --no-warn-script-location\n    \n    if [ ! -f "$VENV_PATH/bin/pip" ]; then\n      error_exit "Failed to create even a minimal virtual environment."\n    else\n      log "Created a minimal virtual environment as a fallback."\n    fi\n  else\n    log "Successfully created virtual environment"\n  fi\nfi\n\n# Verify the virtual environment structure\necho "Verifying virtual environment structure..."\nif [ ! -f "$VENV_PATH/bin/python" ]; then\n  echo "Python executable missing in virtual environment, creating symlink..."\n  ln -sf "$PYTHON_BIN" "$VENV_PATH/bin/python"\nfi\n\nif [ ! -f "$VENV_PATH/bin/pip" ]; then\n  echo "pip missing in virtual environment, attempting to bootstrap it..."\n  curl -s https://bootstrap.pypa.io/get-pip.py -o "$APP_DATA_DIR/get-pip.py"\n  "$VENV_PATH/bin/python" "$APP_DATA_DIR/get-pip.py" --no-warn-script-location\n  \n  if [ ! -f "$VENV_PATH/bin/pip" ]; then\n    echo "ERROR: Failed to bootstrap pip in the virtual environment"\n    exit 1\n  fi\nfi\n\necho "Virtual environment structure verified"\n\n# Activate virtual environment and install local-operator\necho "Installing local-operator in virtual environment..."\nsource "$VENV_PATH/bin/activate"\n\necho "Upgrading pip..."\npython -m pip install --upgrade pip || {\n  echo "WARNING: Failed to upgrade pip. Will try to continue with existing pip version."\n  pip --version\n}\n\n# Check network connectivity to PyPI\necho "Checking network connectivity to PyPI..."\nif command_exists curl; then\n  curl -s https://pypi.org/pypi/local-operator/json -o /dev/null || {\n    echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."\n  }\nelif command_exists wget; then\n  wget -q --spider https://pypi.org/pypi/local-operator/json || {\n    echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."\n  }\nfi\n\necho "Installing local-operator package..."\npython -m pip install --verbose local-operator || {\n  echo "ERROR: Failed to install local-operator package. Exit code: $?"\n  echo "Python version:"\n  python --version\n  echo "pip version:"\n  pip --version\n  echo "Available pip packages:"\n  pip list\n  exit 1\n}\necho "local-operator installation successful"\n\n# Verify installation\nif [ -f "$VENV_PATH/bin/local-operator" ]; then\n  log "Local Operator backend installed successfully!"\n  \n  # Show more information about the installed binary\n  ls -la "$VENV_PATH/bin/local-operator" || true\n  file "$VENV_PATH/bin/local-operator" 2>/dev/null || log "Note: \'file\' command not available"\n  \n  # Try to run the version command with full error output\n  log "Testing local-operator binary..."\n  "$VENV_PATH/bin/local-operator" --version || {\n    log "ERROR: local-operator binary exists but failed to execute. Exit code: $?"\n    log "Binary details:"\n    file "$VENV_PATH/bin/local-operator" 2>/dev/null || log "Note: \'file\' command not available"\n    log "Binary permissions:"\n    ls -la "$VENV_PATH/bin/local-operator" || true\n    log ""\n    log "This could be due to missing dependencies or architecture incompatibility."\n    log "Try running the binary manually to see specific errors."\n    \n    # Don\'t exit here - just warn the user\n    log "WARNING: Installation completed but binary verification failed."\n  }\n  \n  # Create a summary of the installation\n  SUMMARY_FILE="${APP_DATA_DIR}/installation-summary-${TIMESTAMP}.txt"\n  {\n    echo "=== Local Operator Backend Installation Summary ==="\n    echo "Timestamp: $(date)"\n    echo "Python Version: $("${PYTHON_BIN}" --version 2>&1)"\n    echo "Virtual Environment: ${VENV_PATH}"\n    echo "Binary Location: ${VENV_PATH}/bin/local-operator"\n    echo "To activate the virtual environment, run: source ${VENV_PATH}/bin/activate"\n    echo "To test the installation, run: ${VENV_PATH}/bin/local-operator --version"\n    echo "Log file: ${LOG_FILE}"\n    echo "=================================================="\n  } > "${SUMMARY_FILE}"\n  \n  log "Installation summary saved to: ${SUMMARY_FILE}"\nelse\n  log "Error: Failed to install Local Operator backend. Binary not found."\n  log "Contents of bin directory:"\n  ls -la "$VENV_PATH/bin/" || true\n  log "Check the log file for details: ${LOG_FILE}"\n  error_exit "Installation failed. Binary not installed properly."\nfi\n\nlog "Installation completed successfully at $(date)"\n\n# Clean up temporary files now that installation is complete\ncleanup\n\n# Print final instructions\nlog ""\nlog "=== INSTALLATION COMPLETE ==="\nlog "You can now use the Local Operator backend by running: ${VENV_PATH}/bin/local-operator"\nlog "Installation directory: ${VENV_PATH}"\nlog "Log file: ${LOG_FILE}"\nlog "================================"\n';
+const macosInstallScriptRaw = '#!/bin/bash\n# Local Operator Backend Installation Script for macOS\n# This script uses the bundled standalone Python and sets up a virtual environment for the Local Operator backend.\n\nset -e  # Exit immediately if a command exits with a non-zero status\n\n# Configuration\nAPP_NAME="Local Operator"\nVENV_NAME="local-operator-venv"\nAPP_DATA_DIR="${LOCAL_OPERATOR_SUPPORT_PATH:-$HOME/Library/Application Support/$APP_NAME}"\nVENV_PATH="$APP_DATA_DIR/$VENV_NAME"\nLOG_FILE="$APP_DATA_DIR/backend-install.log"\n\n# Which environment this installs into. The path is the app\'s decision, not this\n# script\'s: a packaged install and an unpackaged one must not share an\n# environment (the venv is built on whatever interpreter the instance resolves,\n# and the installed bundle\'s stdlib lives inside the code-sealed .app), and only\n# the app knows which one it is. The app passes its answer in\n# (`LOCAL_OPERATOR_VENV_PATH`, set from `managedVenvPath` in\n# src/main/backend/venv-paths.ts).\n#\n# macOS REFUSES a standalone run rather than falling back, and the asymmetry with\n# the Linux and Windows scripts is deliberate. Their default is the packaged name,\n# which is harmless there; here it is the exact environment this split exists to\n# stop a second instance from writing into - the measured failure is a dev-venv\n# interpreter whose stdlib is `/Applications/Local Operator.app/Contents/\n# Resources/python_aarch64`, so a silent default would rebuild that venv and\n# `pip install` into it, which is what R1 of the review caught. A caller that\n# cannot name the environment is a caller that should not be installing into one.\n: "${LOCAL_OPERATOR_VENV_PATH:?Pass the resolved managed environment path (see venv-paths.ts); this script will not guess which instance it belongs to}"\nVENV_PATH="$LOCAL_OPERATOR_VENV_PATH"\n\n# Keep CPython\'s bytecode cache out of the application bundle.\n#\n# The bundled interpreter writes __pycache__/*.pyc beside the stdlib sources it\n# imports, and those sources live inside the code-signed .app - which is the\n# build\'s own extraResource. Every such write is a change to a sealed resource:\n# measured on an installed 0.17.3, `codesign --verify --deep` reported 308\n# `file added:` violations, all of them .pyc, and ShipIt then refuses the\n# in-place update with -67028 errSecCSBadBundleFormat. A file codesign reports\n# as *added* can be deleted and the seal comes back; a *modified* one cannot,\n# which is why nothing may ship a .pyc at all. The app sets this variable when\n# it spawns us; defaulting it here keeps a standalone run of this script in\n# agreement with the app about where bytecode goes. It is not a complete answer:\n# the app does not spawn every python that runs this interpreter, and a python\n# started by something else - a shell, a CLI script, an agent - has no prefix at\n# all (measured: a venv over this tree wrote 25 .pyc into it that way). The half\n# that covers those is the app\'s seal on the tree itself\n# (src/main/python-bytecode-cache.ts), which a standalone run of this script does\n# not apply. $HOME is the right place for the cache for the same reason the venv\n# lives there: it is never inside the thing that gets signed and swapped.\n: "${PYTHONPYCACHEPREFIX:=$APP_DATA_DIR/python-bytecode-cache}"\nexport PYTHONPYCACHEPREFIX\n\n# And the refusal half of the same pair, so a standalone run of this script\n# cannot write bytecode into the bundle even where the redirect above does not\n# apply - a relative or unwritable prefix, or a child that drops the variable.\n# CPython reads the flag before its first import, so this script\'s own\n# `python -m venv`, its pip runs and the venv they create all compile without\n# writing a `__pycache__` anywhere. Measured on CPython: `0` and the empty\n# string are the two falsy spellings, so the value is set rather than merged\n# with whatever the caller had.\nexport PYTHONDONTWRITEBYTECODE=1\n\n# The architecture block that used to live here computed and logged the name of\n# a directory for an in-bundle search this script no longer performs: every run\n# announced which architecture-named directory it was about to use, and then\n# installed from `PYTHON_BIN` anyway - the line stated the opposite of how the\n# script finds Python, and the names it computed were used nowhere else (review\n# N1). Which interpreter to build the environment with is the caller\'s decision,\n# checked immediately below.\n\n# The app prepares a complete external runtime before invoking this script.\n# Searching /Applications here would reintroduce legacy-bundle execution during\n# migration. Standalone callers must make the same explicit path decision.\n: "${PYTHON_BIN:?Pass an external prepared Python executable}"\ncase "$PYTHON_BIN" in\n  *.app/*) echo "Refusing to execute Python inside an application bundle" >&2; exit 1 ;;\nesac\n\n# Create app data directory if it doesn\'t exist\nmkdir -p "$APP_DATA_DIR"\n\n# Start logging - capture everything and ensure it\'s visible to parent process\nexec > >(tee -a "$LOG_FILE") 2> >(tee -a "$LOG_FILE" >&2)\necho "=============================================="\necho "$(date): Starting Local Operator backend installation..."\necho "=============================================="\necho "Python bin path: $PYTHON_BIN"\necho "Virtual environment path: $VENV_PATH"\necho "App data directory: $APP_DATA_DIR"\necho "Log file: $LOG_FILE"\necho "=============================================="\n\n# --- FFmpeg Installation ---\nBIN_DIR="$APP_DATA_DIR/bin"\nFFMPEG_BIN="$BIN_DIR/ffmpeg"\n\necho "Ensuring bin directory exists: $BIN_DIR"\nmkdir -p "$BIN_DIR"\n\n# Check if FFmpeg is already installed and executable\nif [ -f "$FFMPEG_BIN" ] && [ -x "$FFMPEG_BIN" ]; then\n    echo "FFmpeg already installed at $FFMPEG_BIN. Skipping download."\nelse\n    echo "FFmpeg not found or not executable. Attempting to download and install FFmpeg..."\n\n    # The architecture, read here because this URL is the one place left that needs\n    # it: the environment is built on `PYTHON_BIN`, handed in above, so nothing\n    # else in this script derives anything from `uname -m`. The block that used to\n    # compute it at the top of the file was removed with the in-bundle interpreter\n    # search it existed for (review N1) - and that removal took this variable with\n    # it while this block still read it, so `$ARCH` was empty for every caller,\n    # including the app, and any install on a machine without a cached ffmpeg\n    # exited 1 here, before the venv was ever created. Measured: `bash\n    # src/main/backend/scripts/macos-install-script.sh` with `PYTHON_BIN` set stops\n    # on "Unsupported CPU architecture for FFmpeg download:".\n    ARCH=$(uname -m)\n\n    FFMPEG_DOWNLOAD_URL=""\n\n    if [[ "$ARCH" == "x86_64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-mac-x64"\n    elif [[ "$ARCH" == "arm64" ]] || [[ "$ARCH" == "aarch64" ]]; then\n        FFMPEG_DOWNLOAD_URL="https://github.com/eugeneware/ffmpeg-static/releases/download/b6.0/ffmpeg-mac-arm64"\n    else\n        echo "Error: Unsupported CPU architecture for FFmpeg download: $ARCH"\n        exit 1\n    fi\n\n    echo "Downloading FFmpeg from: $FFMPEG_DOWNLOAD_URL"\n    if curl -L "$FFMPEG_DOWNLOAD_URL" -o "$FFMPEG_BIN"; then\n        echo "FFmpeg downloaded successfully to $FFMPEG_BIN"\n        chmod +x "$FFMPEG_BIN"\n        echo "Set executable permissions for $FFMPEG_BIN"\n    else\n        echo "Error: Failed to download FFmpeg from $FFMPEG_DOWNLOAD_URL"\n        exit 1\n    fi\n\n    # Verify FFmpeg is executable after download\n    if [ ! -f "$FFMPEG_BIN" ] || [ ! -x "$FFMPEG_BIN" ]; then\n        echo "Error: FFmpeg binary not found or not executable after download."\n        exit 1\n    fi\nfi\n\necho "FFmpeg installation complete. FFmpeg binary is at: $FFMPEG_BIN"\n# --- End FFmpeg Installation ---\n\n# Verify bundled Python exists\nif [ ! -f "$PYTHON_BIN" ]; then\n  echo "Error: Bundled Python not found at $PYTHON_BIN"\n  echo "Please ensure standalone Python is properly installed in the application resources."\n  exit 1\nfi\n\n# Make sure Python binary is executable\necho "Using bundled Python: $PYTHON_BIN"\n"$PYTHON_BIN" --version\n\n# Check if Python has venv module available\necho "Checking for venv module availability..."\n"$PYTHON_BIN" -m venv --help > /dev/null 2>&1 || {\n  echo "ERROR: Python venv module not available in the Python installation"\n  echo "Python details:"\n  "$PYTHON_BIN" --version\n  "$PYTHON_BIN" -c "import sys; print(\'Prefix:\', sys.prefix); print(\'Exec Prefix:\', sys.exec_prefix)"\n  "$PYTHON_BIN" -c "import sys; print(\'Modules path:\'); print(\'\\n\'.join(sys.path))"\n  exit 1\n}\necho "venv module is available"\n\n# Create virtual environment if it doesn\'t exist\nif [ ! -d "$VENV_PATH" ]; then\n  echo "Creating virtual environment at $VENV_PATH..."\n  # Never repair a path we did not create. Preparation allocates a fresh final\n  # pathname; a collision is evidence to preserve, not a reason to delete it.\n  if [ -e "$VENV_PATH" ] || [ -L "$VENV_PATH" ]; then\n    echo "Refusing to replace an existing environment path: $VENV_PATH" >&2\n    exit 1\n  fi\n  \n  # Make sure parent directory exists and is writable\n  mkdir -p "$(dirname "$VENV_PATH")"\n  \n  # Create the virtual environment with verbosity\n  "$PYTHON_BIN" -m venv "$VENV_PATH" || {\n    echo "ERROR: Failed to create virtual environment. Exit code: $?"\n    echo "Virtual environment path: $VENV_PATH"\n    echo "Python binary used: $PYTHON_BIN"\n    ls -la "$(dirname "$VENV_PATH")"\n    echo "Python executable permissions:"\n    ls -la "$PYTHON_BIN"\n    exit 1\n  }\n  echo "Successfully created virtual environment"\nfi\n\n# Verify the virtual environment structure\necho "Verifying virtual environment structure..."\nif [ ! -f "$VENV_PATH/bin/python" ] || [ ! -f "$VENV_PATH/bin/pip" ]; then\n  echo "ERROR: Virtual environment is missing critical components"\n  echo "Contents of virtual environment directory:"\n  ls -la "$VENV_PATH"\n  if [ -d "$VENV_PATH/bin" ]; then\n    echo "Contents of bin directory:"\n    ls -la "$VENV_PATH/bin"\n  fi\n  exit 1\nfi\necho "Virtual environment structure verified"\n\n# Activate virtual environment and install local-operator\necho "Installing local-operator in virtual environment..."\nsource "$VENV_PATH/bin/activate"\n\necho "Upgrading pip..."\npython -m pip install --upgrade pip || {\n  echo "ERROR: Failed to upgrade pip. Exit code: $?"\n  echo "pip version before failing:"\n  pip --version\n  exit 1\n}\necho "pip upgrade successful:"\npip --version\n\n# Check network connectivity to PyPI\necho "Checking network connectivity to PyPI..."\ncurl -s https://pypi.org/pypi/local-operator/json -o /dev/null || {\n  echo "WARNING: Could not reach PyPI. Network connectivity issues might prevent installation."\n  echo "Attempting to ping common domains to diagnose network issues:"\n  ping -c 1 google.com || echo "Cannot ping google.com"\n  ping -c 1 pypi.org || echo "Cannot ping pypi.org"\n}\n\necho "Installing local-operator package..."\npython -m pip install --upgrade --verbose local-operator || {\n  echo "ERROR: Failed to install local-operator package. Exit code: $?"\n  echo "Python version:"\n  python --version\n  echo "pip version:"\n  pip --version\n  echo "Available pip packages:"\n  pip list\n  echo "Pip config:"\n  pip config list\n  echo "Network diagnosis:"\n  curl -I https://pypi.org || echo "Cannot reach PyPI server"\n  exit 1\n}\necho "local-operator installation successful"\n\n# Verify installation\nif [ -f "$VENV_PATH/bin/local-operator" ]; then\n  echo "Local Operator backend installed successfully!"\n  \n  # Show more information about the installed binary\n  ls -la "$VENV_PATH/bin/local-operator"\n  file "$VENV_PATH/bin/local-operator"\n  \n  # Try to run the version command with full error output\n  echo "Testing local-operator binary..."\n  "$VENV_PATH/bin/local-operator" --version || {\n    echo "ERROR: local-operator binary exists but failed to execute. Exit code: $?"\n    echo "Binary details:"\n    file "$VENV_PATH/bin/local-operator"\n    echo "Binary permissions:"\n    ls -la "$VENV_PATH/bin/local-operator"\n    echo "Dependencies:"\n    if command -v otool >/dev/null; then\n      otool -L "$VENV_PATH/bin/local-operator" || echo "Could not get dependencies with otool"\n    fi\n    exit 1\n  }\nelse\n  echo "Error: Failed to install Local Operator backend. Binary not found."\n  echo "Contents of bin directory:"\n  ls -la "$VENV_PATH/bin/"\n  exit 1\nfi\n\necho "$(date): Installation completed successfully."\n';
 const windowsInstallScriptRaw = `# Local Operator Backend Installation Script for Windows
 # This script installs pyenv-win, Python 3.12, and sets up a virtual environment for the Local Operator backend.
 
@@ -3412,6 +4335,17 @@ $VenvPath = "$AppDataDir\\\\$VenvName"
 $LogFile = "$AppDataDir\\\\backend-install-shell.log"
 $PyenvDir = "$env:USERPROFILE\\\\.pyenv"
 
+# Which environment this installs into - the app's decision, handed in rather
+# than re-derived. A packaged install and an unpackaged one must not share an
+# environment (the venv is built on whatever interpreter the instance resolves),
+# and only the app knows which it is: LOCAL_OPERATOR_VENV_PATH carries
+# managedVenvPath's answer (src/main/backend/venv-paths.ts). The default above is
+# what a standalone run uses - the packaged name, because that is what every
+# install on a disk today has.
+if ($env:LOCAL_OPERATOR_VENV_PATH) {
+    $VenvPath = $env:LOCAL_OPERATOR_VENV_PATH
+}
+
 # Keep CPython's bytecode cache out of the application directory.
 #
 # Same rule as the macOS script, and stated here for the same reason: an
@@ -3425,6 +4359,11 @@ if (-not $env:PYTHONPYCACHEPREFIX) {
     $env:PYTHONPYCACHEPREFIX = "$AppDataDir\\\\python-bytecode-cache"
 }
 
+# The refusal half of the same pair, kept in step with the app's
+# \`withPythonBytecodeCache\`: CPython reads the flag before its first import, so
+# nothing this script runs can write a __pycache__ at all.
+$env:PYTHONDONTWRITEBYTECODE = "1"
+
 # Create app data directory if it doesn't exist
 if (-not (Test-Path $AppDataDir)) {
     New-Item -ItemType Directory -Path $AppDataDir -Force | Out-Null
@@ -3717,45 +4656,60 @@ try {
 const macosInstallScript = macosInstallScriptRaw;
 const linuxInstallScript = linuxInstallScriptRaw;
 const windowsInstallScript = windowsInstallScriptRaw;
+const SETUP_FAILURE_CAUSES = [
+  [
+    /ENOSPC|No space left|not enough (?:free )?space/i,
+    "This Mac ran out of disk space while setting up the backend. Free some space and retry."
+  ],
+  [
+    /Another Local Operator instance is preparing/i,
+    "Another copy of Local Operator is setting up its backend right now. Retry in a moment."
+  ],
+  [
+    /*
+     * The smoke arm only. `did not complete` used to be in here, and it is the
+     * phrase `prepareManagedPython` throws when the install callback returns
+     * false - a pip or network failure, where nothing was installed at all - so
+     * the user read "The backend was installed but did not start correctly" about
+     * an install that never happened (review round 2, N6). It now falls through
+     * to the generic cause, which is true of it, and the app's own sentence still
+     * follows under `The app recorded:`.
+     */
+    /did not become healthy|Backend smoke|exited with/i,
+    "The backend was installed but did not start correctly."
+  ],
+  [
+    /ENOENT|no such file or directory|could not find|did not match its signed seed/i,
+    "A file the setup needed was missing, which usually means the download or the copy did not finish."
+  ]
+];
+function backendSetupFailureDetail(error, support) {
+  const raw = error instanceof Error ? error.message : String(error);
+  const cause = SETUP_FAILURE_CAUSES.find(([pattern]) => pattern.test(raw))?.[1] ?? "The backend could not be set up on this Mac.";
+  return [
+    `What happened: ${cause}`,
+    `The app recorded: ${raw}`,
+    `Where its environment lives: ${support}/managed-python`
+  ].join("\n\n");
+}
 class BackendInstaller {
   appDataPath = electron.app.getPath("userData");
   venvPath;
   resourcesPath;
   pythonPath = null;
+  preparationWindow = null;
   /**
    * Constructor
    */
   constructor() {
-    if (process.platform === "win32") {
-      this.venvPath = path$1.join(this.appDataPath, "local-operator-venv");
-    } else if (process.platform === "darwin") {
-      this.venvPath = path$1.join(
-        electron.app.getPath("home"),
-        "Library",
-        "Application Support",
-        "Local Operator",
-        "local-operator-venv"
-      );
-    } else {
-      this.venvPath = path$1.join(
-        electron.app.getPath("home"),
-        ".config",
-        "local-operator",
-        "local-operator-venv"
-      );
-    }
-    this.resourcesPath = process.env.NODE_ENV === "development" ? path$1.join(process.cwd(), "resources") : path$1.join(process.resourcesPath);
-    if (electron.app.isPackaged) {
-      const seal = sealPythonInterpreterTrees(
-        bundledPythonTreePaths(process.resourcesPath)
-      );
-      const message = describePythonTreeSeal(seal);
-      if (seal.supported && seal.failures.length > 0) {
-        logger.warn(message, LogFileType.INSTALLER);
-      } else {
-        logger.info(message, LogFileType.INSTALLER);
-      }
-    }
+    this.venvPath = managedVenvPath({
+      platform: process.platform,
+      home: electron.app.getPath("home"),
+      appDataPath: this.appDataPath,
+      packaged: electron.app.isPackaged
+    });
+    this.resourcesPath = !electron.app.isPackaged ? path$1.join(process.cwd(), "resources") : path$1.join(process.resourcesPath);
+    if (process.platform !== "darwin") this.guardVenvBytecode();
     this.pythonPath = this.findPython();
     logger.info(
       `Backend Installer initialized. Virtual environment path: ${this.venvPath}`,
@@ -3772,6 +4726,7 @@ class BackendInstaller {
    * @returns Path to Python executable or null if not found
    */
   findPython() {
+    if (process.platform === "darwin") return null;
     const possibilities = [];
     if (process.arch === "arm64") {
       possibilities.push(
@@ -3814,12 +4769,31 @@ class BackendInstaller {
     );
     return null;
   }
+  /**
+   * Make the app-managed venv refuse bytecode writes for every process that
+   * uses it, whoever started it.
+   *
+   * Logged rather than silent in both directions: a guard that was already
+   * there, one this call wrote, and one that could not be written (no venv yet,
+   * or a `sitecustomize.py` the operator owns) are three different states of the
+   * same guarantee, and the field diagnosis starts from which one this machine
+   * is in. `ensureVenvBytecodeGuard` never replaces a file it did not write.
+   */
+  guardVenvBytecode() {
+    const guard = ensureVenvBytecodeGuard(this.venvPath);
+    logger.info(
+      `Bytecode guard in the app-managed venv: ${guard.reason}`,
+      LogFileType.INSTALLER
+    );
+  }
   /**
    * Check if backend is installed
    * @returns Promise resolving to true if the backend is installed, false otherwise
    */
   async isInstalled() {
     try {
+      if (process.platform === "darwin")
+        return await managedSelectionReady(this.managedOptions());
       if (!fs.existsSync(this.venvPath)) {
         logger.info(
           `Virtual environment not found at ${this.venvPath}`,
@@ -3866,30 +4840,90 @@ class BackendInstaller {
    * Install backend
    * @returns Promise resolving to true if the backend was installed successfully, false otherwise
    */
+  managedOptions() {
+    return {
+      support: path$1.join(
+        electron.app.getPath("home"),
+        "Library",
+        "Application Support",
+        "Local Operator"
+      ),
+      resources: this.resourcesPath,
+      packaged: electron.app.isPackaged,
+      arch: process.arch
+    };
+  }
   async install() {
-    try {
-      const { response } = await electron.dialog.showMessageBox({
-        type: "info",
-        title: "First-Time Setup Required",
-        message: "Local Operator needs to set up some components to work properly. This one-time process will take just a few moments.",
-        buttons: ["Set Up Now", "Cancel"],
-        defaultId: 0,
-        cancelId: 1
-      });
-      if (response === 1) {
-        logger.info(
-          "User cancelled backend installation",
-          LogFileType.INSTALLER
+    if (process.platform !== "darwin") return this.installEnvironment();
+    for (; ; ) {
+      try {
+        const state = inspectManagedSelection(this.managedOptions());
+        if (state.kind === "missing")
+          logger.warn(
+            `Published backend environment is not usable and will be rebuilt: ${state.detail}`,
+            LogFileType.INSTALLER
+          );
+        await prepareManagedPython(
+          this.managedOptions(),
+          async (venv, python) => {
+            this.venvPath = venv;
+            this.pythonPath = python;
+            return this.installEnvironment();
+          }
         );
-        setTimeout(() => {
-          electron.app.exit(0);
-        }, 500);
-        return false;
+        return true;
+      } catch (error) {
+        logger.error(
+          "Backend preparation failed",
+          LogFileType.INSTALLER,
+          error
+        );
+        const { response } = await electron.dialog.showMessageBox({
+          type: "error",
+          title: "Backend setup could not finish",
+          message: "Your existing environment and data were preserved. Retry setup to start this version of Local Operator.",
+          detail: backendSetupFailureDetail(
+            error,
+            this.managedOptions().support
+          ),
+          buttons: ["Retry setup", "Quit"],
+          defaultId: 0,
+          cancelId: 1
+        });
+        if (response !== 0) return false;
+      } finally {
+        if (this.preparationWindow && !this.preparationWindow.isDestroyed())
+          this.preparationWindow.close();
+        this.preparationWindow = null;
+      }
+    }
+  }
+  async installEnvironment() {
+    try {
+      if (process.platform !== "darwin") {
+        const { response } = await electron.dialog.showMessageBox({
+          type: "info",
+          title: "First-Time Setup Required",
+          message: "Local Operator needs to set up some components to work properly. This one-time process will take just a few moments.",
+          buttons: ["Set Up Now", "Cancel"],
+          defaultId: 0,
+          cancelId: 1
+        });
+        if (response === 1) {
+          logger.info(
+            "User cancelled backend installation",
+            LogFileType.INSTALLER
+          );
+          setTimeout(() => {
+            electron.app.exit(0);
+          }, 500);
+          return false;
+        }
       }
       let scriptPath;
       let cmd;
       let args;
-      const tempDir = os.tmpdir();
+      const tempDir = fs.mkdtempSync(path$1.join(os.tmpdir(), "local-operator-install-"));
       if (process.platform === "win32") {
         scriptPath = path$1.join(tempDir, "install-backend-windows.ps1");
         fs.writeFileSync(scriptPath, windowsInstallScript);
@@ -3934,6 +4968,8 @@ class BackendInstaller {
           sandbox: false
         }
       });
+      if (process.platform === "darwin")
+        this.preparationWindow = progressWindow;
       if (utils.is.dev && process.env.ELECTRON_RENDERER_URL) {
         progressWindow.loadURL(
           `${process.env.ELECTRON_RENDERER_URL}/installer`
@@ -4008,6 +5044,13 @@ class BackendInstaller {
         try {
           const env = withPythonBytecodeCache({ ...process.env }, this.appDataPath);
           env.ELECTRON_RESOURCE_PATH = this.resourcesPath;
+          env[VENV_PATH_ENV] = this.venvPath;
+          env.HOME = electron.app.getPath("home");
+          env.LOCAL_OPERATOR_SUPPORT_PATH = process.platform === "darwin" ? this.managedOptions().support : this.appDataPath;
+          logger.info(
+            `Setting ${VENV_PATH_ENV} to ${this.venvPath}`,
+            LogFileType.INSTALLER
+          );
           logger.info(
             `Setting ELECTRON_RESOURCE_PATH to ${this.resourcesPath}`,
             LogFileType.INSTALLER
@@ -4087,7 +5130,7 @@ class BackendInstaller {
       });
       ipcMain.removeListener("cancel-installation", cancelHandler);
       electron.app.removeListener("before-quit", appQuitHandler);
-      if (!progressWindow.isDestroyed()) {
+      if (process.platform !== "darwin" && !progressWindow.isDestroyed()) {
         progressWindow.close();
       }
       if (installationCancelled) {
@@ -4103,6 +5146,7 @@ class BackendInstaller {
           "Backend installation completed successfully",
           LogFileType.INSTALLER
         );
+        this.guardVenvBytecode();
         const localOperatorPath = process.platform === "win32" ? path$1.join(this.venvPath, "Scripts", "local-operator.exe") : path$1.join(this.venvPath, "bin", "local-operator");
         if (!fs.existsSync(localOperatorPath)) {
           logger.error(
@@ -4117,23 +5161,25 @@ class BackendInstaller {
           "Installation verified successfully",
           LogFileType.INSTALLER
         );
-        const { response: successResponse } = await electron.dialog.showMessageBox({
-          type: "info",
-          title: "Setup Complete",
-          message: "Local Operator is ready to use. Everything has been set up successfully.",
-          buttons: ["Let's Go!", "Cancel"],
-          defaultId: 0,
-          cancelId: 1
-        });
-        if (successResponse === 1) {
-          logger.info(
-            "User ended session after successful installation",
-            LogFileType.INSTALLER
-          );
-          setTimeout(() => {
-            electron.app.exit(0);
-          }, 500);
-          return false;
+        if (process.platform !== "darwin") {
+          const { response: successResponse } = await electron.dialog.showMessageBox({
+            type: "info",
+            title: "Setup Complete",
+            message: "Local Operator is ready to use. Everything has been set up successfully.",
+            buttons: ["Let's Go!", "Cancel"],
+            defaultId: 0,
+            cancelId: 1
+          });
+          if (successResponse === 1) {
+            logger.info(
+              "User ended session after successful installation",
+              LogFileType.INSTALLER
+            );
+            setTimeout(() => {
+              electron.app.exit(0);
+            }, 500);
+            return false;
+          }
         }
         await new Promise((resolve) => setTimeout(resolve, 500));
         if (process.platform === "win32") {
@@ -7929,7 +8975,7 @@ function relayedBytes(value) {
   if (!(buffer instanceof ArrayBuffer)) return null;
   return new Uint8Array(buffer, byteOffset, byteLength);
 }
-function registerDesktopIPC(window, expectedUrl, request, streams, media, notifier) {
+function registerDesktopIPC(window, expectedUrl, request, streams, media, notifier, noteLeftSession) {
   const opened = /* @__PURE__ */ new Map();
   function authorize(event) {
     const owner = window();
@@ -7964,6 +9010,15 @@ function registerDesktopIPC(window, expectedUrl, request, streams, media, notifi
         focused: args.focused
       });
     });
+    electron.ipcMain.handle("desktop-watch-release", (event, input) => {
+      authorize(event);
+      const args = input;
+      if (typeof args?.sessionId !== "string") {
+        throw new Error("Invalid watch release.");
+      }
+      notifier.releaseWatch(event.sender.id, args.sessionId);
+      noteLeftSession?.(args.sessionId);
+    });
   }
   if (media) {
     electron.ipcMain.handle("desktop-media", (event, input, bytes) => {
@@ -8064,11 +9119,26 @@ function gateBody(kind, gateTitle, gateDetail) {
   }
   return subject || GATE_BODIES[kind] || GATE_BODIES.approval;
 }
+function isBurstDigest(n) {
+  return (n.burst_count ?? 0) > 1 || (n.session_ids?.length ?? 0) > 1;
+}
+function digestMemberCount(n) {
+  return (n.member_tokens ?? []).filter(
+    (member) => !!member?.session_id && !!member?.completion_token
+  ).length;
+}
+const SILENT_HOST = {
+  windowAlive: () => true,
+  noteDisplayed: () => void 0,
+  reopen: () => void 0
+};
+const RENDERER_REPORT_TTL_MS = 45e3;
 class DesktopNotifier {
-  constructor(window, request, windowRaise = "focus") {
+  constructor(window, request, windowRaise = "focus", host = SILENT_HOST) {
     this.window = window;
     this.request = request;
     this.windowRaise = windowRaise;
+    this.host = host;
   }
   delivered = /* @__PURE__ */ new Map();
   /** Last known frontend epoch per session, to key dedupe on owner epoch. */
@@ -8237,12 +9307,24 @@ class DesktopNotifier {
    * renderer's active subscription; `can_notify` is asserted only when main
    * can really deliver. A focused window is interactive; a visible-but-
    * unfocused one still watches but is not; a hidden one is neither.
+   *
+   * ``windowId`` IS THE WEB CONTENTS ID (``event.sender.id``, from the IPC
+   * handler), and the map is keyed on it because that is what a close cleanup can
+   * still name after the window is gone. Every reader must use the SAME id — see
+   * `presence()`, where reading the ``BrowserWindow`` id instead made the
+   * machine-wide presence report an empty session id for a window it was
+   * claiming was focused on a conversation (review round 2, R2-3).
    */
   async heartbeat(windowId, args) {
     this.windows.set(windowId, {
       visible: args.visible,
-      focused: args.focused
+      focused: args.focused,
+      session: args.sessionId,
+      // THE REPORT'S AGE, part of the record rather than a separate map
+      // (R2-4): a state that cannot expire is a state that outlives its pane.
+      seenAt: Date.now()
     });
+    this.host.noteDisplayed(args.sessionId);
     return this.request({
       op: "sessions.watch",
       sessionId: args.sessionId,
@@ -8251,10 +9333,52 @@ class DesktopNotifier {
       canNotify: this.canNotify
     });
   }
+  /**
+   * Forget a window's watch state on close.
+   *
+   * This had NO CALLER while `mainWindow.on("closed")` nulled the window
+   * without telling the notifier, and `webContents` ids are not reused — so
+   * after one window close the map held `{visible: true, focused: true}` for
+   * the life of the process and every `when_unfocused` completion was
+   * suppressed for good. That is the strongest candidate for the operator's
+   * "I don't reliably get notified", and the fix is this call plus the
+   * liveness read in `anyDisplayingFocused`.
+   */
   forgetWindow(windowId) {
     this.windows.delete(windowId);
   }
-  /** Called by the stream relay for every parsed frame it forwards. */
+  /**
+   * Withdraw the DISPLAYED conversation when the pane that reported it leaves.
+   *
+   * THE NAVIGATION HALF OF R2-4. `forgetWindow` runs when a window closes, and
+   * the report now expires on its own after `RENDERER_REPORT_TTL_MS` — but
+   * navigating from a conversation to the catalogue or Settings stops the watch
+   * and unsubscribes its stream while leaving the window, and therefore the map
+   * entry, exactly where it was. Main's own feed then kept renewing "showing A"
+   * every beat and the backend, which treats fresh presence as authoritative,
+   * suppressed A's banner while no pane displayed it.
+   *
+   * IDENTITY-SAFE BY CONSTRUCTION, which is the part a naive clear gets wrong: a
+   * cleanup runs asynchronously after the pane has already changed, so an
+   * unconditional clear would wipe the session a DEEPER pane has since
+   * subscribed to. This withdraws only the report that names the conversation
+   * being left.
+   */
+  releaseWatch(windowId, sessionId2) {
+    const state = this.windows.get(windowId);
+    if (!state) return;
+    if (!sessionId2 || state.session !== sessionId2) return;
+    this.windows.set(windowId, { ...state, session: "" });
+  }
+  /**
+   * Called by the stream relay for every parsed frame it forwards, and by the
+   * machine-wide feed for the frames it carries.
+   *
+   * ONE method for both sources on purpose. A `notification` frame's payload is
+   * byte-identical whichever way it arrived — same `dedupe_key`, minted by the
+   * backend — so two entry points would be two places to keep that true, and
+   * the pair would eventually be delivered twice instead of once.
+   */
   observe(sessionId2, frame) {
     if (!this.canNotify) return;
     if (this.windowRaise === "never") return;
@@ -8315,16 +9439,47 @@ class DesktopNotifier {
    */
   async composed(sessionId2, n) {
     if (!this.claim(n.dedupe_key)) return;
-    if (n.focus_policy === "when_unfocused" && this.anyFocused()) return;
+    if (n.focus_policy === "when_unfocused" && this.anyDisplayingFocused(sessionId2))
+      return;
     if (n.completion_token) {
       const outcome = await this.claimDelivery(sessionId2, n.completion_token);
       if (outcome !== "won") {
         if (outcome === "failed") this.delivered.delete(n.dedupe_key);
         return;
       }
+    } else if (digestMemberCount(n) > 0 || isBurstDigest(n)) {
+      const won = await this.claimDigestMembers(n);
+      if (won === 0 && digestMemberCount(n) > 0) {
+        this.delivered.delete(n.dedupe_key);
+        return;
+      }
     }
     this.show(
-      sessionId2,
+      /*
+       * A BURST DIGEST is not about one conversation (R1-2). The backend
+       * caps per-tick banners and publishes ONE frame for the remainder,
+       * carrying `burst_count` and `session_ids` and setting `session_id`
+       * to the LAST overflow member — it must name something for the frame
+       * to be a valid session frame at all. Routing its click to that id
+       * opened one arbitrary member of the burst, which is the "the click
+       * did not land where I expected" defect this change exists to
+       * remove, so a digest opens the catalogue instead.
+       *
+       * Detected on the fields themselves rather than on a title string:
+       * the strings are the backend's to word, and a surface that matched
+       * on them would route a re-worded digest to a random conversation.
+       *
+       * A ONE-MEMBER DIGEST LANDS ON ITS OWN CONVERSATION, and that is a
+       * decision rather than a fall-through (review round 3, R3-1). The frame
+       * above is the case the claim branch now recognises and this one does
+       * not: `burst_count` is 1 and it names exactly one conversation, so the
+       * banner says one thing and the click goes there — the operator's own
+       * request ("a click landing on the exact conversation") read literally.
+       * Folding the member marker into `isBurstDigest` would send it to the
+       * catalogue and lose that navigation for no gain in correctness, since
+       * it is the CLAIM that has to happen for every member, not the routing.
+       */
+      isBurstDigest(n) ? null : sessionId2,
       n.title,
       n.status,
       n.body,
@@ -8332,6 +9487,36 @@ class DesktopNotifier {
       n.body_is_failure ?? false
     );
   }
+  /**
+   * Claim a burst digest's members, and report how many this surface won.
+   *
+   * One `sessions.notified` per member, through the SAME atomic claim a single
+   * frame uses — that is the point of the contract: the arbitration lives in one
+   * place (the backend's `claim_delivery`), so a digest and an individual banner
+   * for one of its members cannot both win.
+   *
+   * Members are claimed SEQUENTIALLY rather than in parallel, deliberately: this
+   * runs on the delivery path with a banner's worth of latency behind it, and a
+   * burst is capped at a handful of members by the backend's own ceiling.
+   *
+   * A `failed` claim is treated as NOT won, which makes the whole digest fail
+   * closed when the backend is unreachable — the same choice the single-frame
+   * path makes, and for the same reason: showing the banner anyway would risk a
+   * second banner for completions another surface may also have reached.
+   */
+  async claimDigestMembers(n) {
+    const members = n.member_tokens ?? [];
+    let won = 0;
+    for (const member of members) {
+      if (!member?.session_id || !member?.completion_token) continue;
+      const outcome = await this.claimDelivery(
+        member.session_id,
+        member.completion_token
+      );
+      if (outcome === "won") won += 1;
+    }
+    return won;
+  }
   /**
    * Ask the backend whether this surface owns this completion's toast.
    *
@@ -8359,12 +9544,91 @@ class DesktopNotifier {
       return "failed";
     }
   }
-  anyFocused() {
-    for (const state of this.windows.values()) {
-      if (state.visible && state.focused) return true;
+  /**
+   * Whether a LIVE window is displaying `sessionId` in the foreground.
+   *
+   * THE completion gate, and the predicate is deliberately two facts rather
+   * than one. `anyFocused()` alone answers "is the app in front", which is not
+   * the question: with the app focused on session A, a completion in session B
+   * was suppressed and announced to nobody — and rung 3 had already deferred
+   * to rung 2, so nothing else could raise it either. That is the operator's
+   * reported symptom, made permanent by the presence mechanism itself (B1).
+   *
+   * Only a window showing THIS conversation is a reason not to banner, because
+   * only then is the completion already on screen.
+   *
+   * Dead windows are filtered rather than assumed gone. `forgetWindow` runs on
+   * `closed`, but a renderer process that dies takes its `webContents` id with
+   * it and no `closed` event reaches this map, and `webContents` ids are not
+   * reused — so an unfiltered stale `{visible: true, focused: true}` entry
+   * suppresses every completion for the life of the process.
+   */
+  anyDisplayingFocused(sessionId2) {
+    for (const [id2, state] of this.windows) {
+      if (!state.visible || !state.focused) continue;
+      if (state.session !== sessionId2) continue;
+      if (!this.host.windowAlive(id2)) continue;
+      if (Date.now() - state.seenAt > RENDERER_REPORT_TTL_MS) continue;
+      return true;
     }
     return false;
   }
+  /**
+   * What this app can say about itself for the machine-wide presence claim.
+   *
+   * The claim is not "a desktop is connected" - the backend already knows that
+   * from the socket. It is the two answers only the app has, and both are
+   * read by the delivery ladder: `session_id` + `window` decide `attended`
+   * (rung 1's "a watching surface already has it"), and a MISSING window is not
+   * a missing value - it means this app is watching nothing, which is the
+   * correct answer for the operator's own windowless case and the wrong answer
+   * for a window that is merely minimised.
+   *
+   * `sessionId` comes from this notifier's own heartbeat map rather than from
+   * the renderer, so it cannot disagree with the completion gate above: the
+   * same value that suppresses a banner is the value that tells the backend
+   * not to raise someone else's. An app that names a conversation it is not
+   * showing suppresses the banner for a conversation nobody can see.
+   *
+   * Dead windows answer "no window" rather than "last known window": a
+   * destroyed window has no `is*()` to read, and reporting its stale state
+   * would advertise a surface that cannot display anything.
+   *
+   * THE SESSION IS READ BY THE ID THE WRITER USED (review round 2, R2-3).
+   * `heartbeat` keys this map on `event.sender.id` — the WEB CONTENTS id —
+   * because that is what the IPC event carries and what the close cleanup
+   * captures. This accessor read `window.id`, the BrowserWindow id, which merely
+   * happens to be equal early in a session and drifts as soon as anything else
+   * is created (the browser host's own webContents, a second window). It then
+   * reported a focused, visible window with `session_id: ""`, so the backend
+   * could not recognise the conversation actually on screen and bannered it as
+   * background.
+   */
+  presence() {
+    const window = this.window();
+    if (!window || window.isDestroyed()) {
+      return {
+        sessionId: "",
+        window: {
+          exists: false,
+          focused: false,
+          visible: false,
+          minimized: false
+        }
+      };
+    }
+    const reported = this.windows.get(window.webContents.id);
+    const current = reported && Date.now() - reported.seenAt <= RENDERER_REPORT_TTL_MS;
+    return {
+      sessionId: current ? reported.session : "",
+      window: {
+        exists: true,
+        focused: window.isFocused(),
+        visible: window.isVisible(),
+        minimized: window.isMinimized()
+      }
+    };
+  }
   /**
    * Raise the banner for a pending approval or question.
    *
@@ -8416,7 +9680,7 @@ class DesktopNotifier {
   turn(sessionId2, seq) {
     const key = `turn:${sessionId2}:${this.epochs.get(sessionId2) ?? ""}:${seq}`;
     if (!this.claim(key)) return;
-    if (this.anyFocused()) return;
+    if (this.anyDisplayingFocused(sessionId2)) return;
     this.show(sessionId2, "Turn complete", "", "The agent finished its turn.");
   }
   claim(key) {
@@ -8480,9 +9744,12 @@ class DesktopNotifier {
     });
     notification.on("click", () => {
       const target2 = this.window();
-      if (!target2) return;
-      raiseWindow(target2, this.windowRaise);
+      if (!target2 || target2.isDestroyed()) {
+        this.host.reopen(sessionId2);
+        return;
+      }
       target2.webContents.send("desktop-open-conversation", { sessionId: sessionId2 });
+      raiseWindow(target2, this.windowRaise);
     });
     notification.show();
   }
@@ -8553,15 +9820,20 @@ ${probe.stderr}`.trim();
     detail: marker ? `${marker}: ${output || "no output"}` : `codesign --verify exited ${probe.exitCode}: ${output || "no output"}`
   };
 }
-function installedBundleSealBlock(appBundlePath, detail, version) {
+function installedBundleSealBlock(appBundlePath, detail, version, context = "update") {
+  const message = context === "startup" ? "This copy of Local Operator did not pass its integrity check, so it can't repair itself." : version ? `This install of Local Operator can't be updated in place, so the update to version ${version} was stopped before the app quit.` : "This install of Local Operator can't be updated in place, so the update was stopped before the app quit.";
   return {
     code: "installed-bundle-not-sealed",
-    message: version ? `This install of Local Operator can't be updated in place, so the update to version ${version} was stopped before the app quit.` : "This install of Local Operator can't be updated in place, so the update was stopped before the app quit.",
+    message,
     remedy: {
       text: "Quit Local Operator, then download a fresh copy and replace the app in Applications.",
       url: DOWNLOAD_PAGE_URL
     },
-    detail: `${appBundlePath}: ${detail}`
+    detail: `${appBundlePath}: ${detail}`,
+    ...context === "startup" ? {
+      heading: "This copy of Local Operator needs replacing",
+      dismissLabel: "Not now"
+    } : {}
   };
 }
 const VIOLATION_LINE = /^file (added|modified|missing):\s*(.+)$/;
@@ -8593,7 +9865,12 @@ function canonicalPath(path2) {
     }
   }
 }
-const BUNDLED_PYTHON_DIRS = ["python", "python_aarch64"];
+const BUNDLED_PYTHON_DIRS = [
+  ...BUNDLED_PYTHON_LAYOUT.legacyResourceNames,
+  ...BUNDLED_PYTHON_LAYOUT.architectures.map(
+    (arch) => `${BUNDLED_PYTHON_LAYOUT.seedNamespace}/${arch}`
+  )
+];
 function isPythonBytecodePath(bundlePath, candidate) {
   const bundle = canonicalPath(bundlePath);
   const path2 = canonicalPath(candidate);
@@ -9640,7 +10917,7 @@ function resolveGlobalInstallPlan(input) {
     sourceBuild: false
   };
 }
-function buildPipUpgradeCommand(pythonPath) {
+function buildPipUpgradeCommand(pythonPath2) {
   const args = [
     "-m",
     "pip",
@@ -9651,9 +10928,9 @@ function buildPipUpgradeCommand(pythonPath) {
     "local-operator"
   ];
   return {
-    command: pythonPath,
+    command: pythonPath2,
     args,
-    display: `"${pythonPath}" ${args.join(" ")}`
+    display: `"${pythonPath2}" ${args.join(" ")}`
   };
 }
 const PIP_SHOW_VERSION_REGEX = /^Version:\s*(.+)$/m;
@@ -9678,6 +10955,7 @@ const BUNDLE_ID_REGEX = /^[\w.-]+$/;
 const INSTALL_IN_FLIGHT_RECHECK_MS = 1e4;
 const LAUNCHCTL_NOT_LOADED_REGEX = /could not find|no such process/i;
 const SEAL_PROBE_TIMEOUT_MS = 45e3;
+const STARTUP_SEAL_PROBE_DELAY_MS = 15e3;
 function versionSuffix(version) {
   return version ? ` to version ${version}` : "";
 }
@@ -9760,6 +11038,19 @@ class UpdateService {
   /** A failed install detected from the marker on this start, if any. */
   pendingInstallFailure = null;
   installFailureDelivered = false;
+  /**
+   * A refusal this process found at start-up, if any.
+   *
+   * Kept apart from `pendingInstallFailure` because they are different facts with
+   * different remedies - that one is an install that did not finish, this one is a
+   * bundle that can no longer be replaced in place - and both can be true of the
+   * same start. Delivered through the same scheduler shape for the same reason:
+   * the window is loading when this is produced (the service is constructed as
+   * the window is created), and a bare `webContents.send` with no subscriber
+   * still reports success.
+   */
+  pendingInstallBlock = null;
+  installBlockDelivered = false;
   /**
    * An install this process found still running, if any.
    *
@@ -9826,6 +11117,15 @@ class UpdateService {
     electronUpdater.autoUpdater.autoInstallOnAppQuit = false;
     this.setupUpdateEvents();
     this.recoverPendingInstall();
+    const sealProbe = setTimeout(() => {
+      void this.repairReachableBundleSeals().catch((error) => {
+        logger.warn(
+          `Start-up seal check could not run: ${error instanceof Error ? error.message : String(error)}`,
+          LogFileType.UPDATE_SERVICE
+        );
+      });
+    }, STARTUP_SEAL_PROBE_DELAY_MS);
+    sealProbe.unref();
     this.startPeriodicUpdateChecks();
   }
   /**
@@ -9893,13 +11193,32 @@ class UpdateService {
       `Update refused (${block.code}): ${block.detail}`,
       LogFileType.UPDATE_SERVICE
     );
-    this.sendToRenderer("update-install-blocked", {
+    this.sendToRenderer(
+      "update-install-blocked",
+      this.installBlockPayload(block, version ?? null)
+    );
+  }
+  /**
+   * The refusal payload the renderer's panel reads.
+   *
+   * One builder, so a refusal found at start-up and one found by the pre-flight
+   * cannot arrive in two shapes: the renderer keys the heading off `code` and the
+   * remedy off `remedy`, and a field missing in one path is a panel that renders
+   * nothing where the user was told what to do.
+   */
+  installBlockPayload(block, version) {
+    return {
       code: block.code,
-      version: version ?? null,
+      version,
       message: block.message,
       remedy: block.remedy,
-      detail: block.detail
-    });
+      detail: block.detail,
+      // Both optional, and both must travel: the payload is built field by
+      // field, so a copy the main process owns and this builder forgets is a
+      // panel that renders the default heading (design D2, D3).
+      heading: block.heading ?? null,
+      dismissLabel: block.dismissLabel ?? null
+    };
   }
   /**
    * Read the marker a previous run may have left, and act on it.
@@ -9919,6 +11238,14 @@ class UpdateService {
    * alone entirely, and the re-check below reports what really happens to it.
    */
   recoverPendingInstall() {
+    if (!electron.app.isPackaged) {
+      const marker2 = readPendingInstallMarker(this.markerDir());
+      logger.info(
+        marker2 ? `Unpackaged instance: leaving the packaged app's pending install marker for version ${marker2.targetVersion} alone, with its install job and staging tree; this process cannot act on an install of a bundle it is not.` : "Unpackaged instance: no packaged install state to leave alone.",
+        LogFileType.UPDATE_SERVICE
+      );
+      return;
+    }
     const marker = readPendingInstallMarker(this.markerDir());
     const outcome = evaluatePendingInstall({
       marker,
@@ -10131,6 +11458,43 @@ class UpdateService {
       LogFileType.UPDATE_SERVICE
     );
   }
+  /**
+   * Deliver a refusal found at start-up once the renderer can hear it.
+   *
+   * Same shape as the failure's delivery, for the same measured reason: the
+   * refusal is produced while the window is loading (the service is constructed
+   * as the window is created), the panel subscribes from a React effect that can
+   * run after `did-finish-load`, and `sendToRenderer` answers true for a push
+   * that no subscriber saw. Unlike the failure it clears nothing on the way out -
+   * this refusal is not tied to any on-disk state, and the pre-flight's own
+   * direct push (`sendInstallBlock`) stays the path used when the window is
+   * already up.
+   */
+  scheduleInstallBlockDelivery(block) {
+    this.pendingInstallBlock = block;
+    if (this.installBlockDelivered) return;
+    const deliver = () => this.deliverPendingInstallBlock();
+    const webContents = this.mainWindow?.webContents;
+    if (webContents && !webContents.isDestroyed()) {
+      webContents.once("did-finish-load", deliver);
+    }
+    setTimeout(deliver, 5e3);
+  }
+  deliverPendingInstallBlock() {
+    const block = this.pendingInstallBlock;
+    if (!block || this.installBlockDelivered) return;
+    if (!this.sendToRenderer(
+      "update-install-blocked",
+      this.installBlockPayload(block, null)
+    )) {
+      return;
+    }
+    this.installBlockDelivered = true;
+    logger.info(
+      "Reported a start-up refusal to the renderer",
+      LogFileType.UPDATE_SERVICE
+    );
+  }
   /**
    * A substituted answer to "is this app's install job loaded", or null.
    *
@@ -10375,17 +11739,68 @@ class UpdateService {
    * backend. Those writes are `file added:` violations and deleting exactly
    * those files restores the seal (measured; see `healPythonBytecode`), where a
    * bundle broken any other way still gets the reinstall refusal below.
+   *
+   * The probe, the retry and the heal are `readBundleSeal` and `repairBundleSeal`
+   * below, shared with the start-up repair pass: this method is the update-time
+   * policy on top of them (an unanswerable probe proceeds, an unhealable bundle
+   * refuses the install), and it must not grow a second copy of either.
    */
   async probeInstalledBundleSeal(version) {
+    const bundlePath = this.runningBundlePath();
+    if (!bundlePath) return null;
+    const { seal, heal, block } = await this.repairBundleSeal(
+      bundlePath,
+      version
+    );
+    if (seal.kind === "unavailable") {
+      logger.warn(
+        `Seal check could not run twice, continuing with the install: ${seal.detail}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    if (seal.kind === "sealed") {
+      logger.info(
+        heal ? `Installed bundle sealed again after removing ${heal.removed.length} added bytecode file(s); continuing with the install.` : `Installed bundle passed its seal check: ${bundlePath}`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+    return block;
+  }
+  /**
+   * The `.app` this process runs from, or null when it is not a bundle layout.
+   *
+   * Shared by the pre-flight and the start-up repair pass so both ask about the
+   * same bundle, and so the "unpacked or dev run" answer is stated once: not a
+   * bundle we recognise means nothing to verify, and refusing every install
+   * because the path did not parse would be worse than the risk it guards
+   * against.
+   */
+  runningBundlePath() {
     if (process.platform !== "darwin" || !electron.app.isPackaged) return null;
     const bundlePath = appBundleFromExecutable(process.execPath);
     if (!bundlePath) {
       logger.warn(
-        `Could not derive an app bundle from ${process.execPath}; skipping the seal pre-flight.`,
+        `Could not derive an app bundle from ${process.execPath}; skipping the seal checks.`,
         LogFileType.UPDATE_SERVICE
       );
       return null;
     }
+    return bundlePath;
+  }
+  /**
+   * One `codesign --verify` of `bundlePath`, retried once when it could not run.
+   *
+   * The retry lives here rather than at either caller because "did not complete"
+   * is a fact about the probe, not about the install being offered: measured on
+   * macOS 26.5, a 1 GiB bundle answers in 6.1 s warm, and a timeout or a probe
+   * that died silently used to arrive as exit code 1 - which the pre-flight read
+   * as "codesign rejected this bundle" and turned into a permanent reinstall
+   * message (review R5). `probe` is returned beside the verdict because the
+   * heal reads the violations out of the raw stdout, and a second probe for them
+   * would be a second answer about one bundle.
+   */
+  async readBundleSeal(bundlePath) {
     const probeBundle = () => runCommand(
       "/usr/bin/codesign",
       ["--verify", "--deep", "--verbose=2", bundlePath],
@@ -10401,20 +11816,29 @@ class UpdateService {
       probe = await probeBundle();
       seal = evaluateBundleSeal(probe);
     }
-    if (seal.kind === "unavailable") {
-      logger.warn(
-        `Seal check could not run twice, continuing with the install: ${seal.detail}`,
-        LogFileType.UPDATE_SERVICE
-      );
-      return null;
-    }
-    if (seal.kind === "sealed") {
-      logger.info(
-        `Installed bundle passed its seal check: ${bundlePath}`,
-        LogFileType.UPDATE_SERVICE
-      );
-      return null;
-    }
+    return { seal, probe };
+  }
+  /**
+   * Probe the bundle, heal the one break we cause, and probe again.
+   *
+   * The whole mechanism, run identically by the update pre-flight and by the
+   * start-up pass: a sealed bundle is returned untouched, an unsealed one is
+   * healed only when the plan says the break is ours (`planPythonBytecodeHeal`),
+   * and the verdict that follows the heal is a fresh probe rather than an
+   * assumption about what a deletion did. `block` is the refusal to show when the
+   * bundle cannot be put back together, and it carries the version the caller was
+   * asked about (null at start-up, where no update is being offered yet).
+   *
+   * Why start-up also runs this: the break is introduced by the app running, not
+   * by the update, so by the time an install is attempted the bundle may already
+   * have been refused by macOS at launch - measured on 2026-09-14, a bundle
+   * signed at 09:31:53 with one added
+   * `lib/python3.12/__pycache__/webbrowser.cpython-312.pyc` at 10:11:29, and no
+   * packaged instance ever came back to report it.
+   */
+  async repairBundleSeal(bundlePath, version, context = "update") {
+    const { seal, probe } = await this.readBundleSeal(bundlePath);
+    if (seal.kind !== "unsealed") return { seal, heal: null, block: null };
     logger.error(
       `Installed bundle failed its seal check: ${seal.detail}`,
       LogFileType.UPDATE_SERVICE
@@ -10426,28 +11850,117 @@ class UpdateService {
         `Installed bundle is not healable in place: ${heal.reason}`,
         LogFileType.UPDATE_SERVICE
       );
-      return installedBundleSealBlock(bundlePath, seal.detail, version);
+      return {
+        seal,
+        heal,
+        block: installedBundleSealBlock(
+          bundlePath,
+          seal.detail,
+          version,
+          context
+        )
+      };
     }
     logger.info(
       `Removed ${heal.removed.length} bytecode file(s) our own interpreter had written into the sealed bundle: ${heal.reason}. Paths:
 ${heal.removed.join("\n")}`,
       LogFileType.UPDATE_SERVICE
     );
-    const healed = evaluateBundleSeal(await probeBundle());
+    const { probe: healedProbe } = await this.readBundleSeal(bundlePath);
+    const healed = evaluateBundleSeal(healedProbe);
     if (healed.kind === "sealed") {
-      logger.info(
-        `Installed bundle sealed again after removing ${heal.removed.length} added bytecode file(s); continuing with the install.`,
-        LogFileType.UPDATE_SERVICE
-      );
-      return null;
+      return { seal: healed, heal, block: null };
     }
     logger.error(
       `Installed bundle still fails its seal check after healing: ${healed.detail}`,
       LogFileType.UPDATE_SERVICE
     );
-    return installedBundleSealBlock(bundlePath, healed.detail, version);
+    return {
+      seal: healed,
+      heal,
+      block: installedBundleSealBlock(
+        bundlePath,
+        healed.detail,
+        version,
+        context
+      )
+    };
+  }
+  /** Inspect only the app this process runs from. An unpackaged instance must
+   * never traverse, heal, seal or otherwise mutate another installed bundle. */
+  async repairReachableBundleSeals() {
+    this.reportLegacyVenvInterpreters();
+    const running = this.runningBundlePath();
+    if (running) await this.repairRunningBundleSeal(running);
+  }
+  /**
+   * Say what the pre-split environments resolve to, and change nothing.
+   *
+   * An install from before this change has a venv whose `pyvenv.cfg` `home` is
+   * inside an `.app`, and one whose bundle is already gone is a state this
+   * machine has actually been in. Both are reported because they explain the log
+   * a support conversation reads - "this venv belongs to a bundle that is not
+   * here any more" and "this venv is still built on the installed app's
+   * interpreter" are different facts, and silence makes them look like the same
+   * healthy one. Neither is repaired: those environments are left byte-identical,
+   * deliberately, so a rollback to an older build still finds what it built.
+   *
+   * Darwin only, and by construction rather than by choice: what is reported is a
+   * venv built on the interpreter inside a code-sealed `.app`, and no other
+   * platform has one (`BUNDLED_INTERPRETER_HOME` requires the `.app` component).
+   *
+   * It reads `legacyVenvPaths`, NOT `managedVenvPath`. That was the bug: on darwin
+   * `managedVenvPath` answers with the post-split selection venv - whose
+   * `pyvenv.cfg` names the external runtime by construction - or with the
+   * `no-environment-selected` sentinel, so both iterations took the `continue` and
+   * nothing was ever logged for the state this exists to describe (review R7).
+   */
+  reportLegacyVenvInterpreters() {
+    if (process.platform !== "darwin") return;
+    for (const line of legacyEnvironmentReport(
+      managedSupportRoot(electron.app.getPath("home"))
+    ))
+      logger.info(line, LogFileType.UPDATE_SERVICE);
+  }
+  /**
+   * Repair this bundle's seal at start-up, and say so either way.
+   *
+   * What this catches: a bundle that already carries bytecode its own interpreter
+   * wrote after it was signed. macOS refuses such a bundle at launch
+   * ("damaged and can't be opened") and ShipIt refuses the next in-place update
+   * with -67028, so a break found here is repaired before either can happen, and
+   * one that cannot be repaired is reported with the same refusal/remedy panel
+   * the pre-flight uses - the user has to replace the app by hand, and finding
+   * that out at the next update is worse than being told now.
+   *
+   * Nothing is reported when the bundle is sealed, which is every ordinary
+   * start: the log line is the evidence that the pass ran at all.
+   */
+  async repairRunningBundleSeal(bundlePath) {
+    const { seal, heal, block } = await this.repairBundleSeal(
+      bundlePath,
+      null,
+      "startup"
+    );
+    if (seal.kind === "sealed") {
+      logger.info(
+        heal ? `Start-up seal repair: removed ${heal.removed.length} added bytecode file(s) from ${bundlePath}, and the bundle verifies again.` : `Start-up seal check: ${bundlePath} is a sealed code object.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return;
+    }
+    if (seal.kind === "unavailable") {
+      logger.warn(
+        `Start-up seal check could not run: ${seal.detail}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return;
+    }
+    if (block) this.scheduleInstallBlockDelivery(block);
   }
-  /** File names the updater's metadata knows this update by. */
+  /**
+   * File names the updater's metadata knows this update by.
+   */
   stagedArtifactCandidates(info) {
     const names = /* @__PURE__ */ new Set();
     if (info?.path) names.add(path$1.basename(info.path));
@@ -10904,6 +12417,13 @@ ${heal.removed.join("\n")}`,
         );
         return false;
       }
+      if (!electron.app.isPackaged) {
+        logger.info(
+          "Refusing to start an update install: this instance is unpackaged, so it is not the bundle an install replaces.",
+          LogFileType.UPDATE_SERVICE
+        );
+        return false;
+      }
       logger.info(
         "Preparing to quit and install the update...",
         LogFileType.UPDATE_SERVICE
@@ -11544,9 +13064,9 @@ ${heal.removed.join("\n")}`,
    * @returns Promise resolving to true if update was successful, false otherwise
    */
   /** The version the bundled environment has installed, via `pip show`. */
-  async readBundledBackendVersion(pythonPath) {
+  async readBundledBackendVersion(pythonPath2) {
     const probe = await runCommand(
-      pythonPath,
+      pythonPath2,
       ["-m", "pip", "show", "local-operator"],
       { timeoutMs: 12e4, env: this.pythonSpawnEnv() }
     );
@@ -11686,16 +13206,19 @@ ${heal.removed.join("\n")}`,
           LogFileType.UPDATE_SERVICE
         );
       }
-      let pythonPath = "";
+      let pythonPath2 = "";
       const venvPath = this.backendService?.getVenvPath();
       if (venvPath && electron.app.isPackaged) {
         const venvBinDir = process.platform === "win32" ? "Scripts" : "bin";
         const pythonName = process.platform === "win32" ? "python.exe" : "python3";
-        pythonPath = path$1.join(venvPath, venvBinDir, pythonName);
+        pythonPath2 = path$1.join(venvPath, venvBinDir, pythonName);
       }
-      if (!pythonPath || !fs.existsSync(pythonPath)) {
+      if (!pythonPath2 || !fs.existsSync(pythonPath2)) {
         logger.error(
-          `Cannot update the bundled backend: no Python at ${pythonPath || "an unknown path"}`,
+          // `managedVenvPath` answers with a sentinel when no environment has
+          // been published, and "no Python at …/no-environment-selected" sent a
+          // reader to a directory-shaped path that nothing creates (review N3).
+          isUnpreparedVenvPath(venvPath ?? "") ? "Cannot update the bundled backend: no environment has been selected for this instance yet" : `Cannot update the bundled backend: no Python at ${pythonPath2 || "an unknown path"}`,
           LogFileType.UPDATE_SERVICE
         );
         await this.restartBackendAfterFailedUpgrade();
@@ -11705,8 +13228,8 @@ ${heal.removed.join("\n")}`,
         );
         return false;
       }
-      const pip = buildPipUpgradeCommand(pythonPath);
-      const versionBefore = await this.readBundledBackendVersion(pythonPath);
+      const pip = buildPipUpgradeCommand(pythonPath2);
+      const versionBefore = await this.readBundledBackendVersion(pythonPath2);
       logger.info(
         `Executing pip command: ${pip.display}`,
         LogFileType.UPDATE_SERVICE
@@ -11727,7 +13250,7 @@ ${pipRun.stderr.trim()}`,
           LogFileType.UPDATE_SERVICE
         );
       }
-      const versionAfter = await this.readBundledBackendVersion(pythonPath);
+      const versionAfter = await this.readBundledBackendVersion(pythonPath2);
       const upgradeLanded = pipRun.exitCode === 0 && didUpgradeLand({
         before: versionBefore,
         after: versionAfter,
@@ -11979,6 +13502,311 @@ ${pipRun.stderr.trim()}`,
     }
   }
 }
+const AUTH_TIMEOUT_MS = 5e3;
+const MAX_FRAME_BYTES = 64 * 1024;
+const SESSION_ID = /^[a-f0-9]{12}$/;
+class ViewerEndpoint {
+  constructor(host, key) {
+    this.host = host;
+    this.key = key;
+  }
+  server = null;
+  port = 0;
+  get boundPort() {
+    return this.port;
+  }
+  /**
+   * Bind on loopback and answer the port.
+   *
+   * IDEMPOTENT, and that is load-bearing: a window can be recreated, and the
+   * app's own `activate` path runs again after every close. A second bind
+   * would leak a listener, and a leaked listener is worse than a leaked
+   * source because the record then advertises a port nothing reads.
+   */
+  start() {
+    if (this.server) return Promise.resolve(this.port);
+    return new Promise((resolve, reject) => {
+      const server = node_net.createServer((socket) => this.onConnection(socket));
+      server.on("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const address = server.address();
+        if (address === null || typeof address === "string") {
+          server.close();
+          reject(new Error("The viewer endpoint could not resolve its port."));
+          return;
+        }
+        this.server = server;
+        this.port = address.port;
+        server.removeAllListeners("error");
+        server.on("error", () => void 0);
+        resolve(this.port);
+      });
+    });
+  }
+  /** Stop serving. Idempotent, and safe on a listener that never bound. */
+  close() {
+    const server = this.server;
+    this.server = null;
+    this.port = 0;
+    if (!server) return;
+    try {
+      server.close();
+    } catch {
+    }
+  }
+  onConnection(socket) {
+    let authenticated = false;
+    let buffer = "";
+    let closed = false;
+    let chain = Promise.resolve();
+    const finish = () => {
+      closed = true;
+      socket.destroy();
+    };
+    const authTimer = setTimeout(() => {
+      if (!authenticated) finish();
+    }, AUTH_TIMEOUT_MS);
+    socket.setEncoding("utf8");
+    socket.on("error", finish);
+    socket.on("close", () => clearTimeout(authTimer));
+    socket.on("data", (chunk) => {
+      if (closed) return;
+      buffer += chunk;
+      if (buffer.length > MAX_FRAME_BYTES) {
+        finish();
+        return;
+      }
+      for (; ; ) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0) break;
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        chain = chain.then(
+          () => this.onLine(line, socket, {
+            isAuthenticated: () => authenticated,
+            markAuthenticated: () => {
+              authenticated = true;
+              clearTimeout(authTimer);
+            },
+            finish
+          }).catch(() => void 0)
+        );
+      }
+    });
+  }
+  async onLine(line, socket, state) {
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (typeof frame !== "object" || frame === null) return;
+    const record = frame;
+    if (!state.isAuthenticated()) {
+      const key = typeof record.key === "string" ? record.key : "";
+      if (!constantTimeEqual(key, this.key)) {
+        state.finish();
+        return;
+      }
+      state.markAuthenticated();
+      return;
+    }
+    const op = typeof record.op === "string" ? record.op : "";
+    const req = record.req;
+    let reply;
+    try {
+      reply = { op: "ack", req, detail: await this.apply(op, record) };
+    } catch (error) {
+      reply = {
+        op: "error",
+        req,
+        detail: error instanceof Error ? error.message : "refused"
+      };
+    }
+    try {
+      socket.write(`${JSON.stringify(reply)}
+`);
+    } catch {
+      state.finish();
+    }
+  }
+  async apply(op, frame) {
+    if (op === "resume_session") {
+      const sessionId2 = String(frame.session_id ?? "");
+      if (!SESSION_ID.test(sessionId2)) {
+        throw new Error("resume_session needs a session id");
+      }
+      return await this.host.resumeSession(sessionId2);
+    }
+    if (op === "focus_window") {
+      return await this.host.focusWindow();
+    }
+    throw new Error(`unknown viewer op: ${op || "(none)"}`);
+  }
+}
+function constantTimeEqual(actual, expected) {
+  const a = Buffer.from(actual, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  if (a.length !== b.length) {
+    node_crypto.timingSafeEqual(b, b);
+    return false;
+  }
+  return node_crypto.timingSafeEqual(a, b);
+}
+const VIEWER_RUN_DIRNAME = "run/viewers";
+const VIEWER_PROTOCOL = 1;
+const FOCUS_WINDOW_CAPABILITY = "focus-window-v1";
+const DESKTOP_NOTIFY_CAPABILITY = "desktop-notify-v1";
+const VIEWER_HEARTBEAT_INTERVAL_MS = 15e3;
+function viewerRunDir(env = process.env) {
+  const root = env.LOCAL_OPERATOR_CONFIG_DIR || path$1.join(os.homedir(), ".local-operator");
+  return path$1.join(root, VIEWER_RUN_DIRNAME);
+}
+function publishViewerRecord(record, dir = viewerRunDir()) {
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs.chmodSync(dir, 448);
+  const target2 = path$1.join(dir, `${record.pid}.json`);
+  const temporary = path$1.join(
+    dir,
+    `.${record.pid}.${node_crypto.randomBytes(6).toString("hex")}.tmp`
+  );
+  fs.writeFileSync(temporary, JSON.stringify(record), { mode: 384 });
+  fs.renameSync(temporary, target2);
+  return target2;
+}
+function unpublishViewerRecord(pid, dir = viewerRunDir()) {
+  try {
+    fs.unlinkSync(path$1.join(dir, `${pid}.json`));
+  } catch {
+  }
+}
+class ViewerRecordPublisher {
+  constructor(dir = viewerRunDir(), pid = process.pid) {
+    this.dir = dir;
+    this.record = {
+      pid,
+      surface: "desktop",
+      // 0 until the listener binds. A record advertising port 0 is not
+      // dialable, which is the honest answer during the gap and the reason
+      // the endpoint stamps the real port before anything else.
+      control_port: 0,
+      // The whole authorization story: 32 random bytes, 0600 on disk.
+      control_key: node_crypto.randomBytes(32).toString("hex"),
+      current_session: "",
+      // True even with no window: `resume_session` RECREATES the window and
+      // then navigates (B3), so routing a click here is still the cheapest
+      // landing site on a machine where the app is alive in the dock. What
+      // the record must not claim while no window exists is a CONVERSATION
+      // (`current_session` stays `""`), because that field is what lets a
+      // click skip the switch.
+      can_switch: true,
+      focused_at: 0,
+      protocol: VIEWER_PROTOCOL,
+      started_at: Date.now() / 1e3,
+      heartbeat_at: Date.now() / 1e3,
+      capabilities: [FOCUS_WINDOW_CAPABILITY, DESKTOP_NOTIFY_CAPABILITY]
+    };
+  }
+  record;
+  timer = null;
+  stopped = false;
+  /**
+   * Whether anything has been written yet.
+   *
+   * `setControlPort` lands BEFORE `start` in the app's own ordering (the port
+   * only exists once the listener has bound, and the listener is what the
+   * record advertises), so a publisher that wrote on every setter would put a
+   * port-0 record in the directory for a moment — and a reader that dialled it
+   * would spend its whole dial timeout on nothing. Mutations accumulate; the
+   * first write is `start`'s.
+   */
+  started = false;
+  get controlKey() {
+    return this.record.control_key;
+  }
+  /** Record the port the control listener actually bound, and publish. */
+  setControlPort(port) {
+    this.record.control_port = port;
+    this.publish();
+  }
+  /**
+   * Record which conversation is on screen now.
+   *
+   * An early return on an unchanged value keeps the 15 s beat from being a
+   * disk write at navigation cadence: a re-render that re-asserts the same
+   * session costs nothing.
+   */
+  noteSession(sessionId2) {
+    if (this.record.current_session === sessionId2) return;
+    this.record.current_session = sessionId2;
+    this.publish();
+  }
+  /**
+   * Withdraw the report that THIS conversation is on screen, because the pane
+   * that made it has left it (QA round 2, Q1).
+   *
+   * `current_session` is the record's answer to "which conversation should a
+   * banner click land on", so leaving it naming a conversation the user has
+   * navigated away from is not a stale label — it is a wrong destination the
+   * backend then confirms: `needs_switch` is false for a match, so the click is
+   * answered with a raise, that branch reports success, and no later rung of the
+   * click ladder is tried. The user gets whatever the window happens to show
+   * (the catalogue, Settings) instead of the conversation they were called back
+   * to, and this branch's own presence withdrawal is what makes that click
+   * `focus_policy: "always"` — the case the feature exists for.
+   *
+   * IDENTITY-SAFE, like the notifier's own `releaseWatch` and for the same
+   * reason: the release runs from a renderer cleanup, after the pane has already
+   * changed, so an unconditional clear would wipe a session a DEEPER pane has
+   * since reported. An EMPTY id withdraws nothing — `""` is this record's own
+   * "nothing is on screen" value, so a caller sending it is not naming a
+   * conversation to leave.
+   *
+   * Losing the report is self-healing rather than lossy: a pane that still holds
+   * the conversation re-asserts it on its next heartbeat, which is the same
+   * 15 s beat that wrote it.
+   */
+  releaseSession(sessionId2) {
+    if (!sessionId2 || this.record.current_session !== sessionId2) return;
+    this.record.current_session = "";
+    this.publish();
+  }
+  /** Stamp the focus GAIN edge only. A blur carries no routing information. */
+  noteFocused() {
+    this.record.focused_at = Date.now() / 1e3;
+    this.publish();
+  }
+  /** Begin the beat, and write the record for the first time. Idempotent,
+   * because a window can be recreated. */
+  start() {
+    if (this.timer || this.stopped) return;
+    this.started = true;
+    this.publish();
+    this.timer = setInterval(
+      () => this.publish(),
+      VIEWER_HEARTBEAT_INTERVAL_MS
+    );
+    this.timer.unref?.();
+  }
+  /** Stop beating and remove the record. Safe to call twice. */
+  stop() {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    unpublishViewerRecord(this.record.pid, this.dir);
+  }
+  publish() {
+    if (this.stopped || !this.started) return;
+    this.record.heartbeat_at = Date.now() / 1e3;
+    try {
+      publishViewerRecord(this.record, this.dir);
+    } catch {
+    }
+  }
+}
 const WINDOW_MODES = ["normal", "headless", "inactive"];
 const WINDOW_MODE_ENV = "LOCAL_OPERATOR_UI_WINDOW_MODE";
 const WINDOW_SIZE_ENV = "LOCAL_OPERATOR_UI_WINDOW_SIZE";
@@ -12103,16 +13931,16 @@ function createApplicationMenu() {
   const isDev = Boolean(process.env.ELECTRON_RENDERER_URL);
   const zoomInHandler = () => {
     if (mainWindow) {
-      const webContents = mainWindow.webContents;
-      const currentZoom = webContents.getZoomFactor();
-      webContents.setZoomFactor(currentZoom + 0.1);
+      const webContents2 = mainWindow.webContents;
+      const currentZoom = webContents2.getZoomFactor();
+      webContents2.setZoomFactor(currentZoom + 0.1);
     }
   };
   const zoomOutHandler = () => {
     if (mainWindow) {
-      const webContents = mainWindow.webContents;
-      const currentZoom = webContents.getZoomFactor();
-      webContents.setZoomFactor(currentZoom - 0.1);
+      const webContents2 = mainWindow.webContents;
+      const currentZoom = webContents2.getZoomFactor();
+      webContents2.setZoomFactor(currentZoom - 0.1);
     }
   };
   const actualSizeHandler = () => {
@@ -12237,7 +14065,7 @@ function createApplicationMenu() {
   const menu = electron.Menu.buildFromTemplate(template);
   electron.Menu.setApplicationMenu(menu);
 }
-function createWindow() {
+function createWindow(initialSession = null, openCatalogue = false) {
   const mainWindow2 = new electron.BrowserWindow({
     width: windowLaunch.width,
     height: windowLaunch.height,
@@ -12284,16 +14112,33 @@ function createWindow() {
       // than from anything this app controls, so hold the page at full
       // rate explicitly instead of trusting the platform. `normal`
       // keeps Electron's own default.
-      backgroundThrottling: windowLaunch.backgroundThrottling
+      backgroundThrottling: windowLaunch.backgroundThrottling,
+      /*
+       * The conversation this window is being created FOR, in the renderer
+       * process's own argv so preload can read it before the first paint (B3).
+       *
+       * Omitted entirely rather than set to an empty value on an ordinary
+       * launch: the preload parses a flag out of argv, and an empty one would
+       * be a value it then has to decide means "no session".
+       *
+       * `openCatalogue` is the THIRD intent (R2-1): a burst digest's click has
+       * no single conversation to name, and "no flag at all" already means
+       * "restore what you had open" — so it needs a flag of its own rather than
+       * sharing that absence.
+       */
+      ...launchArgumentFlags(initialSession, openCatalogue)
     }
   });
+  if (initialSession) holdPresentUntilConversation(mainWindow2, initialSession);
   mainWindow2.webContents.on("console-message", (_event, level, message) => {
     if (level < 2) return;
     const write = level >= 3 ? logger.error : logger.warn;
     write.call(logger, `[renderer] ${message}`, LogFileType.BACKEND);
   });
   mainWindow2.on("ready-to-show", () => {
-    presentWindow(mainWindow2, windowLaunch.show);
+    if (!heldForConversation.has(mainWindow2.id)) {
+      presentWindow(mainWindow2, windowLaunch.show);
+    }
     if (windowLaunch.mode === "normal") return;
     setTimeout(() => {
       if (!mainWindow2 || mainWindow2.isDestroyed()) return;
@@ -12369,6 +14214,7 @@ function createWindow() {
   } else {
     mainWindow2.loadFile(path$1.join(__dirname, "../renderer/index.html"));
   }
+  attachBrowserHostToWindow?.(mainWindow2);
   return mainWindow2;
 }
 const backendService = new BackendServiceManager();
@@ -12396,18 +14242,57 @@ if (windowLaunch.mode !== "normal") {
 }
 let mainWindow = null;
 let activeUpdateService = null;
+const launchTarget = readLaunchTarget(process.argv);
+const launchSession = launchTarget.kind === "session" ? launchTarget.sessionId : null;
+const launchCatalogue = launchTarget.kind === "catalogue";
+function launchArgumentFlags(initialSession, openCatalogue) {
+  if (initialSession) {
+    return { additionalArguments: [`${OPEN_SESSION_FLAG}=${initialSession}`] };
+  }
+  if (openCatalogue) return { additionalArguments: [OPEN_CATALOGUE_FLAG] };
+  return {};
+}
+let queuedSession = null;
+let viewerRecord = null;
+let viewerEndpoint = null;
+let openConversationInWindow = null;
+let attachBrowserHostToWindow = null;
+const CONVERSATION_PAINT_FALLBACK_MS = 3e3;
+const heldForConversation = /* @__PURE__ */ new Map();
+function holdPresentUntilConversation(window, session) {
+  const timer = setTimeout(() => {
+    releaseHeldWindow(window.id);
+  }, CONVERSATION_PAINT_FALLBACK_MS);
+  timer.unref?.();
+  heldForConversation.set(window.id, { session, timer });
+}
+function releaseHeldWindow(windowId) {
+  const held = heldForConversation.get(windowId);
+  if (!held) return false;
+  clearTimeout(held.timer);
+  heldForConversation.delete(windowId);
+  const window = electron.BrowserWindow.fromId(windowId);
+  if (window && !window.isDestroyed()) presentWindow(window, windowLaunch.show);
+  return true;
+}
+function releaseHeldWindowFor(session) {
+  for (const [windowId, held] of heldForConversation) {
+    if (held.session !== session) continue;
+    releaseHeldWindow(windowId);
+  }
+}
 const zoomInFromEvent = () => {
   if (mainWindow) {
-    const webContents = mainWindow.webContents;
-    const currentZoom = webContents.getZoomFactor();
-    webContents.setZoomFactor(currentZoom + 0.1);
+    const webContents2 = mainWindow.webContents;
+    const currentZoom = webContents2.getZoomFactor();
+    webContents2.setZoomFactor(currentZoom + 0.1);
   }
 };
 const zoomOutFromEvent = () => {
   if (mainWindow) {
-    const webContents = mainWindow.webContents;
-    const currentZoom = webContents.getZoomFactor();
-    webContents.setZoomFactor(currentZoom - 0.1);
+    const webContents2 = mainWindow.webContents;
+    const currentZoom = webContents2.getZoomFactor();
+    webContents2.setZoomFactor(currentZoom - 0.1);
   }
 };
 const actualSizeFromEvent = () => {
@@ -12421,6 +14306,12 @@ if (!gotTheLock) {
   electron.app.quit();
 } else {
   electron.app.on("second-instance", (_event, commandLine) => {
+    const requested = readOpenSessionArgv(commandLine);
+    if (requested) {
+      if (openConversationInWindow) openConversationInWindow(requested);
+      else queuedSession = requested;
+      return;
+    }
     if (mainWindow) {
       raiseWindow(mainWindow, windowLaunch.show);
     }
@@ -12445,10 +14336,45 @@ electron.app.whenReady().then(async () => {
   const desktopNotifier = new DesktopNotifier(
     () => mainWindow,
     sendDesktop,
-    windowLaunch.show
+    windowLaunch.show,
+    {
+      /*
+       * Whether a window we have a heartbeat from is still there.
+       *
+       * `forgetWindow` is called on `closed`, which covers every ordinary
+       * close — but a renderer process that dies takes its `webContents` id
+       * with it and no `closed` event reaches the notifier, and those ids
+       * are not reused. Filtering on liveness is what makes a stale
+       * `{visible: true, focused: true}` entry unable to suppress every
+       * completion for the rest of the run.
+       */
+      windowAlive: (windowId) => {
+        const contents = electron.webContents.fromId(windowId);
+        return Boolean(contents && !contents.isDestroyed());
+      },
+      // A banner click with no window recreates one and navigates it. The
+      // queue lives in `openSessionInWindow` because window creation does.
+      reopen: (sessionId2) => openSessionInWindow(sessionId2),
+      /*
+       * The renderer's report that this conversation is on screen. Two
+       * consumers, and neither is delivery:
+       *
+       * - the viewer record's `current_session`, which is how a later click
+       *   routes here and how it skips a redundant switch;
+       * - the held first present of a click-created window, where this report
+       *   IS the "conversation applied" milestone `ready-to-show` is not
+       *   (B3).
+       */
+      noteDisplayed: (sessionId2) => {
+        viewerRecord?.noteSession(sessionId2);
+        releaseHeldWindowFor(sessionId2);
+      }
+    }
   );
   backendService.onBackendReady(() => {
     void desktopNotifier.refreshNotificationContract();
+    void backendService.getDesktopFeedRelay().start();
+    void publishViewerPresence();
   });
   backendService.observeStream((sessionId2, data) => {
     try {
@@ -12457,13 +14383,85 @@ electron.app.whenReady().then(async () => {
     }
   });
   const rendererUrl = process.env.ELECTRON_RENDERER_URL || node_url.pathToFileURL(path$1.join(__dirname, "../renderer/index.html")).href;
+  backendService.observeDesktopFeed(
+    (frame) => {
+      if (frame.type === "notification") {
+        desktopNotifier.observe(frame.session_id, frame);
+        return;
+      }
+      const window = mainWindow;
+      if (!window || window.isDestroyed()) return;
+      window.webContents.send("desktop-feed-frame", frame);
+    },
+    (state) => {
+      const window = mainWindow;
+      if (!window || window.isDestroyed()) return;
+      window.webContents.send("desktop-feed-state", state);
+    }
+  );
+  backendService.providePresenceContext(() => desktopNotifier.presence());
+  electron.ipcMain.on("desktop-feed-watch", () => {
+    const window = mainWindow;
+    if (!window || window.isDestroyed()) return;
+    window.webContents.send("desktop-feed-state", {
+      connected: backendService.getDesktopFeedRelay().isConnected
+    });
+  });
+  const record = new ViewerRecordPublisher();
+  const endpoint2 = new ViewerEndpoint(
+    {
+      resumeSession: async (sessionId2) => {
+        openSessionInWindow(sessionId2);
+        return `showing ${sessionId2}`;
+      },
+      focusWindow: async () => {
+        const window = mainWindow;
+        if (window && !window.isDestroyed()) {
+          raiseWindow(window, windowLaunch.show);
+          return "raised the window";
+        }
+        setupMainWindowWithUpdateService();
+        return "opened a window";
+      }
+    },
+    record.controlKey
+  );
+  viewerRecord = record;
+  viewerEndpoint = endpoint2;
+  let viewerPublished = false;
+  async function publishViewerPresence() {
+    if (viewerPublished) return;
+    let features;
+    try {
+      const response = await backendService.requestDesktop({
+        op: "capabilities"
+      });
+      const body = response.body;
+      features = body?.result?.features;
+    } catch {
+      return;
+    }
+    if (!(Number(features?.desktop_presence ?? 0) >= 1)) return;
+    try {
+      const port = await endpoint2.start();
+      record.setControlPort(port);
+      record.start();
+      viewerPublished = true;
+    } catch (error) {
+      logger.warn(
+        `Viewer endpoint did not bind, so no record is published: ${String(error)}`,
+        LogFileType.BACKEND
+      );
+    }
+  }
   registerDesktopIPC(
     () => mainWindow,
     rendererUrl,
     sendDesktop,
     () => backendService.getStreamRelay(),
     (input, bytes) => backendService.requestDesktopMedia(input, bytes),
-    desktopNotifier
+    desktopNotifier,
+    (sessionId2) => viewerRecord?.releaseSession(sessionId2)
   );
   electron.ipcMain.handle("open-file", async (_, filePath) => {
     try {
@@ -12773,8 +14771,9 @@ electron.app.whenReady().then(async () => {
   }
   createApplicationMenu();
   let updateService = null;
-  function setupMainWindowWithUpdateService() {
-    mainWindow = createWindow();
+  function setupMainWindowWithUpdateService(initialSession = null, openCatalogue = false) {
+    mainWindow = createWindow(initialSession, openCatalogue);
+    const windowId = mainWindow.webContents.id;
     if (mainWindow) {
       mainWindow.webContents.on("before-input-event", (event, input) => {
         const isCmdOrCtrl = input.control || input.meta;
@@ -12803,8 +14802,17 @@ electron.app.whenReady().then(async () => {
         updateService.dispose();
         updateService = null;
       }
+      desktopNotifier.forgetWindow(windowId);
+      if (electron.BrowserWindow.getAllWindows().length === 0)
+        viewerRecord?.noteSession("");
+      if (heldForConversation.has(windowId)) {
+        const held = heldForConversation.get(windowId);
+        if (held) clearTimeout(held.timer);
+        heldForConversation.delete(windowId);
+      }
       mainWindow = null;
     });
+    mainWindow.on("focus", () => viewerRecord?.noteFocused());
     updateService.setupIpcHandlers();
     updateService.handlePlatformSpecifics();
     setTimeout(() => {
@@ -12850,12 +14858,28 @@ electron.app.whenReady().then(async () => {
       );
     }
   }
-  setupMainWindowWithUpdateService();
-  if (mainWindow) await startBrowserHostForWindow(mainWindow);
+  function openSessionInWindow(sessionId2) {
+    const window = mainWindow;
+    if (window && !window.isDestroyed()) {
+      window.webContents.send("desktop-open-conversation", { sessionId: sessionId2 });
+      raiseWindow(window, windowLaunch.show);
+      return;
+    }
+    setupMainWindowWithUpdateService(sessionId2, sessionId2 === null);
+  }
+  openConversationInWindow = openSessionInWindow;
+  attachBrowserHostToWindow = (window) => {
+    void startBrowserHostForWindow(window);
+  };
+  setupMainWindowWithUpdateService(launchSession, launchCatalogue);
+  if (queuedSession) {
+    const queued = queuedSession;
+    queuedSession = null;
+    openSessionInWindow(queued);
+  }
   electron.app.on("activate", () => {
     if (electron.BrowserWindow.getAllWindows().length === 0) {
       setupMainWindowWithUpdateService();
-      if (mainWindow) void startBrowserHostForWindow(mainWindow);
     }
   });
 }).catch((error) => {
@@ -12891,6 +14915,8 @@ const QUIT_FAILSAFE_MARGIN_MS = 5e3;
 const QUIT_CLEANUP_FAILSAFE_MS = CONSOLE_RESOLUTION_WORST_MS + INTERPRETER_RESOLUTION_WORST_MS + OWNED_STOP_WORST_MS + READINESS_POLL_INTERVAL_MS + QUIT_FAILSAFE_MARGIN_MS;
 let backendQuitPending = false;
 electron.app.on("will-quit", (event) => {
+  viewerEndpoint?.close();
+  viewerRecord?.stop();
   if (backendService.isOwnedCleanupComplete()) return;
   event.preventDefault();
   if (backendQuitPending) return;