local-operator-ui 0.23.2 → 0.23.3

package/out/main/index.js

@@ -86,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(),
@@ -280,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
@@ -386,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({
@@ -494,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,
@@ -797,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`,
@@ -807,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);
@@ -920,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":
@@ -1057,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`,
@@ -1139,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;
@@ -1335,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") {
@@ -1345,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
@@ -1364,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)) {
@@ -1421,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) {
@@ -2835,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.
    *
@@ -2895,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);
   }
@@ -8422,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();
@@ -8457,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) => {
@@ -8557,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. */
@@ -8730,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,
@@ -8744,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;
@@ -8808,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,
@@ -8825,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.
    *
@@ -8852,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.
    *
@@ -8909,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) {
@@ -8973,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();
   }
@@ -12728,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";
@@ -12852,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 = () => {
@@ -12986,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,
@@ -13033,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;
@@ -13118,6 +14214,7 @@ function createWindow() {
   } else {
     mainWindow2.loadFile(path$1.join(__dirname, "../renderer/index.html"));
   }
+  attachBrowserHostToWindow?.(mainWindow2);
   return mainWindow2;
 }
 const backendService = new BackendServiceManager();
@@ -13145,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 = () => {
@@ -13170,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);
     }
@@ -13194,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 {
@@ -13206,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 {
@@ -13522,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;
@@ -13552,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(() => {
@@ -13599,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) => {
@@ -13640,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;