hop2 0.11.0 → 0.11.2

package/hay/apps/server/src/rooms.ts

@@ -18,48 +18,108 @@ export type SocketAdapter = {
 export type ClientInfo = {
   id: string;
   name: string;
+  // "local-cli" = hop CLI attach; "monitor" = read-only live tile (session
+  // switcher wall): excluded from presence and client counts, and given a
+  // small snapshot so a wall of tiles doesn't pull megabytes per open.
   source?: string;
   colorIndex: number;
   cols: number;
   rows: number;
+  // Optional per-connection cap for the join snapshot (clamped to the
+  // room-level bound). Monitors request ~64KB.
+  replayBytes?: number;
+  // False = skip the equal-size attach "wiggle" (the −1/+1 column repaint
+  // nudge). Wall tiles decline it: they arrive already showing the current
+  // grid (the daemon's headless screen, complete — not a raw byte tail), so
+  // the nudge's two SIGWINCHes only produce a visible reflow of the running
+  // app at the exact moment the tile goes live — the "twitch".
+  nudge?: boolean;
 };
 
 export type RoomCreateOptions = {
   cwd: string;
   env?: Record<string, string>;
   shell?: string;
+  // Raw terminal output to pre-load into the room's buffer before the PTY
+  // starts producing data. Used by `hop restore` to replay a plain-shell
+  // session's last screen (so reopening it picks up where it left off) ahead of
+  // the fresh shell's first prompt. Clamped to the buffer cap like live output.
+  seedOutput?: string;
+  // Launch the room ON this command (passed to the shell as argv) instead of
+  // typing it in afterwards — see PtyFactoryOptions.command.
+  command?: string;
 };
 
 export type RoomSummary = {
   id: string;
   cwd: string;
   liveCwd: string;
+  foregroundProcess: string;
+  lastActivityAt: number;
+  bellSeq: number;
+  lastBellAt: number;
   clientCount: number;
   localCliCount: number;
 };
 
-// Raw output retained for reattach snapshots. ~2MB of raw stream reconstructs
-// roughly a full client scrollback (2000-5000 lines) of plain output; TUI
-// streams are escape-dense and reconstruct less. Override with
+// Raw output retained for reattach snapshots. ~20MB of raw stream reconstructs
+// roughly a full client scrollback (tens of thousands of lines) of plain
+// output; TUI streams are escape-dense and reconstruct less. This is the whole
+// buffer replayed (and parsed by the client) on reattach, so very large values
+// trade memory + reattach-parse time for deeper restored history. Override with
 // HAY_SNAPSHOT_BUFFER_BYTES (bytes of raw stream kept per room).
 const MAX_BUFFER_SIZE = (() => {
   const env = Number(process.env.HAY_SNAPSHOT_BUFFER_BYTES);
-  return Number.isFinite(env) && env > 0 ? env : 2_000_000;
+  return Number.isFinite(env) && env > 0 ? env : 20_000_000;
 })();
 // Keep rooms alive indefinitely; only explicit kill/remove should end a session.
 const CLEANUP_DELAY_MS = 0;
+// Join-time replay bound: the room keeps up to MAX_BUFFER_SIZE of history,
+// but replaying tens of MB through the client's parser on every open/switch
+// is what made sessions feel slow to load (a phone on a tunnel downloads and
+// parses all of it before first paint). Send a bounded tail instead; the cut
+// avoids starting mid-line so a partial escape sequence can't corrupt the
+// replay. Alt-screen apps redraw fully, and mode flags (alternateScreen,
+// cursorHidden, keyboardEnhanced) travel separately, so a tail is safe.
+const SNAPSHOT_REPLAY_BYTES = (() => {
+  const env = Number(process.env.HAY_SNAPSHOT_REPLAY_BYTES);
+  return Number.isFinite(env) && env > 0 ? env : 1_500_000;
+})();
+
+const boundSnapshotReplay = (buffer: string): string => {
+  if (buffer.length <= SNAPSHOT_REPLAY_BYTES) return buffer;
+  let tail = buffer.slice(buffer.length - SNAPSHOT_REPLAY_BYTES);
+  const nl = tail.indexOf("\n");
+  if (nl !== -1 && nl < 8192) {
+    tail = tail.slice(nl + 1);
+  }
+  return tail;
+};
+
+// Autofit-on-attach: a resize may claim the shared size when every OTHER
+// client has been input-idle at least this long. Someone actively typing keeps
+// the size they set; a viewer opening the session after everyone went idle
+// takes it over immediately instead of waiting to type first.
+const RESIZE_CLAIM_IDLE_MS = (() => {
+  const env = Number(process.env.HAY_RESIZE_CLAIM_IDLE_MS);
+  return Number.isFinite(env) && env >= 0 ? env : 60_000;
+})();
+// A claim:"attach" resize (a fresh client's first autofit) is deliberate:
+// someone just opened the session there. It takes the shared size unless a
+// peer typed within this window — only an actively-typing peer holds it.
+// 2.5s (was 5s): an actively typing peer keeps refreshing its own window, so
+// this only decides how long a PAUSED typist blocks a deliberate new attach —
+// measured 5s made wall-tile focus feel stuck (converged at ~5s through the
+// tunnel; ~3s with this).
+const ATTACH_CLAIM_IDLE_MS = (() => {
+  const env = Number(process.env.HAY_ATTACH_CLAIM_IDLE_MS);
+  return Number.isFinite(env) && env >= 0 ? env : 2_500;
+})();
 const CONTROL_SEQUENCE_TAIL = 32;
 const DEBUG_STATE = process.env.HAY_DEBUG === "1";
 
 const now = () => Date.now();
 
-const clampBuffer = (value: string) => {
-  if (value.length <= MAX_BUFFER_SIZE) {
-    return value;
-  }
-  return value.slice(value.length - MAX_BUFFER_SIZE);
-};
-
 // Build a useful error for a payload that failed schema validation: name the
 // message type and the offending field instead of a bare "Invalid message".
 const describeInvalidMessage = (payload: string): string => {
@@ -124,14 +184,48 @@ export class Room extends EventEmitter {
   private pty: IPty;
   private readonly initialCwd: string;
   private liveCwd: string;
+  private foregroundProcess = "";
+  private lastActivityAt = now(); // ms of the most recent PTY output
+  // Terminal bells (BEL outside escape sequences) rung by the app — agents and
+  // long jobs ring one to ask for attention. Monotonic counter + timestamp so
+  // clients can diff against a last-seen value; never reset for a room's life.
+  private bellSeq = 0;
+  private lastBellAt = 0;
+  // Whether the previous output chunk ended inside an unterminated OSC (whose
+  // BEL terminator must not count as a bell) — see trackBells.
+  private inOscForBells = false;
+  private bellEscCarry = false;
   private clients = new Map<string, ClientState>();
   private collabMode = true;
   private controllerId: string | null = null;
   private activeClientId: string | null = null;
   private activeCols: number;
   private activeRows: number;
-  private outputBuffer = "";
+  // Retained raw output as a chunk ring: append is O(1) and trimming drops
+  // whole chunks from the head. NEVER joined in full on the hot path — a flat
+  // string here meant every chunk past the 20MB cap re-copied the entire
+  // buffer (≈3ms of blocked event loop per 2KB chunk, measured), which froze
+  // the host for minutes under a busy fleet and got it killed as unresponsive.
+  private outputChunks: string[] = [];
+  private outputBytes = 0;
+  // Absolute stream offset (UTF-16 units) of the FIRST retained char — i.e.
+  // how much has been trimmed off the head over the room's lifetime. Lets
+  // getOutputSince hand out stable cursors into an ever-trimming ring.
+  private outputStart = 0;
+  // Last viewer's terminal colors (6-hex, no '#'), used to answer OSC 10/11
+  // while headless. Defaults to the web client's dark surface.
+  private clientBg = "0d1117";
+  private clientFg = "e6edf3";
   private alternateScreen = false;
+  // Enhanced keyboard reporting requested by the remote app (kitty keyboard protocol
+  // or xterm modifyOtherKeys). Tracked like alternateScreen so a reattaching client
+  // can restore it on its real terminal (see snapshot below).
+  private keyboardEnhanced = false;
+  // Mouse tracking requested by the remote app (any of ?1000/1002/1003) and
+  // whether it asked for SGR encoding (?1006). Snapshotted so a reattaching
+  // client can scroll the app with wheel events instead of Page keys.
+  private mouseReporting = false;
+  private mouseSgr = false;
   private cursorHidden = false;
   private controlSequenceTail = "";
   private oscBuffer = "";
@@ -151,15 +245,29 @@ export class Room extends EventEmitter {
       cols: initialSize.cols,
       rows: initialSize.rows,
       cwd: options.cwd,
-      env: options.env,
-      shell: options.shell
+      // Tag every session's environment with its room id so a Claude SessionStart
+      // hook can map a running claude conversation back to this hop session (used
+      // by `hop restore` to resume the exact conversation per session).
+      env: { ...(options.env || {}), HOP_SESSION: id },
+      shell: options.shell,
+      command: options.command
     });
     this.activeCols = initialSize.cols;
     this.activeRows = initialSize.rows;
 
+    // Restore replay: pre-load the previous session's tail output so the first
+    // client to attach sees the restored screen (via the snapshot) before the
+    // fresh shell repaints. This is raw bytes that already happened, so we only
+    // stage it into the buffer — we don't re-broadcast or re-parse it.
+    if (options.seedOutput) {
+      this.appendOutput(options.seedOutput);
+    }
+
     this.pty.onData((data: string) => {
-      this.outputBuffer = clampBuffer(this.outputBuffer + data);
+      this.lastActivityAt = now();
+      this.appendOutput(data);
       this.updateTerminalState(data);
+      this.answerTerminalQueriesIfHeadless(data);
       this.broadcast({ type: "output", data });
       this.emit("pty_output", { roomId: this.id, data, timestamp: now() });
     });
@@ -170,24 +278,44 @@ export class Room extends EventEmitter {
       console.log(
         `[hay] PTY exit room=${this.id} code=${normalizedExit ?? "null"} signal=${normalizedSignal ?? "null"}`
       );
-      this.endSession({
+      // Spurious-exit guard: an exit event with the shell still alive must not
+      // end the session — a wrongly `ended` room keeps serving output but its
+      // cwd poll and cleanup are permanently dead (observed live: a restored
+      // session whose cwd froze for hours while the shell ran fine). If the
+      // pid still exists shortly after the event, ignore it.
+      const pid = (this.pty as unknown as { pid?: number }).pid;
+      const finish = () => this.endSession({
         exitCode: normalizedExit,
         signal: normalizedSignal,
         message: "Session ended"
       });
+      if (!pid) {
+        finish();
+        return;
+      }
+      setTimeout(() => {
+        try {
+          process.kill(pid, 0); // throws when the process is gone
+          console.log(`[hay] room=${this.id} ignoring spurious exit event (pid ${pid} still alive)`);
+        } catch {
+          finish();
+        }
+      }, 150);
     };
 
     if (typeof this.pty.onExit === "function") {
       this.pty.onExit((event) => {
         handleExit(event.exitCode, event.signal);
       });
-    }
-
-    const legacyOn = (this.pty as unknown as { on?: (event: string, handler: (...args: any[]) => void) => void }).on;
-    if (typeof legacyOn === "function") {
-      legacyOn.call(this.pty, "exit", (exitCode: number, signal?: number) => {
-        handleExit(exitCode, signal);
-      });
+    } else {
+      // Legacy fallback ONLY when onExit is unavailable — registering both
+      // fired every real exit twice.
+      const legacyOn = (this.pty as unknown as { on?: (event: string, handler: (...args: any[]) => void) => void }).on;
+      if (typeof legacyOn === "function") {
+        legacyOn.call(this.pty, "exit", (exitCode: number, signal?: number) => {
+          handleExit(exitCode, signal);
+        });
+      }
     }
 
     // Start PID-based cwd polling as fallback for shells without OSC 7
@@ -226,15 +354,47 @@ export class Room extends EventEmitter {
       } satisfies ServerMessage)
     );
 
-    if (this.outputBuffer) {
+    if (this.outputBytes > 0) {
       socket.send(JSON.stringify({
         type: "snapshot",
-        data: this.outputBuffer,
+        data: boundSnapshotReplay(this.tailOutput(
+          Number.isFinite(info.replayBytes) && (info.replayBytes as number) > 0
+            ? Math.min(SNAPSHOT_REPLAY_BYTES, Math.floor(info.replayBytes as number))
+            : SNAPSHOT_REPLAY_BYTES
+        )),
         alternateScreen: this.alternateScreen,
-        cursorHidden: this.cursorHidden
+        cursorHidden: this.cursorHidden,
+        keyboardEnhanced: this.keyboardEnhanced,
+        mouseReporting: this.mouseReporting,
+        mouseSgr: this.mouseSgr
       } satisfies ServerMessage));
     }
 
+    // The snapshot is a raw byte TAIL, and incremental TUIs (Claude Code/Ink)
+    // never re-emit rows that don't change — e.g. the input box's horizontal
+    // border lines — so the replay can be missing them. When this client's
+    // size differs from the PTY's, the attach resize triggers a full repaint
+    // anyway; when sizes are EQUAL nothing would repaint, so nudge: a one-
+    // column wiggle (tmux's redraw trick) makes full-screen apps repaint.
+    if (
+      info.nudge !== false &&
+      client.cols === this.activeCols &&
+      client.rows === this.activeRows &&
+      this.activeCols > 4 &&
+      !this.ended
+    ) {
+      const cols = this.activeCols;
+      const rows = this.activeRows;
+      try { this.pty.resize(cols - 1, rows); } catch { /* pty may be gone */ }
+      setTimeout(() => {
+        if (this.ended) return;
+        // Only bounce back if nobody claimed a different size meanwhile.
+        if (this.activeCols === cols && this.activeRows === rows) {
+          try { this.pty.resize(cols, rows); } catch { /* pty may be gone */ }
+        }
+      }, 60);
+    }
+
     // Send current cwd to the new client
     socket.send(JSON.stringify({
       type: "cwd_changed",
@@ -272,7 +432,7 @@ export class Room extends EventEmitter {
         this.handleInput(client, message.data);
         break;
       case "resize":
-        this.handleResize(client, message.cols, message.rows);
+        this.handleResize(client, message.cols, message.rows, message.claim, message.user === true);
         break;
       case "typing":
         client.typing = message.active;
@@ -316,6 +476,8 @@ export class Room extends EventEmitter {
     let nextAlternate = this.alternateScreen;
     let nextCursorHidden = this.cursorHidden;
 
+    let nextMouseReporting = this.mouseReporting;
+    let nextMouseSgr = this.mouseSgr;
     while ((match = regex.exec(combined)) !== null) {
       const params = match[1].split(";").filter(Boolean);
       const mode = match[2];
@@ -324,11 +486,36 @@ export class Room extends EventEmitter {
           nextCursorHidden = mode === "l";
         } else if (param === "47" || param === "1047" || param === "1049") {
           nextAlternate = mode === "h";
+        } else if (param === "1000" || param === "1002" || param === "1003") {
+          // Mouse tracking (any flavor) — lets a reattaching client know it can
+          // scroll the app with wheel events instead of coarse Page keys.
+          nextMouseReporting = mode === "h";
+        } else if (param === "1006") {
+          nextMouseSgr = mode === "h";
         }
       }
     }
 
+    // Enhanced keyboard reporting: kitty keyboard protocol (CSI >flags u push /
+    // CSI <n u pop / CSI =flags u set) and xterm modifyOtherKeys (CSI >4;n m).
+    let nextKeyboardEnhanced = this.keyboardEnhanced;
+    const kbdRegex = /\x1b\[([<>=])[0-9;:]*u|\x1b\[>([0-9;]*)m/g;
+    let kbdMatch: RegExpExecArray | null;
+    while ((kbdMatch = kbdRegex.exec(combined)) !== null) {
+      if (kbdMatch[1] !== undefined) {
+        nextKeyboardEnhanced = kbdMatch[1] !== "<"; // push/set = on, pop = off
+      } else {
+        const parts = (kbdMatch[2] ?? "").split(";");
+        if (parts[0] === "4") nextKeyboardEnhanced = (parts[1] ?? "0") !== "0";
+      }
+    }
+
     let stateChanged = false;
+    if (nextMouseReporting !== this.mouseReporting || nextMouseSgr !== this.mouseSgr) {
+      this.mouseReporting = nextMouseReporting;
+      this.mouseSgr = nextMouseSgr;
+      stateChanged = true;
+    }
     if (nextAlternate !== this.alternateScreen) {
       if (DEBUG_STATE) {
         console.log(`[hay] room=${this.id} alternateScreen=${nextAlternate}`);
@@ -336,6 +523,13 @@ export class Room extends EventEmitter {
       this.alternateScreen = nextAlternate;
       stateChanged = true;
     }
+    if (nextKeyboardEnhanced !== this.keyboardEnhanced) {
+      if (DEBUG_STATE) {
+        console.log(`[hay] room=${this.id} keyboardEnhanced=${nextKeyboardEnhanced}`);
+      }
+      this.keyboardEnhanced = nextKeyboardEnhanced;
+      stateChanged = true;
+    }
     if (nextCursorHidden !== this.cursorHidden) {
       if (DEBUG_STATE) {
         console.log(`[hay] room=${this.id} cursorHidden=${nextCursorHidden}`);
@@ -358,9 +552,70 @@ export class Room extends EventEmitter {
       this.parseOsc7(data);
     }
 
+    this.trackBells(data);
+
     this.controlSequenceTail = combined.slice(-CONTROL_SEQUENCE_TAIL);
   }
 
+  // Count attention bells: BEL bytes that are NOT the terminator of an OSC
+  // sequence (title updates, OSC 7 cwd reports, clipboard writes all end in
+  // BEL and must not register). Tracks OSC state across chunk boundaries; a
+  // trailing lone ESC is carried so a split "\x1b]" still opens an OSC.
+  private trackBells(data: string) {
+    let chunk = data;
+    if (this.bellEscCarry) {
+      chunk = "\x1b" + chunk;
+      this.bellEscCarry = false;
+    }
+    if (!this.inOscForBells && chunk.indexOf("\x07") === -1) {
+      // Fast path: no bell to classify; just keep the cross-chunk OSC state.
+      const lastOsc = chunk.lastIndexOf("\x1b]");
+      if (lastOsc !== -1) {
+        const tail = chunk.slice(lastOsc);
+        this.inOscForBells = tail.indexOf("\x07") === -1 && tail.indexOf("\x1b\\") === -1;
+      }
+      if (chunk.endsWith("\x1b")) this.bellEscCarry = true;
+      return;
+    }
+    let bells = 0;
+    let i = 0;
+    const len = chunk.length;
+    while (i < len) {
+      if (this.inOscForBells) {
+        const bel = chunk.indexOf("\x07", i);
+        const st = chunk.indexOf("\x1b\\", i);
+        if (bel === -1 && st === -1) {
+          i = len;
+          break;
+        }
+        if (bel !== -1 && (st === -1 || bel < st)) {
+          this.inOscForBells = false;
+          i = bel + 1;
+        } else {
+          this.inOscForBells = false;
+          i = st + 2;
+        }
+      } else {
+        const bel = chunk.indexOf("\x07", i);
+        const osc = chunk.indexOf("\x1b]", i);
+        if (bel === -1 && osc === -1) break;
+        if (bel !== -1 && (osc === -1 || bel < osc)) {
+          bells += 1;
+          i = bel + 1;
+        } else {
+          this.inOscForBells = true;
+          i = osc + 2;
+        }
+      }
+    }
+    if (!this.inOscForBells && chunk.endsWith("\x1b")) this.bellEscCarry = true;
+    if (bells > 0) {
+      this.bellSeq += bells;
+      this.lastBellAt = now();
+      this.emit("bell", { roomId: this.id, bellSeq: this.bellSeq, timestamp: this.lastBellAt });
+    }
+  }
+
   // Regex: matches OSC 7 with BEL (\x07) or ST (\x1b\\) terminator
   private static readonly OSC7_RE = /\x1b\]7;([^\x07\x1b]*?)(?:\x07|\x1b\\)/g;
 
@@ -438,6 +693,12 @@ export class Room extends EventEmitter {
 
     const poll = () => {
       if (this.ended) return;
+      // node-pty exposes the foreground process name (already short, e.g. "vim",
+      // "node", "claude"); cheap getter, sampled on the same cadence as cwd.
+      const fg = (this.pty as unknown as { process?: string }).process;
+      if (typeof fg === "string" && fg) {
+        this.foregroundProcess = fg.replace(/^-/, ""); // strip login-shell "-zsh" dash
+      }
       if (process.platform === "darwin") {
         execFile("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], { timeout: 5000 }, (err, stdout) => {
           if (err || !stdout) return;
@@ -512,7 +773,7 @@ export class Room extends EventEmitter {
     this.emit("pty_input", { roomId: this.id, clientId: client.id, data, timestamp: now() });
   }
 
-  private handleResize(client: ClientState, cols: number, rows: number) {
+  private handleResize(client: ClientState, cols: number, rows: number, claim?: "attach", userClaim = false) {
     if (!Number.isFinite(cols) || !Number.isFinite(rows)) return;
     if (cols < 1 || cols > 500 || rows < 1 || rows > 200) return;
 
@@ -527,15 +788,47 @@ export class Room extends EventEmitter {
     // 0) only wins when no one else has typed either — so the first/sole client
     // can still size the PTY before typing.
     const maxInputAt = Math.max(...[...this.clients.values()].map((c) => c.lastInputAt));
-    const isActive = client.lastInputAt >= maxInputAt;
+    const othersMaxInputAt = Math.max(
+      0,
+      ...[...this.clients.values()].filter((c) => c.id !== client.id).map((c) => c.lastInputAt)
+    );
+    const claimIdleMs = claim === "attach" ? ATTACH_CLAIM_IDLE_MS : RESIZE_CLAIM_IDLE_MS;
+    // A user-flagged claim is a deliberate human act (clicking a wall tile,
+    // switching to the session): it wins outright. Anyone actively typing
+    // elsewhere reclaims with their next keystroke, so misfires self-heal.
+    const isActive = userClaim ||
+      client.lastInputAt >= maxInputAt || now() - othersMaxInputAt > claimIdleMs;
     if (isActive) {
       this.pty.resize(cols, rows);
       this.activeCols = cols;
       this.activeRows = rows;
       this.activeClientId = client.id;
-      // Broadcast the new active size to other clients so they can adjust
+      // Broadcast the new active size to other clients so they can adjust —
+      // and CONFIRM to the winner: a claimant otherwise learns nothing on
+      // success and can only distinguish accept from reject by timeout.
       this.broadcastActiveSize(client);
+      client.socket.send(
+        JSON.stringify({
+          type: "active_size",
+          clientId: client.id,
+          cols,
+          rows
+        } satisfies ServerMessage)
+      );
       this.emit("pty_resize", { roomId: this.id, clientId: client.id, cols, rows, timestamp: now() });
+    } else if (cols !== this.activeCols || rows !== this.activeRows) {
+      // The resize lost the election (a passive viewer auto-fitted itself).
+      // Snap that client back to the shared size — otherwise its local
+      // terminal re-wraps the buffer at a size the PTY isn't, and it has no
+      // way to learn the real size until the next winning resize.
+      client.socket.send(
+        JSON.stringify({
+          type: "active_size",
+          clientId: this.activeClientId ?? client.id,
+          cols: this.activeCols,
+          rows: this.activeRows
+        } satisfies ServerMessage)
+      );
     }
   }
 
@@ -564,7 +857,9 @@ export class Room extends EventEmitter {
   }
 
   private broadcastPresence() {
-    const clients = [...this.clients.values()].map(toPresence);
+    // Monitor tiles are spectators of the UI, not participants — eight live
+    // tiles must not read as eight viewers in every session.
+    const clients = [...this.clients.values()].filter((c) => c.source !== "monitor").map(toPresence);
     this.broadcast({ type: "presence", clients });
   }
 
@@ -599,6 +894,97 @@ export class Room extends EventEmitter {
     }, CLEANUP_DELAY_MS);
   }
 
+  /**
+   * Headless terminal-identity: hop rooms usually start with NO client
+   * attached, so an app's startup probes — "what's your background color?"
+   * (OSC 10/11), "who are you?" (DA1), "do you support truecolor?"
+   * (XTGETTCAP RGB/Tc) — go unanswered, and the app falls back to its most
+   * conservative palette. Measured live: Claude Code emits only 256-color
+   * SGR in hop while emitting truecolor in iTerm2, purely because iTerm
+   * answers these and nobody here did. When a room is headless, the ROOM is
+   * the terminal — answer as one (dark background, truecolor-capable).
+   * With a client attached, the real terminal answers and we stay silent.
+   */
+  private answerTerminalQueriesIfHeadless(data: string) {
+    if (this.clients.size > 0 || this.ended) return;
+    if (data.indexOf("\x1b") === -1) return;
+    let reply = "";
+    // OSC 10/11: foreground / background color queries — answered with the
+    // LAST VIEWER'S actual colors, so an app that themes itself from the
+    // background (Claude Code picks light vs dark this way) matches what the
+    // user is really looking at. Falls back to the dark default before any
+    // client has ever attached.
+    const osc = (n: number, hex: string) => {
+      const p = (i: number) => hex.slice(i, i + 2).repeat(2);
+      return `\x1b]${n};rgb:${p(0)}/${p(2)}/${p(4)}\x1b\\`;
+    };
+    if (/\x1b\]10;\?(?:\x07|\x1b\\)/.test(data)) reply += osc(10, this.clientFg);
+    if (/\x1b\]11;\?(?:\x07|\x1b\\)/.test(data)) reply += osc(11, this.clientBg);
+    // DA1: identify as a VT220-class terminal (matches xterm.js's own reply).
+    if (/\x1b\[0?c/.test(data)) reply += "\x1b[?62;22c";
+    // DSR 5 (status): "OK".
+    if (/\x1b\[5n/.test(data)) reply += "\x1b[0n";
+    // XTGETTCAP: confirm truecolor for the two conventional capability names
+    // (RGB / Tc, hex-encoded); other capability requests get a valid "not
+    // recognized" so the app never hangs waiting.
+    const tcap = data.match(/\x1bP\+q([0-9a-fA-F;]+)\x1b\\/g);
+    if (tcap) {
+      for (const q of tcap) {
+        const names = (q.slice(4, -2) || "").split(";"); // strip ESC P + q … ESC \
+        for (const hex of names) {
+          const name = Buffer.from(hex, "hex").toString("utf8");
+          if (name === "RGB" || name === "Tc") reply += `\x1bP1+r${hex}\x1b\\`;
+          else reply += `\x1bP0+r${hex}\x1b\\`;
+        }
+      }
+    }
+    if (reply) {
+      try {
+        this.pty.write(reply);
+      } catch {
+        /* pty gone — nothing to answer */
+      }
+    }
+  }
+
+  /** O(1) append; trims whole chunks from the head past MAX_BUFFER_SIZE. */
+  private appendOutput(data: string) {
+    if (!data) return;
+    this.outputChunks.push(data);
+    this.outputBytes += data.length;
+    while (this.outputChunks.length > 1 && this.outputBytes - this.outputChunks[0].length >= MAX_BUFFER_SIZE) {
+      this.outputBytes -= this.outputChunks[0].length;
+      this.outputStart += this.outputChunks[0].length;
+      this.outputChunks.shift();
+    }
+    // A single chunk larger than the whole cap (giant seed/paste): slice once.
+    if (this.outputChunks.length === 1 && this.outputBytes > MAX_BUFFER_SIZE) {
+      const only = this.outputChunks[0].slice(this.outputChunks[0].length - MAX_BUFFER_SIZE);
+      this.outputStart += this.outputChunks[0].length - only.length;
+      this.outputChunks[0] = only;
+      this.outputBytes = only.length;
+    }
+  }
+
+  /**
+   * Join at most the last maxBytes of retained output. Every consumer
+   * (snapshot replay, preview, persistence) needs only a bounded tail, so the
+   * full ring is never flattened.
+   */
+  private tailOutput(maxBytes: number): string {
+    if (this.outputBytes === 0 || maxBytes <= 0) return "";
+    const cap = Math.min(maxBytes, this.outputBytes);
+    const parts: string[] = [];
+    let collected = 0;
+    for (let i = this.outputChunks.length - 1; i >= 0 && collected < cap; i--) {
+      parts.push(this.outputChunks[i]);
+      collected += this.outputChunks[i].length;
+    }
+    parts.reverse();
+    const joined = parts.join("");
+    return joined.length > cap ? joined.slice(joined.length - cap) : joined;
+  }
+
   private endSession(payload: { exitCode: number | null; signal: string | null; message: string; by?: string }) {
     if (this.ended) return;
     this.ended = true;
@@ -623,13 +1009,87 @@ export class Room extends EventEmitter {
     this.emit("empty");
   }
 
+  /**
+   * Bounded source for an on-demand screen preview: the terminal's size plus a
+   * tail of the raw output (enough to reconstruct the visible screen for the
+   * common case of full-repaint TUIs). The actual rendering happens in the
+   * daemon, on demand, only when someone is looking — so idle rooms cost nothing.
+   */
+  getPreviewSource(maxBytes = 65536): { cols: number; rows: number; output: string } {
+    return { cols: this.activeCols, rows: this.activeRows, output: this.tailOutput(maxBytes) };
+  }
+
+  /**
+   * Incremental output for a persistent consumer-side screen parser (the
+   * daemon's preview grids). `since` is an absolute cursor from a previous
+   * call's `offset`; the response is exactly the chars appended after it, so
+   * parser state carries forward with no arbitrary cut points. A cursor
+   * that's unknown, ahead of the stream, fallen off the retained ring, or too
+   * far behind to be worth replaying comes back as `reset: true` with a
+   * bounded tail and a fresh cursor — the caller re-seeds.
+   */
+  /** Remember the viewer's terminal colors for headless OSC 10/11 answers. */
+  setClientColors(bg?: string | null, fg?: string | null) {
+    if (bg && /^[0-9a-f]{6}$/i.test(bg)) this.clientBg = bg.toLowerCase();
+    if (fg && /^[0-9a-f]{6}$/i.test(fg)) this.clientFg = fg.toLowerCase();
+  }
+
+  getOutputSince(
+    since?: number,
+    maxBytes = 1_048_576
+  ): { offset: number; data: string; reset: boolean; cols: number; rows: number } {
+    const end = this.outputStart + this.outputBytes;
+    const dims = { cols: this.activeCols, rows: this.activeRows };
+    if (
+      typeof since !== "number" ||
+      !Number.isFinite(since) ||
+      since < this.outputStart ||
+      since > end ||
+      end - since > maxBytes
+    ) {
+      return { offset: end, data: this.tailOutput(maxBytes), reset: true, ...dims };
+    }
+    // The delta from `since` to the end IS the tail of that length, and
+    // since >= outputStart guarantees every char of it is still retained.
+    const deltaLen = end - since;
+    return { offset: end, data: deltaLen === 0 ? "" : this.tailOutput(deltaLen), reset: false, ...dims };
+  }
+
+  /**
+   * A bounded tail of the raw output, for persisting across a host restart so
+   * `hop restore` can replay the last screen of a plain-shell session. Returns
+   * an empty string for an empty buffer so callers can skip writing a file.
+   */
+  getPersistableBuffer(maxBytes = 65536): string {
+    return this.tailOutput(maxBytes);
+  }
+
+  hasEnded() {
+    return this.ended;
+  }
+
   getSummary(): RoomSummary {
     const localCliCount = [...this.clients.values()].filter((client) => client.source === "local-cli").length;
+    // Read the foreground process name fresh (cheap getter) so the session
+    // manager reflects what's running now; fall back to the last polled sample.
+    let foregroundProcess = this.foregroundProcess;
+    try {
+      const live = (this.pty as unknown as { process?: string }).process;
+      if (typeof live === "string" && live) {
+        foregroundProcess = live.replace(/^-/, "");
+      }
+    } catch {
+      /* keep the polled fallback */
+    }
     return {
       id: this.id,
       cwd: this.initialCwd,
       liveCwd: this.liveCwd,
-      clientCount: this.clients.size,
+      foregroundProcess,
+      lastActivityAt: this.lastActivityAt,
+      bellSeq: this.bellSeq,
+      lastBellAt: this.lastBellAt,
+      clientCount: [...this.clients.values()].filter((c) => c.source !== "monitor").length,
       localCliCount
     };
   }
@@ -645,7 +1105,9 @@ export class RoomManager {
 
   getRoom(roomId: string, initialSize: { cols: number; rows: number }, cwdOrOptions: string | RoomCreateOptions) {
     const existing = this.rooms.get(roomId);
-    if (existing) {
+    // Never hand out a room that already ended — its poll/cleanup are dead and
+    // its pty is (supposed to be) gone. Replace it with a fresh generation.
+    if (existing && !existing.hasEnded()) {
       return existing;
     }
     const options = typeof cwdOrOptions === "string"
@@ -656,7 +1118,12 @@ export class RoomManager {
     }
     const room = new Room(roomId, this.ptyFactory, initialSize, options);
     room.on("empty", () => {
-      this.rooms.delete(roomId);
+      // Generation-safe delete: only remove the mapping if it still points at
+      // THIS room. A late 'empty' from a dead generation must not evict a
+      // freshly created successor under the same id.
+      if (this.rooms.get(roomId) === room) {
+        this.rooms.delete(roomId);
+      }
     });
     this.rooms.set(roomId, room);
     return room;
@@ -683,6 +1150,30 @@ export class RoomManager {
     }
   }
 
+  getRoomPreviewSource(id: string, maxBytes?: number) {
+    const room = this.rooms.get(id);
+    return room ? room.getPreviewSource(maxBytes) : null;
+  }
+
+  getRoomOutputSince(id: string, since?: number, maxBytes?: number) {
+    const room = this.rooms.get(id);
+    return room ? room.getOutputSince(since, maxBytes) : null;
+  }
+
+  /**
+   * Snapshot every live room's tail buffer for persistence across a host
+   * restart. Rooms with no output are omitted. The host script writes these to
+   * disk on shutdown; `hop restore` replays them as `seedOutput`.
+   */
+  getPersistableBuffers(maxBytes?: number): Array<{ id: string; output: string }> {
+    const out: Array<{ id: string; output: string }> = [];
+    for (const room of this.rooms.values()) {
+      const output = room.getPersistableBuffer(maxBytes);
+      if (output) out.push({ id: room.id, output });
+    }
+    return out;
+  }
+
   listRooms(): RoomSummary[] {
     return Array.from(this.rooms.values()).map((room) => room.getSummary());
   }