local-operator-ui 0.30.4 → 0.30.6

package/out/main/index.js

@@ -255,7 +255,21 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
   }).strict(),
   zod.z.object({
     op: zod.z.literal("sessions.list"),
-    limit: zod.z.number().int().min(1).max(500).optional()
+    limit: zod.z.number().int().min(1).max(500).optional(),
+    /*
+     * Whether ARCHIVED conversations belong in the answer.
+     *
+     * ABSENT MEANS `false`, and that default is a compatibility promise rather
+     * than a preference: a client that predates archiving sends no such field
+     * and must keep the list it always had rather than acquiring rows it has no
+     * way to mark, filter or restore. This app sends `true` and partitions the
+     * archived rows out of every default list itself (see `fetchSessions` in the
+     * canonical sessions store and `visibleRows` in `features/chat/chat-archived`),
+     * which is what lets ONE fetch serve both the hidden list and the two
+     * questions a list that hides them cannot answer: the open conversation's own
+     * archived state, and an unarchive control on a row found by search.
+     */
+    include_archived: zod.z.boolean().optional()
   }).strict(),
   zod.z.object({
     // Content search over the store: name, id, exact conversation body, and
@@ -271,7 +285,61 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     // closed vocabulary stays closed: no caller can send a request whose
     // answer it would have to discard.
     q: zod.z.string().min(1).max(SESSION_SEARCH_MAX_CHARS),
-    limit: zod.z.number().int().min(1).max(500).optional()
+    limit: zod.z.number().int().min(1).max(500).optional(),
+    /*
+     * Whether the SCAN admits archived conversations, absent meaning `false`
+     * (the same compatibility promise `sessions.list` states).
+     *
+     * The sidebar's "Include archived" control is the only writer, and the flag is
+     * in the query's cache key on this side because the two answers to one query
+     * are different questions: without that, toggling the control off would serve
+     * the answer that carries the archived hits and the rows would linger - the
+     * stale-row failure `chat-search.test.mjs` pins.
+     */
+    include_archived: zod.z.boolean().optional()
+  }).strict(),
+  /*
+   * Archive or unarchive ONE conversation: `POST /v1/desktop/sessions/{id}/archive`.
+   *
+   * DESIRED STATE ON THE WIRE (`archived: true|false`), never a bare toggle, for
+   * the reason the pin op states beside its own field: over HTTP a toggle is not
+   * idempotent, and a request retried after a dropped response would flip the
+   * conversation back. Idempotent by construction here rather than by a receipt:
+   * re-archiving an archived conversation writes what is already there, so the op
+   * carries no `requestId` (the same at-most-once trade `sessions.warm` makes for
+   * a call that already is).
+   *
+   * Archiving is RECOVERABLE and therefore never confirmed: it hides the
+   * conversation from the default lists and from search, and unarchiving restores
+   * it. Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`):
+   * a boolean and a 12-char id are not prose.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.archive"),
+    sessionId,
+    archived: zod.z.boolean()
+  }).strict(),
+  /*
+   * Delete ONE conversation PERMANENTLY: `DELETE /v1/desktop/sessions/{id}`.
+   *
+   * `confirmed: true` is required and is not a receipt: it is the wire's own echo
+   * of the user's answer to a danger dialog, so a caller that has not asked cannot
+   * express this request at all (a missing field is a 422 here, by name, rather
+   * than a delete nobody confirmed). The route refuses the delete of a session
+   * that is LIVE with a 409 and a sentence naming the guard - the one refusal this
+   * surface renders inside the dialog that asked, which is why the op needs no
+   * failure vocabulary of its own.
+   *
+   * It removes exactly the addressed conversation and NOT its subagent children;
+   * a surface that has children to mention says so in its own copy rather than
+   * implying a wider blast radius. No `requestId`: the delete is not retried by
+   * this client, and a retry of a delete cannot be owed an answer - the second
+   * call's honest answer is 404 and the outcome the user asked for either way.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.delete"),
+    sessionId,
+    confirmed: zod.z.literal(true)
   }).strict(),
   zod.z.object({
     op: zod.z.literal("sessions.create"),
@@ -1254,7 +1322,10 @@ function desktopEndpoint(request) {
       };
     case "sessions.list":
       return {
-        path: `/v1/desktop/sessions?limit=${request.limit ?? 100}`,
+        // Omitted when false, for the reason `sessions.search`'s own query
+        // states: the pre-flag request is what an older backend must keep
+        // seeing, and `false` is the route's default anyway.
+        path: `/v1/desktop/sessions?limit=${request.limit ?? 100}${request.include_archived ? "&include_archived=true" : ""}`,
         method: "GET"
       };
     case "sessions.search": {
@@ -1262,11 +1333,29 @@ function desktopEndpoint(request) {
         q: request.q,
         limit: String(request.limit ?? SESSION_SEARCH_DEFAULT_LIMIT)
       });
+      if (request.include_archived) query.set("include_archived", "true");
       return {
         path: `/v1/desktop/sessions/search?${query}`,
         method: "GET"
       };
     }
+    case "sessions.archive":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/archive`,
+        method: "POST",
+        // The desired state, never a toggle: see the op's own comment for why a
+        // retried toggle is the bug this shape exists to make impossible.
+        body: { archived: request.archived }
+      };
+    case "sessions.delete":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}`,
+        method: "DELETE",
+        // The user's own confirmation, echoed on the wire: the route requires
+        // it, so this op cannot be reached without a dialog having been
+        // answered (see the op's comment).
+        body: { confirmed: true }
+      };
     case "sessions.create":
       return {
         path: "/v1/desktop/sessions",
@@ -10346,7 +10435,8 @@ const CONSOLE_ERROR_CODES = [
   "secure_input_active",
   "console_unavailable",
   "invalid_grid",
-  "capture_unavailable"
+  "capture_unavailable",
+  "console_capture_full"
 ];
 const PROTO_VERSION = 1;
 const METHODS$1 = [
@@ -10553,6 +10643,375 @@ class ConsoleError extends BridgeCommandError {
     super(code, message, data);
   }
 }
+const DEFAULT_IDLE_MS = 3e4;
+const SETTLE_TIMEOUT_MS = 3e4;
+const MIN_CONTENT_DISTINCT_COLOURS = 8;
+const MIN_CONTENT_PIXELS = 32;
+const RETRY_DELAY_MS = 120;
+class ConsoleCaptureView {
+  constructor(options) {
+    this.options = options;
+  }
+  window = null;
+  busy = false;
+  reapTimer = null;
+  /** Whether a capture is in flight right now, for the refusal's own message. */
+  get inFlight() {
+    return this.busy;
+  }
+  /**
+   * Whether the view is on a reap timer. Public because it is the class's stated
+   * contract ("nothing lingers for a session that has stopped asking") and the only
+   * way to assert it from outside without waiting out the idle window: code review
+   * round 1's B2 was exactly a refusal that left no timer armed.
+   */
+  get reapArmed() {
+    return this.reapTimer !== null;
+  }
+  async capture(request) {
+    if (this.busy) {
+      throw new ConsoleError(
+        "console_capture_full",
+        "a console capture is already running; one capture view exists at a time",
+        { surface: request.surface }
+      );
+    }
+    this.busy = true;
+    try {
+      const window = await this.ensureWindow();
+      return await this.feed(window.webContents, request);
+    } finally {
+      this.busy = false;
+      this.scheduleReap();
+    }
+  }
+  /** Release the view now. Called on quit, and by the idle timer. */
+  dispose() {
+    if (this.reapTimer) {
+      clearTimeout(this.reapTimer);
+      this.reapTimer = null;
+    }
+    const window = this.window;
+    this.window = null;
+    this.measured = false;
+    if (window && !window.isDestroyed()) window.destroy();
+  }
+  /**
+   * Create the view if it is not up, and hand back its window.
+   *
+   * The size is a placeholder: the page measures its own cell and the window is
+   * resized to the grid before the bytes are fed, because the frame's determinism
+   * depends on the grid being the record's rather than on the window's default.
+   */
+  async ensureWindow() {
+    if (this.reapTimer) {
+      clearTimeout(this.reapTimer);
+      this.reapTimer = null;
+    }
+    if (this.window && !this.window.isDestroyed()) {
+      if (this.measured) return this.window;
+      return this.measure(this.window);
+    }
+    this.measured = false;
+    const window = new electron.BrowserWindow({
+      // `show: false` and `paintWhenInitiallyHidden` (Electron's default) is the
+      // measured-working pair: the page paints so there is a frame to capture,
+      // and nothing is ever presented, focused or raised - which is the whole
+      // requirement the design states for the capture view.
+      show: false,
+      width: 1e3,
+      height: 600,
+      webPreferences: {
+        preload: this.options.preload,
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: false,
+        // The reconstruction is unattended and single-shot: a throttled
+        // background renderer would make the settle wait a matter of luck.
+        backgroundThrottling: false
+      }
+    });
+    this.window = window;
+    window.webContents.on("console-message", (...args) => {
+      const event = args[0];
+      const level = event?.level ?? args[1];
+      const message = (typeof event?.message === "string" ? event.message : void 0) ?? (typeof args[2] === "string" ? args[2] : void 0) ?? "";
+      const severity = String(level ?? "info").toLowerCase();
+      if (severity !== "warning" && severity !== "error" && severity !== "2") {
+        return;
+      }
+      this.options.log(`[console] capture view: ${message}`);
+    });
+    await window.loadURL(this.options.url);
+    return this.measure(window);
+  }
+  /**
+   * THE MEASUREMENT HANDSHAKE, once per window rather than once per attempt.
+   *
+   * The page owns the cell metrics, because it owns the font: main has no way to
+   * measure a face, and the frame is a function of (bytes, grid, theme, font,
+   * renderer), so the grid's pixel size has to come from the same place the
+   * glyphs do. Cached for the life of the view - a second capture in the idle
+   * window pays neither the launch nor the measurement - which is why the cache is
+   * guarded by `measured` rather than by the window's existence.
+   */
+  async measure(window) {
+    const measured = await waitForCapture(
+      window.webContents,
+      "console-capture-measured",
+      () => window.webContents.send("console-capture-measure"),
+      this.options.settleTimeoutMs
+    );
+    this.cellWidth = numberOr(measured.cellWidth, 8);
+    this.cellHeight = numberOr(measured.cellHeight, 16);
+    this.measured = true;
+    return window;
+  }
+  /** Whether the live window has answered the measurement handshake. */
+  measured = false;
+  cellWidth = 8;
+  cellHeight = 16;
+  /**
+   * THE FEED'S IDENTITY, and it is what makes the frame a function of the record (Q-11).
+   *
+   * The capture page remounts the mirror on this number, which is the whole of the
+   * reconstruction's determinism: the page's terminal is built from a record, so a SECOND
+   * feed must start from a fresh terminal rather than write into the first one's. A number
+   * that identifies the ATTEMPT (`1`, then `2` on a retry) is not an identity across
+   * requests — it repeats — so the page never remounted and the new bytes were appended to
+   * the old grid. QA measured what that produced: a 1-line surface captured after an 8-line
+   * one came back as both (212 rows = 192 + 20), a repeat capture appended again (232), and
+   * three different surfaces — one of them with an empty record — returned BYTE-IDENTICAL
+   * frames. Main is the only authority for a surface (§3(a)), and this counter is how the
+   * mirror is told which one it is looking at.
+   */
+  feedSeq = 0;
+  /**
+   * Feed one surface's record, wait for the page to paint, and photograph it.
+   *
+   * Two attempts at most, and the SECOND attempt re-feeds the same bytes rather
+   * than capturing again: a stale first frame is a paint that had not landed, but a
+   * frame that is still blank after a re-feed is a real failure and is reported as
+   * one instead of being retried until it works.
+   */
+  async feed(contents, request) {
+    const window = this.window;
+    if (window && !window.isDestroyed()) {
+      window.setContentSize(
+        Math.max(1, Math.round(request.cols * this.cellWidth)),
+        Math.max(1, Math.round(request.rows * this.cellHeight))
+      );
+    }
+    let last = { bytes: 0, renderer: "unknown" };
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      this.feedSeq += 1;
+      const nonce = this.feedSeq;
+      const settled = await waitForCapture(
+        contents,
+        "console-capture-settled",
+        () => contents.send("console-capture-feed", {
+          nonce,
+          surface: request.surface,
+          cols: request.cols,
+          rows: request.rows,
+          theme: request.theme,
+          bytes_base64: Buffer.from(request.bytes).toString("base64")
+        }),
+        this.options.settleTimeoutMs
+      );
+      const renderer = stringOr(
+        settled.renderer,
+        "unknown"
+      );
+      if (renderer !== "dom") {
+        throw new ConsoleError(
+          "capture_unavailable",
+          `the capture view painted with the ${renderer} renderer; this path requires the DOM renderer`,
+          { rendered: "offscreen" }
+        );
+      }
+      const image2 = await contents.capturePage();
+      const png = image2.toPNG();
+      last = { bytes: png.length, renderer };
+      const recordIsEmpty = request.bytes.length === 0;
+      if (recordIsEmpty || hasTerminalContent(image2.toBitmap())) {
+        this.scheduleReap();
+        this.options.log(
+          `[console] captured surface ${request.surface} offscreen at ${request.cols}x${request.rows} (${renderer} renderer, ${png.length} B, attempt ${attempt})`
+        );
+        return { png, renderer, attempts: attempt };
+      }
+      this.options.log(
+        `[console] offscreen capture of ${request.surface} came back blank (${png.length} B, attempt ${attempt}); re-feeding the record`
+      );
+      await delay$1(RETRY_DELAY_MS);
+    }
+    throw new ConsoleError(
+      "capture_unavailable",
+      `the offscreen capture of this surface produced a blank frame twice (last ${last.bytes} B, renderer ${last.renderer})`,
+      { rendered: "offscreen" }
+    );
+  }
+  /** Reap the view after the idle window, so a session that has stopped capturing
+   * does not keep a renderer process alive for the life of the app. */
+  scheduleReap() {
+    if (this.reapTimer) clearTimeout(this.reapTimer);
+    this.reapTimer = setTimeout(() => {
+      this.reapTimer = null;
+      const window = this.window;
+      this.window = null;
+      if (window && !window.isDestroyed()) window.destroy();
+    }, this.options.idleMs ?? DEFAULT_IDLE_MS);
+  }
+}
+const waitForCapture = (contents, channel, onWaiting, timeoutMs = SETTLE_TIMEOUT_MS) => new Promise((resolve, reject) => {
+  const listener = (event, payload) => {
+    if (event.sender !== contents) return;
+    clearTimeout(timer);
+    electron.ipcMain.removeListener(channel, listener);
+    resolve(payload ?? {});
+  };
+  const timer = setTimeout(() => {
+    electron.ipcMain.removeListener(channel, listener);
+    reject(
+      new ConsoleError(
+        "capture_unavailable",
+        `the capture view did not report ${channel} within ${timeoutMs} ms`,
+        { rendered: "offscreen" }
+      )
+    );
+  }, timeoutMs);
+  electron.ipcMain.on(channel, listener);
+  onWaiting();
+});
+const hasTerminalContent = (bitmap) => {
+  if (bitmap.length < 8) return false;
+  const first = bitmap.subarray(0, 4);
+  const colours = /* @__PURE__ */ new Set();
+  let nonModal = 0;
+  for (let i = 0; i + 4 <= bitmap.length; i += 4) {
+    colours.add(
+      bitmap[i] << 24 | bitmap[i + 1] << 16 | bitmap[i + 2] << 8 | bitmap[i + 3]
+    );
+    if (bitmap[i] !== first[0] || bitmap[i + 1] !== first[1] || bitmap[i + 2] !== first[2] || bitmap[i + 3] !== first[3]) {
+      nonModal += 1;
+    }
+    if (colours.size >= MIN_CONTENT_DISTINCT_COLOURS && nonModal >= MIN_CONTENT_PIXELS) {
+      return true;
+    }
+  }
+  return false;
+};
+const numberOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+const stringOr = (value, fallback) => typeof value === "string" && value ? value : fallback;
+const delay$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const SAME_COMPLETION_MS = 3e3;
+function consoleCompletionHooks(deps) {
+  const now = deps.now ?? (() => Date.now());
+  const exits = /* @__PURE__ */ new Map();
+  const exitKey = (surface) => {
+    const listing = deps.host()?.state();
+    const row = listing?.surfaces?.find((entry) => entry.surface === surface);
+    const epoch = typeof row?.exit_epoch === "number" ? row.exit_epoch : void 0;
+    const count = epoch ?? (exits.get(surface) ?? 0) + 1;
+    exits.set(surface, count);
+    return `console:exit:${surface}:${count}`;
+  };
+  const lastBanner = /* @__PURE__ */ new Map();
+  const announce = (notice, kind) => {
+    const notifier = deps.notifier();
+    if (!notifier) return;
+    lastBanner.set(notice.surface, { at: now(), kind });
+    notifier.consoleCompletion(notice);
+  };
+  const describe2 = (surface) => {
+    const entry = deps.registry.find(surface);
+    if (!entry) return null;
+    return {
+      sessionId: entry.record.sessionId,
+      command: entry.record.command.trim() || surface
+    };
+  };
+  const displayed = (surface) => {
+    const state = deps.host()?.state();
+    return state?.displayed_surface === surface;
+  };
+  const completionFor = (surface, exitCode, key) => {
+    const described = describe2(surface);
+    if (!described) return null;
+    return {
+      sessionId: described.sessionId,
+      surface,
+      surfaceName: described.command,
+      exitCode,
+      displayed: displayed(surface),
+      key
+    };
+  };
+  return {
+    /*
+     * RUNG 2 OF THE LADDER (§12.1): a command finished inside a persistent shell,
+     * carried by the shell's own OSC 133 `D` mark.
+     *
+     * THE MARK IS ALSO WHAT THE BLIP RIDES, and the two are one signal rather
+     * than two: the renderer learns about it by refetching the listing the host
+     * has already updated (`last_mark`), and the banner is raised here only when
+     * the user is not looking at the surface at all. The blip is deliberately NOT
+     * computed here — a mark that the pane cleared when the user looked at it must
+     * not be re-marked by a later fetch, and only the renderer knows when the
+     * user was looking.
+     *
+     * WHAT THIS RUNG CANNOT SEE is named in the design and repeated so it is not
+     * mistaken for a bug: it needs the shell to emit prompt marks (the app ships a
+     * snippet the user may source, and never writes to their dotfiles), the parse
+     * is a byte scan rather than an emulator feature, and a program can spoof the
+     * sequence — whose worst case is one spurious banner.
+     */
+    onMark: (surface, mark) => {
+      if (mark.kind !== "command-finished") return;
+      const notice = completionFor(
+        surface,
+        mark.exitCode,
+        // The mark's own offset in the log is what makes two marks
+        // distinguishable: a shell that runs the same command twice emits two
+        // `D` marks with the same status, at two offsets.
+        `console:mark:${surface}:${mark.offset}`
+      );
+      if (notice) announce(notice, "mark");
+    },
+    /*
+     * RUNG 1: the surface's process exited — the one signal that is always
+     * available, exactly once per surface, carrying the exit code (§12.1).
+     *
+     * THE KEY IS `(surface, exit_epoch)`, the design's own pair, read from the
+     * host's listing (see `exitKey`). It is what the host's own comment expects the
+     * notifier to dedupe on, it survives a relaunch because the retention layer
+     * persists it, and it is what makes two exits two completions even with the
+     * same code.
+     *
+     * A MARK-AND-THEN-EXIT IS ONE COMPLETION. A shell that exits from a prompt
+     * emits its `D` mark and then the process exit, and both are the same thing
+     * happening once; a second banner for it would be the "notify twice" the
+     * claim discipline exists to prevent. The window is small and named rather
+     * than a guess about content.
+     */
+    onExit: ({
+      surface,
+      exitCode
+    }) => {
+      const key = exitKey(surface);
+      const previous = lastBanner.get(surface);
+      if (previous !== void 0 && previous.kind === "mark" && now() - previous.at < SAME_COMPLETION_MS) {
+        deps.log(
+          `[console] surface ${surface} exited ${exitCode} right after its own completion mark; one banner, not two`
+        );
+        return;
+      }
+      const notice = completionFor(surface, exitCode, key);
+      if (notice) announce(notice, "exit");
+    }
+  };
+}
 const RETAIN_BYTES = 4 * 1024 * 1024;
 const CEILING_BYTES = 16 * 1024 * 1024;
 class ByteLog {
@@ -11055,6 +11514,7 @@ class ConsoleRegistry {
       live: true,
       retain: input.retain,
       secure: false,
+      lastActor: null,
       sizing: input.sizing
     };
     const entry = { record, runtime: null };
@@ -11167,9 +11627,9 @@ const MAX_ROWS = 200;
 const SCROLLBACK_LINES = 5e3;
 const MAX_INPUT_BYTES = 1 << 18;
 const OUTPUT_COALESCE_MS = 16;
+const LIVE_PENDING_MAX_BYTES = 1 << 20;
 const PERSIST_FLUSH_MS = 250;
 const PERSIST_FLUSH_BYTES = 256 * 1024;
-const MIN_FRAME_BYTES = 2e3;
 const FRAME_RETRY_DELAY_MS = 120;
 const CLOSE_GRACE_MS = 1500;
 const SURFACE_ENV_MARKER = "LOCAL_OPERATOR_CONSOLE_SURFACE";
@@ -11264,6 +11724,8 @@ class ConsoleHost {
       scanner: new Osc133Scanner(),
       subscribers: /* @__PURE__ */ new Set(),
       pending: [],
+      pendingBytes: 0,
+      droppedLiveBytes: 0,
       pendingTimer: null,
       persistTimer: null,
       seq: 0,
@@ -11372,6 +11834,8 @@ class ConsoleHost {
       scanner: new Osc133Scanner(),
       subscribers: /* @__PURE__ */ new Set(),
       pending: [],
+      pendingBytes: 0,
+      droppedLiveBytes: 0,
       pendingTimer: null,
       persistTimer: null,
       seq: 0,
@@ -11409,9 +11873,28 @@ class ConsoleHost {
       exit_code: record.exitCode,
       last_activity: record.lastActivity,
       live: record.live,
-      agent_owned: record.origin === "agent"
+      agent_owned: record.origin === "agent",
+      // The co-pilot cell (§13.4): who touched the pty last, which `origin`
+      // deliberately does not answer.
+      last_actor: record.lastActor
     };
   }
+  /**
+   * Record who drove the pty, and push a change ONLY on a transition.
+   *
+   * The push is what the pane's listing refetches on, and a push per keystroke
+   * would be one IPC frame for every character a user types. The mark only has
+   * two values, so a comparison is the whole of the coalescing it needs.
+   *
+   * A REFUSED OR MISSING ACTOR IS THE AGENT PATH, which is the default rather
+   * than a guess: every caller inside main other than the renderer's own IPC is
+   * the RPC dispatch, and the renderer's path names `"user"` explicitly.
+   */
+  markActor(entry, actor) {
+    if (entry.record.lastActor === actor) return;
+    entry.record.lastActor = actor;
+    this.options.onChanged?.();
+  }
   /** `console_status`. */
   status(surface) {
     const entry = this.registry.require(surface);
@@ -11428,6 +11911,14 @@ class ConsoleHost {
       rows: entry.record.rows,
       live: entry.record.live,
       truncated: runtime?.log.truncated ?? false,
+      // The LIVE VIEW's own loss, which is not the log's `truncated`: the ring
+      // drops history it was told to bound, this drops frames a subscriber could
+      // not take. Two numbers because they answer two different questions, and a
+      // caller reasoning about a pane's fidelity needs this one.
+      //
+      // MONOTONIC for the life of the surface: it accumulates and does not reset,
+      // so two readings compare and neither means "how far behind the pane is now".
+      dropped_live_bytes: runtime?.droppedLiveBytes ?? 0,
       modes: grid?.modes ?? null,
       cursor: grid?.cursor ?? null,
       last_activity: entry.record.lastActivity,
@@ -11468,19 +11959,16 @@ class ConsoleHost {
   }
   /**
    * `console_screenshot`: the app's own window, cropped to the pane's reported
-   * rect, photographed with `capturePage` (design 13.2's first row).
-   *
-   * WHAT THIS DOES NOT DO, and it is the design's own first cut item (§17.3): the
-   * offscreen capture view — a hidden renderer replaying the record — is PR B's
-   * (§17.1), so a surface with no displayed pane is refused with
-   * `capture_unavailable` rather than answered with a frame that would not be of
-   * that surface. The `rendered` field is kept so the gap is visible instead of
-   * implied.
+   * rect, photographed with `capturePage` (design 13.2's first row); or, when no
+   * pane is displaying the surface, the capture view's reconstruction from the
+   * record (the second and third rows), which is what makes the `rendered` field a
+   * distinction rather than a label nothing produces.
    *
    * The assert-and-retry is the spike's measured trap and not a hopeful
    * `setTimeout`: on a hidden window the FIRST `capturePage` came back blank
    * (9,866 B against 27,869 B for the settled frame), and a headless rig — which
-   * is what every capture in this repo runs in — is exactly that case.
+   * is what every capture in this repo runs in — is exactly that case. The
+   * offscreen path repeats the same discipline in its own module.
    */
   async screenshot(surface) {
     const entry = this.registry.require(surface);
@@ -11488,11 +11976,34 @@ class ConsoleHost {
     this.refuseWhenSecure(entry);
     const report = runtime.rect;
     if (this.displayed !== surface || !report || !report.visible) {
-      throw new ConsoleError(
-        "capture_unavailable",
-        "no pane is displaying this surface, and this app version cannot reconstruct a frame offscreen",
-        { rendered: null }
-      );
+      const capture = this.options.captureOffscreen;
+      if (!capture) {
+        throw new ConsoleError(
+          "capture_unavailable",
+          "no pane is displaying this surface, and this host has no capture view to reconstruct a frame with",
+          { rendered: null }
+        );
+      }
+      const grid2 = runtime.emulator.grid;
+      const frame = await capture({
+        surface,
+        cols: grid2.cols,
+        rows: grid2.rows,
+        theme: runtime.theme,
+        bytes: runtime.log.read(0).bytes
+      });
+      return {
+        image_base64: frame.png.toString("base64"),
+        cols: grid2.cols,
+        rows: grid2.rows,
+        rendered: "offscreen",
+        theme: runtime.theme,
+        live: entry.record.live,
+        // Which renderer painted the reconstruction, reported rather than
+        // assumed: the DOM pin is what makes an offscreen frame possible at all.
+        renderer: frame.renderer,
+        attempts: frame.attempts
+      };
     }
     const window = this.options.window();
     if (!window || window.isDestroyed()) {
@@ -11517,11 +12028,44 @@ class ConsoleHost {
       live: entry.record.live
     };
   }
+  /**
+   * A displayed frame, retried once, and REFUSED when it has no content twice (Q-2).
+   *
+   * There is no byte floor any more, here or on the offscreen path, and the two
+   * findings are why: the floor was not a guard (QA round 1's Q-2 — a blank 1600x800
+   * capture is a few kilobytes of one colour, so the cell certifying "a screenshot is
+   * the app's own window, cropped to the pane's rect" was green on a uniform field
+   * while the offscreen frame from the same run had 252 colours) AND it refused real
+   * captures from the other side (QA round 2's Q-7 — a live console that had printed
+   * less than a screenful was answered as blank). `hasTerminalContent` asks the
+   * question both findings reduce to, once, for both paths.
+   *
+   * A FRAME WITH NO CONTENT IS REFUSED RATHER THAN RETURNED, which is the design's own
+   * answer for the offscreen path (§13.2's `capture_unavailable`): one flat field is
+   * not a picture of a terminal, and handing it back would be the class of false
+   * evidence this contract exists to avoid. A real pane is never flat — the DOM
+   * renderer paints antialiased text and a cursor — and the empty-terminal case is the
+   * offscreen path's problem too, so this is not a new ceiling.
+   */
   async captureWithRetry(window, rect) {
-    const first = framePng(await window.webContents.capturePage(rect));
-    if (first.length >= MIN_FRAME_BYTES) return first;
-    await delay(FRAME_RETRY_DELAY_MS);
-    return framePng(await window.webContents.capturePage(rect));
+    let bytes = 0;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      const image2 = await window.webContents.capturePage(rect);
+      const png = framePng(image2);
+      bytes = png.length;
+      if (hasTerminalContent(image2.toBitmap())) {
+        return png;
+      }
+      this.options.log(
+        `[console] displayed capture came back blank (${png.length} B, attempt ${attempt})`
+      );
+      if (attempt === 1) await delay(FRAME_RETRY_DELAY_MS);
+    }
+    throw new ConsoleError(
+      "capture_unavailable",
+      `the displayed capture of this surface produced a blank frame twice (last ${bytes} B)`,
+      { rendered: "displayed" }
+    );
   }
   /**
    * `console_input`: bytes into the pty.
@@ -11530,7 +12074,7 @@ class ConsoleHost {
    * record's LIVE mode says so** (§10.5), which is why this is a main-side
    * decision: the mode is read at the moment of the call, from the record.
    */
-  async input(surface, payload) {
+  async input(surface, payload, actor = "agent") {
     const entry = this.registry.require(surface);
     const runtime = this.requireRuntime(entry);
     this.requireRunning(entry);
@@ -11542,13 +12086,14 @@ class ConsoleHost {
         { accepted: 0, limit: MAX_INPUT_BYTES }
       );
     }
+    this.markActor(entry, actor);
     const bracketed = payload.paste === true && runtime.emulator.grid.modes.bracketedPaste;
     const bytes = bracketed ? wrapBracketedPaste(raw) : raw;
     this.writeToPty(entry, runtime, bytes);
     return { accepted: true, bytes: bytes.length };
   }
   /** `console_keys`: named keys through the one encoder (§10.5). */
-  async keys(surface, names) {
+  async keys(surface, names, actor = "agent") {
     const entry = this.registry.require(surface);
     const runtime = this.requireRuntime(entry);
     this.requireRunning(entry);
@@ -11567,6 +12112,7 @@ class ConsoleHost {
         { accepted: [...NAMED_KEYS], key: unknown }
       );
     }
+    this.markActor(entry, actor);
     const sequences = [];
     for (const bytes of encoded) {
       if (!bytes) continue;
@@ -11772,11 +12318,24 @@ class ConsoleHost {
   broadcast(entry, runtime, bytes) {
     if (runtime.subscribers.size === 0) return;
     runtime.pending.push(bytes);
+    runtime.pendingBytes += bytes.length;
+    while (runtime.pendingBytes > LIVE_PENDING_MAX_BYTES && runtime.pending.length > 1) {
+      const oldest = runtime.pending.shift();
+      if (!oldest) break;
+      runtime.pendingBytes -= oldest.length;
+      runtime.droppedLiveBytes += oldest.length;
+      if (runtime.droppedLiveBytes === oldest.length) {
+        this.options.log(
+          `[console] surface ${redactSurface(entry.record.surface)} is behind by more than ${LIVE_PENDING_MAX_BYTES} B; the live view drops its oldest frames (the record keeps every byte)`
+        );
+      }
+    }
     if (runtime.pendingTimer) return;
     runtime.pendingTimer = setTimeout(() => {
       runtime.pendingTimer = null;
       const pending = runtime.pending;
       runtime.pending = [];
+      runtime.pendingBytes = 0;
       if (pending.length === 0) return;
       const joined = concat(pending);
       runtime.seq += 1;
@@ -11811,6 +12370,11 @@ class ConsoleHost {
       `[console] surface ${redactSurface(surface)} exited ${exitCode}`
     );
     this.options.onChanged?.();
+    this.options.onExit?.({
+      surface,
+      sessionId: entry.record.sessionId,
+      exitCode
+    });
   }
   /** Apply a grid change: clamp, compare, and only then touch the record and the
    * pty — so one clamp-crossing is one `TIOCSWINSZ` and one `SIGWINCH` (§8.2). */
@@ -12204,11 +12768,15 @@ async function dispatchConsole(host, method, params) {
           { surface }
         );
       }
-      return host.input(surface, {
-        text,
-        bytes,
-        paste: optionalBoolean(params.paste, "paste")
-      });
+      return host.input(
+        surface,
+        {
+          text,
+          bytes,
+          paste: optionalBoolean(params.paste, "paste")
+        },
+        "agent"
+      );
     }
     case "console_keys": {
       const surface = requiredSurface(params.surface);
@@ -12220,7 +12788,7 @@ async function dispatchConsole(host, method, params) {
           {}
         );
       }
-      return host.keys(surface, keys);
+      return host.keys(surface, keys, "agent");
     }
     case "console_resize": {
       const surface = requiredSurface(params.surface);
@@ -12630,19 +13198,31 @@ const CONSOLE_IPC_CHANNELS = [
   "console-unsubscribe"
 ];
 function registerConsoleIpc(options) {
-  function authorize(event) {
+  function assertTrustedSender(event) {
     const owner = options.window();
     if (!owner || owner.isDestroyed() || event.sender !== owner.webContents || event.senderFrame !== owner.webContents.mainFrame || !trustedDesktopFrame(event.senderFrame.url, options.expectedUrl)) {
       throw new Error("This window cannot use the console.");
     }
+  }
+  function authorize(event) {
+    assertTrustedSender(event);
     const host = options.host();
     if (!host) throw new Error("The console is not running.");
     return host;
   }
-  electron.ipcMain.handle(
-    "console-state",
-    (event, sessionId2) => authorize(event).state(optionalString(sessionId2, "sessionId"))
-  );
+  electron.ipcMain.handle("console-state", (event, sessionId2) => {
+    assertTrustedSender(event);
+    const host = options.host();
+    if (!host) {
+      return {
+        available: false,
+        surfaces: [],
+        reason: options.unavailable?.reason ?? "unavailable",
+        detail: options.unavailable?.detail ?? null
+      };
+    }
+    return host.state(optionalString(sessionId2, "sessionId"));
+  });
   electron.ipcMain.handle("console-create-surface", (event, request) => {
     const host = authorize(event);
     const input = request && typeof request === "object" ? request : {};
@@ -12684,7 +13264,7 @@ function registerConsoleIpc(options) {
       if (typeof text !== "string") {
         throw new Error("Console input must be a string.");
       }
-      return host.input(stringOrThrow(surface, "surface"), { text });
+      return host.input(stringOrThrow(surface, "surface"), { text }, "user");
     }
   );
   electron.ipcMain.handle(
@@ -12694,7 +13274,11 @@ function registerConsoleIpc(options) {
       if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
         throw new Error("Console keys must be a list of names.");
       }
-      return host.keys(stringOrThrow(surface, "surface"), keys);
+      return host.keys(
+        stringOrThrow(surface, "surface"),
+        keys,
+        "user"
+      );
     }
   );
   electron.ipcMain.handle(
@@ -12971,27 +13555,36 @@ async function startConsoleHost(options) {
     );
   }
   const { log } = options;
+  const registerRefusal = (reason, detail) => {
+    registerConsoleIpc({
+      window: () => options.window,
+      expectedUrl: options.expectedUrl,
+      host: () => null,
+      unavailable: { reason, detail },
+      log
+    });
+  };
   if (!consoleHostEnabled()) {
     log(
       `[console] disabled by ${CONSOLE_HOST_ENV}; no surfaces will be created and the record carries console: false`
     );
+    registerRefusal("disabled", `${CONSOLE_HOST_ENV} is off`);
     return {
       ok: false,
       reason: "disabled",
       detail: `${CONSOLE_HOST_ENV} is off`,
-      stop: async () => {
-      }
+      stop: async () => unregisterConsoleIpc()
     };
   }
   const load = loadNodePty();
   if (!load.ok) {
     log(`[console] node-pty is unavailable: ${load.reason}`);
+    registerRefusal("pty_unavailable", load.reason);
     return {
       ok: false,
       reason: "pty_unavailable",
       detail: load.reason,
-      stop: async () => {
-      }
+      stop: async () => unregisterConsoleIpc()
     };
   }
   if (load.helper.healed) {
@@ -13004,19 +13597,43 @@ async function startConsoleHost(options) {
     path$1.join(configDir, "run", "ui-console", "history")
   );
   const registry = new ConsoleRegistry();
+  let hostRef = null;
+  const completion = consoleCompletionHooks({
+    host: () => hostRef,
+    registry,
+    notifier: () => options.notifier ?? null,
+    log,
+    now: options.now
+  });
+  const capture = options.consoleCaptureUrl && options.preloadPath ? new ConsoleCaptureView({
+    url: options.consoleCaptureUrl,
+    preload: options.preloadPath,
+    log
+  }) : null;
   const host = new ConsoleHost(registry, {
     window: () => options.window,
     log,
     history,
     now: options.now,
+    captureOffscreen: capture ? (request) => capture.capture(request) : void 0,
     spawn: options.spawn ?? ((spawnOptions) => spawnPty(load.module, spawnOptions, (report) => {
       log(
         `[console] restored the exec bit on ${report.path ?? "spawn-helper"}`
       );
     })),
+    /*
+     * ONE PUSHER, and it is A's. `broadcastConsoleState` was already the app's
+     * single "the projection moved" signal when this branch arrived; the
+     * completion seam below therefore does NOT push a second copy of the same
+     * frame. It only raises a banner, which is the half a push cannot express —
+     * and the host calls `onChanged` for a mark and an exit too, so the renderer
+     * still refetches on both (see `ConsoleHostOptions.onExit`).
+     */
     onChanged: () => {
       broadcastConsoleState(options.window);
     },
+    onMark: completion.onMark,
+    onExit: completion.onExit,
     onReveal: (request) => {
       const window = options.window;
       if (window.isDestroyed()) return;
@@ -13044,6 +13661,7 @@ async function startConsoleHost(options) {
       `[console] history GC removed ${collected.removedSurfaces} surface(s) from ${collected.removedSessions.length} session(s) older than the window`
     );
   }
+  hostRef = host;
   registerConsoleIpc({
     window: () => options.window,
     expectedUrl: options.expectedUrl,
@@ -13066,6 +13684,7 @@ async function startConsoleHost(options) {
     },
     stop: async () => {
       unregisterConsoleIpc();
+      capture?.dispose();
       host.dispose();
       log("[console] host stopped");
     }
@@ -20037,6 +20656,18 @@ async function startBrowserHost(options) {
     window: options.window,
     expectedUrl: options.expectedUrl,
     appVersion: options.appVersion,
+    notifier: options.notifier,
+    /*
+     * The capture view's document and preload, forwarded rather than re-derived:
+     * only the app knows where its own bundle lives, and a console host that
+     * guessed would answer a screenshot with a blank frame rather than with its
+     * own typed refusal. WITHOUT THESE TWO the host builds no capture view at all,
+     * which the live proof rig caught as `capture_unavailable` on a surface with
+     * no displayed pane — the exact shape of a seam that is wired in tests and
+     * forgotten in the one call site that matters.
+     */
+    consoleCaptureUrl: options.consoleCaptureUrl,
+    preloadPath: options.preloadPath,
     log
   });
   const sessionKey = mintSessionKey();
@@ -20313,6 +20944,9 @@ function createSessionCookieQuitHold(deps) {
     return true;
   };
 }
+const INDEX_DOCUMENT_SUFFIX = /\/?index\.html(\?.*)?$/;
+const CAPTURE_DOCUMENT = "console-capture.html";
+const consoleCaptureUrlFor = (rendererUrl) => INDEX_DOCUMENT_SUFFIX.test(rendererUrl) ? rendererUrl.replace(INDEX_DOCUMENT_SUFFIX, `/${CAPTURE_DOCUMENT}`) : `${rendererUrl.replace(/\/$/, "")}/${CAPTURE_DOCUMENT}`;
 const OPERATION_ID = /^[a-zA-Z0-9_-]{1,128}$/;
 const FOREGROUND_RECEIPT_OPS = /* @__PURE__ */ new Set([
   "sessions.seen",
@@ -21429,6 +22063,68 @@ class DesktopNotifier {
       gateBody(kind, title.trim() || fallback, detail)
     );
   }
+  /**
+   * Raise the banner for a console surface's completion (design 12.3, R14).
+   *
+   * THE ONE PUBLIC ENTRY THIS FEATURE ADDS, routing into the same `show(...)`
+   * choke point every other banner uses rather than constructing its own
+   * `Notification`. A second raiser would duplicate the TTL dedupe map, the window
+   * state, the raise policy and the click path - four things this feature has no
+   * opinion about - so it borrows all four and states only its own two facts: what
+   * it says, and which surface a click should select.
+   *
+   * THE ELIGIBILITY LADDER (§12.3), in order, mirroring the backend's so the two
+   * cannot disagree about the same user:
+   *
+   *  1. this run may present nothing (`windowRaise === "never"`, i.e. `headless`)
+   *     -> nothing. The same single gate `observe` uses, ahead of any claim, so a
+   *     banner that will not be shown never burns a completion claim.
+   *  2. the console pane is displayed ON THIS SURFACE and the window is focused ->
+   *     no banner. The user is looking at the thing the banner would announce, and
+   *     the in-app blip is already the whole signal there.
+   *  3. otherwise -> the banner.
+   *
+   * `displayed` arrives from the console host rather than from the renderer,
+   * because that is the half of the question this process actually owns (the
+   * renderer reports its own focus through the presence heartbeat, which is a
+   * session-level fact and not a surface-level one).
+   *
+   * ONE BANNER PER COMPLETION, claimed before delivery (§12.3). The key is the
+   * caller's, minted from the completion's own identity - see
+   * `console/completion.ts` for what it is built from and why the design's
+   * `exit_epoch` is not readable here.
+   */
+  consoleCompletion(notice) {
+    if (!this.canNotify) return;
+    if (this.windowRaise === "never") return;
+    if (notice.displayed && this.windowFocused()) return;
+    if (!this.claim(notice.key)) return;
+    this.show(
+      notice.sessionId,
+      notice.surfaceName,
+      "",
+      notice.exitCode === null ? "Console finished" : `Console exited with code ${notice.exitCode}`,
+      false,
+      false,
+      notice.surface
+    );
+  }
+  /**
+   * Whether the app's own window is on screen AND focused.
+   *
+   * The console's suppression rule reads this directly rather than through the
+   * renderer's reported presence, and the difference is the question being asked:
+   * presence answers "which conversation does this app have on screen", which is
+   * session-level, while this one needs to know whether the WINDOW the user is in
+   * is the one displaying the surface. A window that is visible but behind another
+   * app is not a user looking at it.
+   */
+  windowFocused() {
+    const target2 = this.window();
+    return Boolean(
+      target2 && !target2.isDestroyed() && target2.isVisible() && target2.isFocused()
+    );
+  }
   /**
    * Legacy completion toast: canned copy, reached only against a backend that
    * does not advertise `notification_contract`. Keyed on `session:epoch:seq`
@@ -21492,7 +22188,7 @@ class DesktopNotifier {
    * still re-words nothing (design 8.4). Gates pass `status = ""` and are
    * unaffected either way.
    */
-  show(sessionId2, title, status2, body, isSnippet = false, isFailure = false) {
+  show(sessionId2, title, status2, body, isSnippet = false, isFailure = false, surface = null) {
     const lead = (isSnippet || isFailure) && status2 ? `${status2} — ` : "";
     const notification = new electron.Notification({
       title,
@@ -21505,7 +22201,10 @@ class DesktopNotifier {
         this.host.reopen(sessionId2);
         return;
       }
-      target2.webContents.send("desktop-open-conversation", { sessionId: sessionId2 });
+      target2.webContents.send("desktop-open-conversation", {
+        sessionId: sessionId2,
+        ...surface ? { surface } : {}
+      });
       raiseWindow(target2, this.windowRaise, {
         trigger: "banner-click",
         report: this.raiseReport
@@ -28861,6 +29560,7 @@ electron.app.whenReady().then(async () => {
     }
   });
   const rendererUrl = process.env.ELECTRON_RENDERER_URL || node_url.pathToFileURL(path$1.join(__dirname, "../renderer/index.html")).href;
+  const consoleCaptureUrl = consoleCaptureUrlFor(rendererUrl);
   backendService.observeDesktopFeed(
     (frame) => {
       if (frame.type === "notification") {
@@ -29422,6 +30122,16 @@ electron.app.whenReady().then(async () => {
         // the screen, and re-deciding it there would be a second policy beside
         // `window-mode.ts`.
         windowShow: windowLaunch.show,
+        // The console's completion banner is raised through this app's ONE
+        // notifier (design 12.3: a second raiser would duplicate the TTL dedupe,
+        // the window state, the raise policy and the click path). It is still the
+        // notifier that decides whether a banner is delivered: this forwards it.
+        notifier: desktopNotifier,
+        // The console's offscreen capture view (design 13.2/13.3): its own
+        // document, and the preload every renderer in this app gets, which is what
+        // lets main feed the reconstruction to it.
+        consoleCaptureUrl,
+        preloadPath: path$1.join(__dirname, "../preload/index.js"),
         log: (message) => logger.info(message, LogFileType.BACKEND)
       });
     } catch (error) {