hop2 0.11.0 → 0.11.2

package/hay/apps/cli/src/index.ts

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { WebSocket } from "ws";
+import http from "node:http";
 import { safeParseServerMessage, type ClientMessage, type PresenceClient } from "hay-shared";
 
 const args = process.argv.slice(2);
@@ -163,11 +164,14 @@ Keyboard shortcuts:
   ${keyLabelLong}+H/J/K/L        Pan viewport, vim-style (Shift = faster)
   ${keyLabelLong}+0             Return to live output (center on cursor)
   ${keyLabelLong}+A             Toggle autofit of remote size to window (saved)
-  ${keyLabelLong}+B             Toggle status bar (saved)
+  ${keyLabelLong}+B             Toggle status bar (this session)
   ${keyLabelLong}+M             Toggle mouse capture (saved)
   ${keyLabelLong}+C             Take/release exclusive control
   ${keyLabelLong}+F             Search scrollback (Enter/↓ next, ↑ prev, Esc close)
-  ${keyLabelLong}+T             Toggle hint bar (saved)
+  ${keyLabelLong}+S             Session panel — list + live preview; ↑↓ fly, Enter switch, Esc close
+  ${keyLabelLong}+R             Rename this session (Enter save, Esc cancel)
+  ${keyLabelLong}+?             Show ALL shortcuts in a full-screen overlay (↑↓ scroll, Esc close)
+  ${keyLabelLong}+T             Toggle hint bar (this session)
   ${keyLabelLong}+\\             Send the next key literally to the remote terminal
                        (lets reserved keys like Ctrl+Q/G reach remote programs)
 
@@ -232,6 +236,14 @@ let remoteMouseModes = new Set<number>();
 let remoteAlternateScreen = false;
 let remoteApplicationCursor = false;
 let pendingPrivateMode = "";
+// Enhanced keyboard reporting the remote app asked for (kitty keyboard protocol /
+// xterm modifyOtherKeys). We mirror the NET state onto the real terminal so keys like
+// Shift+Enter get a distinct encoding that we then forward to the remote verbatim.
+let remoteKittyKeyboard = false;
+let remoteModifyOtherKeys = false;
+let outerKbdEnhanced = false; // what we've actually toggled on the real terminal
+let pendingKbdProto = "";
+const KBD_PROTO_TAIL_CHARS = 24;
 type RgbColor = { r: number; g: number; b: number };
 let defaultFg: RgbColor | null = null;
 let defaultBg: RgbColor | null = null;
@@ -264,6 +276,9 @@ let literalNext = false; // Opt+\ armed: forward the next key verbatim
 let collabMode = true;
 let controllerId: string | null = null;
 let presence: PresenceClient[] = [];
+// Which client last set the shared terminal size. When it's a peer (not us), the
+// status bar shows it so a reshape from someone else's autofit isn't a mystery.
+let activeSizeClientId: string | null = null;
 type NoticeKind = "info" | "ok" | "warn";
 let notice: { message: string; kind: NoticeKind; expiresAt: number } | null = null;
 
@@ -294,6 +309,34 @@ let searchMatchesByRow = new Map<number, number[]>(); // row → match start col
 let searchIndex = -1;
 const SEARCH_MAX_MATCHES = 2000;
 
+// Session panel state (Opt+S): a file-manager-style overlay — session list on
+// the left, a live (cached) screen preview on the right. Arrow to fly through,
+// Enter to switch, Esc to close. Previews are fetched from the hay-host and
+// cached so navigation has no perceived latency.
+type PanelSession = { id: string; cwd: string; process: string; clients: number };
+let sessionPanelMode = false;
+let panelSessions: PanelSession[] = [];
+let panelIndex = 0;
+let panelLoading = false;
+let panelError = "";
+const panelPreviewCache = new Map<string, string[]>();
+let switchingRoom = false;
+
+// Help overlay (Opt+?): a full-screen list of every shortcut, so the keys are
+// reachable even when the hint bar is too narrow to show them all.
+let helpMode = false;
+let helpScroll = 0;
+// Matches Opt+? / Opt+/ in both Option-as-Meta (ESC-prefixed) and macOS
+// Option-as-glyph forms. A bare "?" is intentionally NOT matched so it still
+// types through to the remote.
+const isHelpKey = (input: string) =>
+  input === "\x1b?" || input === "\x1b/" || (isMac && (input === "¿" || input === "÷"));
+
+// Inline rename (Opt+R): edit the session's display name in place. Posts to the
+// local hop daemon's rename API and optimistically updates the label.
+let renameMode = false;
+let renameQuery = "";
+
 let configFile = loadConfig();
 const persistConfig = (patch: Partial<CliConfig>) => {
   configFile = { ...configFile, ...patch };
@@ -310,6 +353,9 @@ let renderScheduled = false;
 let lastRenderCols = 0;
 let lastRenderRows = 0;
 let lastRenderedLines: string[] = []; // previous frame's lines, for dirty-line diffing
+let scrollGeneration = 0;   // bumped on every buffer scroll (xterm onScroll)
+let lastRenderScrollGen = -1; // scrollGeneration captured at the last frame
+let lastRenderTopRow = -1;  // viewY captured at the last frame
 
 // ---- Bar theme -------------------------------------------------------------
 // The bars adapt to the terminal: "auto" (default) resolves light/dark from the
@@ -455,7 +501,7 @@ const getLocalMetrics = () => {
   // toggles just the hint line while the status bar is shown. The reconnect
   // banner forces the line on regardless, so a dropped connection is never silent.
   const reconnecting = !connected && reconnectAttempt > 0;
-  const showHintBar = ((showHints && showBottomBar) || hasNotice || reconnecting || searchMode) && rows >= (showBottomBar ? 3 : 2);
+  const showHintBar = ((showHints && showBottomBar) || hasNotice || reconnecting || searchMode || renameMode) && rows >= (showBottomBar ? 3 : 2);
   const barRows = (showBottomBar ? 1 : 0) + (showHintBar ? 1 : 0);
   return {
     cols,
@@ -476,7 +522,7 @@ let remoteRows = Math.max(1, localMetrics.viewportRows);
 const terminal = new Terminal({
   cols: remoteCols,
   rows: remoteRows,
-  scrollback: 5000,
+  scrollback: 50000,
   allowProposedApi: true
 });
 
@@ -493,6 +539,12 @@ terminal.onData((data) => {
   sendMessage({ type: "input", data });
 });
 
+// Bump a generation counter whenever the buffer scrolls. The dirty-line diff
+// compares screen rows positionally, which is only valid when the buffer→screen
+// mapping is unchanged; a scroll shifts every row's content, so the renderer
+// forces a full repaint when this counter (or the view offset) changed.
+terminal.onScroll(() => { scrollGeneration += 1; });
+
 const filterFocusSequences = (data: string) => data.replace(/\x1b\[I/g, "").replace(/\x1b\[O/g, "");
 
 const getDirectionalKey = (direction: number) => {
@@ -523,10 +575,20 @@ const stripMouseSequences = (data: string) => {
       // Wheel clears any active selection
       clearSelection();
       const direction = wheelAxis === 1 ? 1 : -1;
-      const isTuiLikeMode = remoteAlternateScreen || remoteMouseModes.size > 0;
-      if (isTuiLikeMode) {
+      // A mouse-aware remote (it turned on mouse tracking) gets the real wheel
+      // event — exactly like clicks/drags are passed through below — so it
+      // scrolls natively instead of being fed arrow keys. This is the point of
+      // mouse mode, and it's why the wheel was wrongly arrow-keyed before.
+      if (remoteMouseModes.size > 0) {
+        return sequence;
+      }
+      // A fullscreen app that is NOT tracking the mouse (alt-screen only):
+      // emulate the wheel with arrow keys so paging still works (less, man, a
+      // $PAGER, etc.) where there's no native mouse handling to forward to.
+      if (remoteAlternateScreen) {
         return getDirectionalKey(direction).repeat(SCROLL_STEP);
       }
+      // Normal screen: scroll our own viewport buffer.
       viewY += direction * SCROLL_STEP;
       clampView();
       updateFollowOutputFromViewport();
@@ -1042,6 +1104,78 @@ const trackPrivateModes = (chunk: string) => {
   pendingPrivateMode = combined.slice(-PRIVATE_MODE_TAIL_CHARS);
 };
 
+// Enable/disable enhanced keyboard reporting on the REAL terminal. The remote app
+// (e.g. Claude Code) turns this on so it can see Shift+Enter etc., but because we
+// model its screen in a headless terminal and re-render, that request never reaches
+// the real terminal on its own — so we reflect it here. Idempotent: only writes on a
+// state transition, so plain-shell sessions (no app request) are byte-for-byte
+// unaffected.
+const KBD_ENABLE = "\x1b[>1u\x1b[>4;2m"; // kitty keyboard (disambiguate) + modifyOtherKeys L2
+const KBD_DISABLE = "\x1b[<u\x1b[>4;0m"; // pop kitty + modifyOtherKeys off
+const setOuterKeyboardEnhanced = (on: boolean) => {
+  if (on === outerKbdEnhanced) return;
+  outerKbdEnhanced = on;
+  if (process.stdout.isTTY) process.stdout.write(on ? KBD_ENABLE : KBD_DISABLE);
+};
+
+// Scan remote output for the enhanced-keyboard enable/disable sequences and reflect
+// the resulting NET state onto the real terminal. Claude re-asserts pop+push together
+// (\x1b[<u\x1b[>1u…) so we compute the final state per chunk rather than toggling.
+const KBD_PROTO_REGEX = /\x1b\[([<>=])[0-9;:]*u|\x1b\[>([0-9;]*)m/g;
+const trackKeyboardProtocol = (chunk: string) => {
+  if (!chunk) return;
+  const combined = pendingKbdProto + chunk;
+  KBD_PROTO_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  let lastEnd = 0;
+  while ((match = KBD_PROTO_REGEX.exec(combined)) !== null) {
+    lastEnd = KBD_PROTO_REGEX.lastIndex;
+    if (match[1] !== undefined) {
+      remoteKittyKeyboard = match[1] !== "<"; // push/set = on, pop = off
+    } else {
+      const parts = (match[2] ?? "").split(";");
+      if (parts[0] === "4") remoteModifyOtherKeys = (parts[1] ?? "0") !== "0";
+    }
+  }
+  setOuterKeyboardEnhanced(remoteKittyKeyboard || remoteModifyOtherKeys);
+  // Stash a trailing partial CSI so a sequence split across chunks still resolves.
+  const tailStart = combined.lastIndexOf("\x1b[");
+  if (tailStart !== -1 && tailStart >= lastEnd && /^\x1b\[[<>=]?[0-9;:]*$/.test(combined.slice(tailStart))) {
+    pendingKbdProto = combined.slice(tailStart).slice(-KBD_PROTO_TAIL_CHARS);
+  } else {
+    pendingKbdProto = "";
+  }
+};
+
+// When enhanced keyboard reporting is on, the real terminal encodes hop's OWN shortcut
+// keys in the new scheme too. Translate just those reserved combos back to their legacy
+// bytes so Ctrl+G/Ctrl+Q and the Opt+… shortcuts keep working; everything else is
+// forwarded to the remote verbatim. Returns null when the token isn't a reserved key.
+const RESERVED_CTRL_CODES = new Map<number, string>([[103, "\x07"], [113, "\x11"]]); // Ctrl+G, Ctrl+Q
+const normalizeReservedKey = (token: string): string | null => {
+  if (!outerKbdEnhanced) return null;
+  let code: number;
+  let mods: number;
+  const kitty = /^\x1b\[(\d+)(?:;(\d+))?u$/.exec(token);
+  if (kitty) {
+    code = Number.parseInt(kitty[1], 10);
+    mods = kitty[2] ? Number.parseInt(kitty[2], 10) : 1;
+  } else {
+    const modOther = /^\x1b\[27;(\d+);(\d+)~$/.exec(token);
+    if (!modOther) return null;
+    mods = Number.parseInt(modOther[1], 10);
+    code = Number.parseInt(modOther[2], 10);
+  }
+  const bits = mods - 1;
+  const shift = (bits & 1) !== 0;
+  const alt = (bits & 2) !== 0;
+  const ctrl = (bits & 4) !== 0;
+  if (ctrl && !alt && RESERVED_CTRL_CODES.has(code)) return RESERVED_CTRL_CODES.get(code) ?? null;
+  if (alt && !ctrl && code >= 97 && code <= 122) return "\x1b" + String.fromCharCode(shift ? code - 32 : code);
+  if (alt && !ctrl && code === 92) return "\x1b\\"; // Opt+\ (arms literal mode)
+  return null;
+};
+
 terminal.parser.registerCsiHandler({ prefix: "?", final: "l" }, (params) => {
   applyPrivateModes(params, false);
   return false;
@@ -1064,6 +1198,16 @@ const pushNotice = (message: string, kind: NoticeKind = "info") => {
   scheduleRender();
 };
 
+// Brand context: when a host product (hop) spawns this CLI it sets
+// HAY_BRAND and HAY_REATTACH_CMD so user-facing messages speak the host's
+// language ("[hop] ... Reattach with: hop attach <room>") instead of leaking
+// the internal hay layer. Standalone use keeps the hay defaults.
+const BRAND = process.env.HAY_BRAND || "hay";
+const reattachHint = (room: string) =>
+  process.env.HAY_REATTACH_CMD
+    ? `${process.env.HAY_REATTACH_CMD} ${room}`
+    : `hay -r ${room}`;
+
 const sendMessage = (message: ClientMessage) => {
   if (ws?.readyState === WebSocket.OPEN) {
     ws.send(JSON.stringify(message));
@@ -1123,10 +1267,16 @@ const handleTyping = () => {
 };
 
 const getUrl = () => {
-  const separator = config.server.includes("?") ? "&" : "?";
-  return `${config.server}${separator}room=${encodeURIComponent(config.room)}&name=${encodeURIComponent(
-    config.name
-  )}&cols=${Math.max(2, localMetrics.viewportCols)}&rows=${Math.max(2, localMetrics.viewportRows)}`;
+  // config.server may already carry query params (e.g. `hop attach` bakes in
+  // room/name/source/cwd). Use searchParams.set so switching rooms REPLACES the
+  // baked-in room= instead of appending a second one — the server reads the first
+  // room= value, so an appended duplicate is ignored and switches never take effect.
+  const url = new URL(config.server);
+  url.searchParams.set("room", config.room);
+  url.searchParams.set("name", config.name);
+  url.searchParams.set("cols", String(Math.max(2, localMetrics.viewportCols)));
+  url.searchParams.set("rows", String(Math.max(2, localMetrics.viewportRows)));
+  return url.toString();
 };
 
 const isPidAlive = (pid: number) => {
@@ -1206,6 +1356,12 @@ const setStatus = (nextStatus: typeof status) => {
   scheduleRender();
 };
 
+// One-shot autofit claim per connection (see the active_size handler):
+// "pending" = armed at connect, waiting for the room's true size;
+// "claimed" = claim sent, the next active_size may be the corrective echo;
+// "done" = steady state, peer reshape notices apply.
+let sizeClaimPhase: "pending" | "claimed" | "done" = "done";
+
 const applyRemoteSize = (cols: number, rows: number) => {
   localMetrics = getLocalMetrics();
   const nextCols = Math.max(2, Math.min(cols, 500));
@@ -1223,7 +1379,7 @@ const applyRemoteSize = (cols: number, rows: number) => {
   scheduleRender();
 };
 
-const applySyncSize = () => {
+const applySyncSize = (claim?: "attach") => {
   if (!syncSize) return;
   localMetrics = getLocalMetrics();
   const cols = localMetrics.viewportCols;
@@ -1232,8 +1388,10 @@ const applySyncSize = () => {
   applyRemoteSize(cols, rows);
   if (needsResize) {
     // Protocol rejects resize below 2x2 — clamp so tiny terminals don't send
-    // messages the server refuses.
-    sendMessage({ type: "resize", cols: Math.max(2, cols), rows: Math.max(2, rows) });
+    // messages the server refuses. claim:"attach" (the one-shot claim at
+    // connect) beats the 60s idle election unless a peer typed seconds ago —
+    // attaching is intent, same as the web client opening a session.
+    sendMessage({ type: "resize", cols: Math.max(2, cols), rows: Math.max(2, rows), claim });
   }
 };
 
@@ -1277,6 +1435,9 @@ const initUi = () => {
 const restoreUi = () => {
   if (!uiInitialized || !process.stdout.isTTY) return;
   disableMouseCapture();
+  // Undo any enhanced keyboard reporting we turned on, so the shell we return to
+  // isn't left sending kitty/modifyOtherKeys encodings.
+  setOuterKeyboardEnhanced(false);
   process.stdout.write("\x1b[?25h\x1b[?1049l\x1b[0m");
   uiInitialized = false;
 };
@@ -1663,6 +1824,384 @@ const renderLine = (lineIndex: number, cursorRow: number, cursorCol: number) =>
   return output;
 };
 
+// ===== Session panel (Opt+S): file-manager-style switcher with preview =====
+const panelHttpOrigin = inferServerOrigin(); // http://host:port of the hay-host
+
+const fetchHostJson = (pathname: string): Promise<any> =>
+  new Promise((resolve) => {
+    if (!panelHttpOrigin) { resolve(null); return; }
+    let settled = false;
+    const done = (v: any) => { if (!settled) { settled = true; resolve(v); } };
+    try {
+      const u = new URL(panelHttpOrigin + pathname);
+      const req = http.request(
+        { hostname: u.hostname, port: u.port, path: u.pathname + u.search, method: "GET" },
+        (res) => {
+          if ((res.statusCode || 0) !== 200) { res.resume(); done(null); return; }
+          let data = "";
+          res.on("data", (c) => (data += c));
+          res.on("end", () => { try { done(JSON.parse(data)); } catch { done(null); } });
+        }
+      );
+      req.on("error", () => done(null));
+      req.setTimeout(2000, () => { req.destroy(); done(null); });
+      req.end();
+    } catch { done(null); }
+  });
+
+// Render a preview source ({cols,rows,output}) to plain visible-screen lines via
+// a throwaway headless terminal (same approach the daemon uses for the web).
+const renderPreviewToLines = (source: { cols: number; rows: number; output: string }): Promise<string[]> =>
+  new Promise((resolve) => {
+    const cols = Math.max(2, Math.min(300, Math.floor(Number(source.cols) || 80)));
+    const rows = Math.max(2, Math.min(120, Math.floor(Number(source.rows) || 24)));
+    let t: ReturnType<typeof createPreviewTerm>;
+    try {
+      t = createPreviewTerm(cols, rows);
+    } catch { resolve(["(preview unavailable)"]); return; }
+    t.write(typeof source.output === "string" ? source.output : "", () => {
+      const buf = t.buffer.active;
+      const out: string[] = [];
+      for (let i = 0; i < rows; i++) {
+        const line = buf.getLine(buf.baseY + i);
+        out.push(line ? line.translateToString(true) : "");
+      }
+      try { t.dispose(); } catch { /* ignore */ }
+      while (out.length && !out[out.length - 1].trim()) out.pop();
+      resolve(out.length ? out : ["(blank screen)"]);
+    });
+  });
+const createPreviewTerm = (cols: number, rows: number) =>
+  new Terminal({ cols, rows, scrollback: 0, allowProposedApi: true });
+
+const loadPanelPreview = async (id: string) => {
+  if (panelPreviewCache.has(id)) return;
+  const source = await fetchHostJson(`/rooms/${encodeURIComponent(id)}/preview`);
+  panelPreviewCache.set(id, source ? await renderPreviewToLines(source) : ["(no preview)"]);
+  if (sessionPanelMode) scheduleRender();
+};
+
+const openSessionPanel = async () => {
+  sessionPanelMode = true;
+  panelLoading = true;
+  panelError = "";
+  lastRenderedLines = [];
+  scheduleRender();
+  const data = await fetchHostJson("/rooms");
+  if (!sessionPanelMode) return; // closed while loading
+  panelLoading = false;
+  const rooms = Array.isArray(data?.rooms) ? data.rooms : null;
+  if (!rooms) { panelError = "Could not list sessions (is the host reachable?)"; scheduleRender(); return; }
+  panelSessions = rooms
+    .map((r: any): PanelSession => ({
+      id: String(r?.id || ""),
+      cwd: typeof r?.liveCwd === "string" && r.liveCwd ? r.liveCwd : (typeof r?.cwd === "string" ? r.cwd : ""),
+      process: (typeof r?.foregroundProcess === "string" ? r.foregroundProcess : "").replace(/^-/, ""),
+      clients: Number(r?.clientCount) || 0
+    }))
+    .filter((r: PanelSession) => r.id)
+    .sort((a: PanelSession, b: PanelSession) => a.id.localeCompare(b.id));
+  const cur = panelSessions.findIndex((r) => r.id === config.room);
+  panelIndex = cur >= 0 ? cur : 0;
+  panelPreviewCache.clear();
+  scheduleRender();
+  // Prefetch previews (selected first, then the rest) so flying has no latency.
+  const order = [panelIndex, ...panelSessions.map((_, i) => i).filter((i) => i !== panelIndex)];
+  for (const i of order) { const s = panelSessions[i]; if (s) loadPanelPreview(s.id); }
+};
+
+const closeSessionPanel = () => {
+  if (!sessionPanelMode) return;
+  sessionPanelMode = false;
+  lastRenderedLines = [];
+  scheduleRender();
+};
+
+const movePanelSelection = (delta: number) => {
+  if (!panelSessions.length) return;
+  panelIndex = (panelIndex + delta + panelSessions.length) % panelSessions.length;
+  const s = panelSessions[panelIndex];
+  if (s) loadPanelPreview(s.id);
+  scheduleRender();
+};
+
+const switchToRoom = (id: string) => {
+  if (!id || id === config.room) { closeSessionPanel(); return; }
+  closeSessionPanel();
+  config.room = id;
+  sessionLabel = id;
+  terminal.reset();
+  lastRenderedLines = [];
+  followOutput = true;
+  releaseScrollAnchor();
+  if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+  clearReconnectTicker();
+  reconnectAttempt = 0;
+  pushNotice(`Switching to '${id}'…`);
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+    switchingRoom = true;
+    try { ws.close(); } catch { /* ignore */ }
+  } else {
+    connect();
+  }
+};
+
+const handlePanelInput = (input: string) => {
+  if (input === "\x1b" || input === "\x1bs" || input === "\x1bS" || (isMac && input === "ß")) { closeSessionPanel(); return; }
+  if (input === "\x1b[A" || input === "\x1bOA" || input === "k") { movePanelSelection(-1); return; }
+  if (input === "\x1b[B" || input === "\x1bOB" || input === "j") { movePanelSelection(1); return; }
+  if (input === "\r" || input === "\n") {
+    const s = panelSessions[panelIndex];
+    if (s) switchToRoom(s.id);
+    return;
+  }
+  // Everything else is swallowed while the panel is open.
+};
+
+const renderSessionPanel = (): string[] => {
+  const cols = localMetrics.cols;
+  const rows = localMetrics.rows;
+  const reset = "\x1b[0m";
+  const cell = (text: string, width: number) => {
+    const t = truncateAnsi(text, width);
+    return t + " ".repeat(Math.max(0, width - visibleLength(t)));
+  };
+  const lines: string[] = [];
+
+  // Header
+  const hint = panelLoading
+    ? "loading…"
+    : `${panelSessions.length} session${panelSessions.length === 1 ? "" : "s"} · ↑↓ move · ⏎ switch · Esc close`;
+  const header = ` ${BAR.bold}Sessions${BAR.resetFg}   ${BAR.dim}${hint}${BAR.resetFg}`;
+  lines.push(`${BAR.statusBg}${BAR.fg}${padOrTrim(header, cols)}${reset}`);
+
+  const bodyH = Math.max(1, rows - 2);
+  // Wider list column so each row can show its working dir next to the name.
+  const listW = Math.max(26, Math.min(46, Math.floor(cols * 0.40)));
+  const prevW = Math.max(10, cols - listW - 3);
+  const listStart = panelSessions.length <= bodyH
+    ? 0
+    : Math.max(0, Math.min(panelIndex - Math.floor(bodyH / 2), panelSessions.length - bodyH));
+
+  const sel = panelSessions[panelIndex];
+  let previewLines: string[];
+  if (panelLoading) previewLines = ["Loading sessions…"];
+  else if (panelError) previewLines = [panelError];
+  else if (!panelSessions.length) previewLines = ["No sessions."];
+  else if (sel) previewLines = panelPreviewCache.get(sel.id) || ["loading preview…"];
+  else previewLines = [];
+  const prevStart = Math.max(0, previewLines.length - bodyH);
+
+  for (let b = 0; b < bodyH; b++) {
+    let left: string;
+    const absIdx = listStart + b;
+    if (!panelLoading && absIdx < panelSessions.length) {
+      const s = panelSessions[absIdx];
+      const selected = absIdx === panelIndex;
+      const isCurrent = s.id === config.room;
+      // Session name on the left; working dir dimmed and right-aligned, truncated to fit.
+      const namePart = truncateAnsi(`${selected ? "▸ " : "  "}${s.id}${isCurrent ? " ·here" : ""}`, listW);
+      const nameW = visibleLength(namePart);
+      const avail = Math.max(0, listW - nameW - 1);
+      const cwdText = s.cwd ? formatCwd(s.cwd) : "";
+      const cwd = avail > 0 && cwdText ? truncateAnsi(cwdText, avail) : "";
+      const gap = " ".repeat(Math.max(1, listW - nameW - visibleLength(cwd)));
+      left = selected
+        ? `${BAR.chip}${namePart}${gap}${cwd}\x1b[22m${reset}`
+        : `${BAR.fg}${namePart}${reset}${gap}${BAR.dim}${cwd}${reset}`;
+    } else {
+      left = cell("", listW);
+    }
+    const pline = previewLines[prevStart + b] ?? "";
+    const right = `${BAR.dim}${cell(pline, prevW)}${reset}`;
+    lines.push(`${left} ${BAR.dim}│${reset} ${right}\x1b[K`);
+  }
+
+  // Footer: selected session's working dir + running program
+  let footer: string;
+  if (sel && !panelLoading && !panelError) {
+    const meta = [
+      sel.cwd ? formatCwd(sel.cwd) : "",
+      sel.process ? `running ${sel.process}` : "",
+      sel.clients ? `${sel.clients} viewer${sel.clients === 1 ? "" : "s"}` : ""
+    ].filter(Boolean).join("  ·  ");
+    footer = ` ${BAR.bold}${sel.id}${BAR.resetFg}  ${BAR.dim}${meta}${BAR.resetFg}`;
+  } else {
+    footer = ` ${BAR.dim}${panelError || "Opt+S to close"}${BAR.resetFg}`;
+  }
+  lines.push(`${BAR.hintBg}${BAR.fg}${padOrTrim(footer, cols)}${reset}`);
+
+  return lines;
+};
+
+const openHelp = () => {
+  helpMode = true;
+  helpScroll = 0;
+  lastRenderedLines = [];
+  scheduleRender();
+};
+
+const closeHelp = () => {
+  if (!helpMode) return;
+  helpMode = false;
+  lastRenderedLines = [];
+  scheduleRender();
+};
+
+const handleHelpInput = (input: string) => {
+  if (input === "\x1b" || input === "q" || isHelpKey(input)) { closeHelp(); return; }
+  if (input === "\x1b[A" || input === "\x1bOA" || input === "k") {
+    helpScroll = Math.max(0, helpScroll - 1); scheduleRender(); return;
+  }
+  if (input === "\x1b[B" || input === "\x1bOB" || input === "j") {
+    helpScroll += 1; scheduleRender(); return;
+  }
+  // Everything else is swallowed while help is open.
+};
+
+// ── Inline rename (Opt+R) ──
+const enterRename = () => {
+  renameMode = true;
+  renameQuery = "";
+  scheduleRender();
+};
+
+// The local hop daemon's API address + auth, read from ~/.hop2/.tunnel-state
+// (the same file the daemon writes its pid/port/secret to). Null when there's no
+// reachable local daemon (e.g. a remote `hop client`).
+const readDaemonApi = (): { port: number; secret: string } | null => {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(hopTunnelStateFile, "utf8"));
+    if (!isPidAlive(Number(parsed?.pid))) return null;
+    const port = Number(parsed?.port);
+    const secret = typeof parsed?.sessionSecret === "string" ? parsed.sessionSecret : "";
+    if (!Number.isInteger(port) || port <= 0 || !secret) return null;
+    return { port, secret };
+  } catch {
+    return null;
+  }
+};
+
+const submitRename = (raw: string) => {
+  const newName = raw.trim();
+  if (!newName || newName === sessionLabel || newName === config.room) { scheduleRender(); return; }
+  const api = readDaemonApi();
+  if (!api) {
+    pushNotice("Rename needs the local hop daemon (not available here)", "warn");
+    scheduleRender();
+    return;
+  }
+  const body = JSON.stringify({ oldName: config.room, newName });
+  const req = http.request(
+    {
+      hostname: "127.0.0.1", port: api.port, path: "/api/sessions/rename", method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+        Authorization: `Bearer ${api.secret}`,
+      },
+    },
+    (res) => {
+      let data = "";
+      res.on("data", (c) => (data += c));
+      res.on("end", () => {
+        const ok = (res.statusCode || 0) >= 200 && (res.statusCode || 0) < 300;
+        if (ok) {
+          sessionLabel = newName;
+          pushNotice(`Renamed to ${newName}`, "ok");
+        } else {
+          let msg = `status ${res.statusCode}`;
+          try { msg = JSON.parse(data)?.error || msg; } catch { /* keep status */ }
+          pushNotice(`Rename failed: ${msg}`, "warn");
+        }
+        scheduleRender();
+      });
+    }
+  );
+  req.on("error", (e) => { pushNotice(`Rename failed: ${e.message}`, "warn"); scheduleRender(); });
+  req.setTimeout(2500, () => { req.destroy(); pushNotice("Rename timed out", "warn"); scheduleRender(); });
+  req.write(body);
+  req.end();
+};
+
+const handleRenameInput = (input: string) => {
+  if (input === "\x1b") { renameMode = false; scheduleRender(); return; }
+  if (input === "\r" || input === "\n") {
+    const q = renameQuery;
+    renameMode = false;
+    submitRename(q);
+    return;
+  }
+  if (input === "\x7f" || input === "\b") { renameQuery = renameQuery.slice(0, -1); scheduleRender(); return; }
+  // Accept only characters valid in a session name; ignore the rest (control
+  // sequences, spaces, etc.) so the result is always a legal name.
+  const cleaned = input.replace(/[^A-Za-z0-9_-]/g, "");
+  if (cleaned) { renameQuery = (renameQuery + cleaned).slice(0, 64); scheduleRender(); }
+};
+
+// Full-screen list of every shortcut, grouped. Reachable even when the hint bar
+// is too narrow to show them all (which is the whole point of this overlay).
+const renderHelpOverlay = (): string[] => {
+  const cols = localMetrics.cols;
+  const rows = localMetrics.rows;
+  const reset = "\x1b[0m";
+  const kOpt = (k: string) => (isMac ? `⌥${k}` : `Alt+${k}`);
+  const kCtrl = (k: string) => (isMac ? `⌃${k}` : `Ctrl+${k}`);
+  const groups: Array<[string, Array<[string, string]>]> = [
+    ["Viewport", [
+      [kOpt("←/→/↑/↓"), "pan the view"],
+      [kOpt("H/J/K/L"), "pan (vim keys)"],
+      ["Shift + pan", "pan faster"],
+      [kOpt("0"), "jump back to live output"],
+      [kOpt("A"), "toggle autofit"],
+    ]],
+    ["Session", [
+      [kCtrl("G"), "detach (leave it running)"],
+      [`${kCtrl("Q")} ×2`, "kill the session"],
+      [kOpt("S"), "session switcher"],
+      [kOpt("R"), "rename this session"],
+      [kOpt("C"), "take / release control"],
+    ]],
+    ["Display", [
+      [kOpt("B"), "status bar on/off (this session)"],
+      [kOpt("T"), "hints on/off (this session)"],
+      [kOpt("M"), "mouse capture on/off"],
+    ]],
+    ["Input", [
+      [kOpt("F"), "search the scrollback"],
+      [kOpt("\\"), "send the next key literally"],
+      [kOpt("?"), "this help"],
+    ]],
+  ];
+
+  const body: string[] = [];
+  for (const [title, items] of groups) {
+    if (body.length) body.push("");
+    body.push(` ${BAR.bold}${title}${BAR.resetFg}`);
+    const keyW = Math.max(...items.map(([k]) => visibleLength(k)));
+    for (const [k, desc] of items) {
+      const key = k + " ".repeat(Math.max(0, keyW - visibleLength(k)));
+      body.push(`   ${BAR.fg}${key}${reset}   ${BAR.dim}${desc}${reset}`);
+    }
+  }
+
+  const bodyH = Math.max(1, rows - 2);
+  const maxScroll = Math.max(0, body.length - bodyH);
+  if (helpScroll > maxScroll) helpScroll = maxScroll;
+
+  const lines: string[] = [];
+  const atEnd = helpScroll >= maxScroll;
+  const scrollHint = maxScroll > 0 ? (atEnd ? "↑ more" : "↑↓ scroll") : "";
+  const header = ` ${BAR.bold}Keyboard shortcuts${BAR.resetFg}   ${BAR.dim}${scrollHint}${scrollHint ? " · " : ""}Esc close${BAR.resetFg}`;
+  lines.push(`${BAR.statusBg}${BAR.fg}${padOrTrim(header, cols)}${reset}`);
+  for (let b = 0; b < bodyH; b++) {
+    lines.push(`${padOrTrim(body[helpScroll + b] ?? "", cols)}\x1b[K`);
+  }
+  const footer = ` ${BAR.dim}${kOpt("?")} or Esc to close${maxScroll > 0 && !atEnd ? "  ·  more below ↓" : ""}${BAR.resetFg}`;
+  lines.push(`${BAR.hintBg}${BAR.fg}${padOrTrim(footer, cols)}${reset}`);
+  return lines;
+};
+
 const render = () => {
   if (!process.stdout.isTTY) return;
   initUi();
@@ -1678,6 +2217,34 @@ const render = () => {
     lastRenderedLines = []; // dimensions changed — repaint everything
     forceFull = true;
   }
+  // The dirty-line diff compares screen rows positionally; that's only valid
+  // when the buffer→screen mapping is stable. A scroll (buffer scrolled, or the
+  // user panned the viewport) shifts every row's content, so a positional diff
+  // would skip rows that matched a stale neighbour (lost text) and leave moved
+  // rows behind (duplicated text). Force a full repaint whenever the view
+  // offset or scroll generation changed since the last frame.
+  if (!sessionPanelMode && !helpMode && (viewY !== lastRenderTopRow || scrollGeneration !== lastRenderScrollGen)) {
+    forceFull = true;
+  }
+  lastRenderTopRow = viewY;
+  lastRenderScrollGen = scrollGeneration;
+
+  // Session panel / help overlays take over the whole screen when open.
+  if (sessionPanelMode || helpMode) {
+    const olines = helpMode ? renderHelpOverlay() : renderSessionPanel();
+    let output = "\x1b[?25l";
+    let changed = 0;
+    for (let i = 0; i < localMetrics.rows; i++) {
+      const line = olines[i] ?? "\x1b[K";
+      if (forceFull || line !== lastRenderedLines[i]) {
+        output += `\x1b[${i + 1};1H` + line;
+        changed += 1;
+      }
+    }
+    lastRenderedLines = olines;
+    if (changed > 0) process.stdout.write(output);
+    return;
+  }
 
   const others = presence.filter((client) => client.id !== clientId);
   const controllerName = controllerId
@@ -1714,12 +2281,19 @@ const render = () => {
   const peerNames = others.map((c) => (c.typing ? `${c.name}*` : c.name)).join(", ");
   const peerLabel = others.length ? `peers: ${peerNames}` : "";
   const controlLabel = (!collabMode && controllerName) ? `locked: ${controllerName}` : "";
+  // When a peer is driving the shared size, surface it so a different shape is
+  // explained at a glance (the transient notice covers the moment it changes).
+  const sizeDriverName = (activeSizeClientId && activeSizeClientId !== clientId)
+    ? others.find((c) => c.id === activeSizeClientId)?.name
+    : null;
+  const sizeDriverLabel = sizeDriverName ? `⇄ ${sizeDriverName}` : "";
   const candidateSegments: Array<BarSegment | null> = [
     scrollLabel ? { text: scrollLabel } : null,
     statusLabel ? { text: statusLabel } : null,
     hopDaemonLabel ? { text: hopDaemonLabel, secondary: true, dropPriority: 1 } : null,
     !statusLabel && shareUrl ? { text: shareUrl, secondary: true, dropPriority: 0 } : null,
     autofitLabel ? { text: autofitLabel, secondary: true, dropPriority: 3 } : null,
+    sizeDriverLabel ? { text: sizeDriverLabel, secondary: true, dropPriority: 5 } : null,
     peerLabel ? { text: peerLabel, secondary: true, dropPriority: 4 } : null,
     controlLabel ? { text: controlLabel, secondary: true, dropPriority: 6 } : null,
     { text: "● " } // state dot, rightmost; no dropPriority — always visible
@@ -1760,12 +2334,15 @@ const render = () => {
   const hintPairs: Array<[string, string]> = [
     [kCtrl("G"), "detach"],
     [kCtrl("Q"), "kill"],
+    [kOpt("?"), "help"],
     [kOpt("←→↑↓"), "pan"],
     [kOpt("0"), "live"],
     [kOpt("A"), "autofit"],
     [kOpt("B"), `status ${showStatusBar ? "on" : "off"}`],
     [kOpt("M"), `mouse ${mouseCapture ? "on" : "off"}`],
     [kOpt("F"), "find"],
+    [kOpt("S"), "sessions"],
+    [kOpt("R"), "rename"],
     [kOpt("C"), "control"],
     [kOpt("T"), "hints"],
     [kOpt("\\"), "literal"]
@@ -1773,7 +2350,9 @@ const render = () => {
   const controls = ` ${hintPairs.map(([key, label]) => `${BAR.fg}${key} ${BAR.dim}${label}`).join(" · ")}`;
   const reconnecting = !connected && reconnectAttempt > 0;
   let hintInner: string;
-  if (searchMode) {
+  if (renameMode) {
+    hintInner = `${BAR.accent} rename: ${renameQuery}▏${BAR.resetFg}${BAR.dim}  Enter save · Esc cancel${BAR.resetFg}`;
+  } else if (searchMode) {
     const count = searchQuery
       ? (searchMatches.length > 0
           ? `${searchIndex + 1}/${searchMatches.length}`
@@ -1788,6 +2367,12 @@ const render = () => {
   } else {
     hintInner = noticeText || controls;
   }
+  // When the controls overflow a narrow window, end with a dim ellipsis so it's
+  // clear there are more hints than fit — Opt+? (kept near the front so it
+  // survives truncation) opens the full list.
+  if (hintInner === controls && visibleLength(controls) > localMetrics.cols && localMetrics.cols > 2) {
+    hintInner = truncateAnsi(controls, localMetrics.cols - 2) + `${BAR.dim} …${BAR.resetFg}`;
+  }
   const hintLine = renderBar(
     composeBar(hintInner, "", localMetrics.cols),
     "hint"
@@ -1886,6 +2471,11 @@ const connect = () => {
     lastWsError = null;
     remoteMouseModes.clear();
     remoteAlternateScreen = false;
+    // Recompute enhanced-keyboard state from the fresh snapshot; leave the real
+    // terminal as-is (setOuterKeyboardEnhanced reconciles it idempotently).
+    remoteKittyKeyboard = false;
+    remoteModifyOtherKeys = false;
+    pendingKbdProto = "";
     remoteApplicationCursor = false;
     pendingPrivateMode = "";
     pendingOsc = "";
@@ -1909,6 +2499,10 @@ const connect = () => {
     if (syncSize) {
       applySyncSize();
     }
+    // The sync above is a no-op on a fresh connect: the local size model
+    // starts equal to this window, and the room's true size is only learned
+    // from the first active_size. Arm a one-shot claim for that moment.
+    sizeClaimPhase = "pending";
     scheduleRender();
   });
 
@@ -1952,6 +2546,7 @@ const connect = () => {
       case "output":
         {
           trackPrivateModes(message.data);
+          trackKeyboardProtocol(message.data);
           trackOscColors(message.data);
           const filtered = filterFocusSequences(message.data);
           if (!filtered) return;
@@ -1971,10 +2566,19 @@ const connect = () => {
           if (typeof message.alternateScreen === "boolean") {
             remoteAlternateScreen = message.alternateScreen;
           }
+          // The enable sequence may predate the retained buffer (long-running app), so
+          // trust the server's tracked state to restore enhanced keyboard reporting.
+          if (typeof message.keyboardEnhanced === "boolean") {
+            remoteKittyKeyboard = message.keyboardEnhanced;
+            remoteModifyOtherKeys = message.keyboardEnhanced;
+            setOuterKeyboardEnhanced(message.keyboardEnhanced);
+          }
+          trackKeyboardProtocol(message.data);
           trackOscColors(message.data);
           // reset() (not clear()) so the stale cursor position, SGR attrs, and
           // mode state from the previous connection don't bleed into the replay.
           terminal.reset();
+          lastRenderedLines = []; // post-reset buffer is unrelated to the last frame — repaint fully
           releaseScrollAnchor();
           followOutput = true;
           const filtered = filterFocusSequences(message.data);
@@ -2017,9 +2621,35 @@ const connect = () => {
         }
         break;
       }
-      case "active_size":
+      case "active_size": {
+        const prevCols = remoteCols;
+        const prevRows = remoteRows;
+        activeSizeClientId = message.clientId || null;
         applyRemoteSize(message.cols, message.rows);
+        // Autofit-at-attach: the first active_size is where we learn the
+        // room's real size, so this is the moment to claim it (the server's
+        // idle election decides). One-shot: if the claim loses, the server's
+        // corrective echo lands here as phase "claimed" and must not re-claim
+        // (that would loop) or fire the reshape notice (nobody resized).
+        const claimPhase = sizeClaimPhase;
+        if (claimPhase === "pending") {
+          sizeClaimPhase = "claimed";
+          if (syncSize) {
+            applySyncSize("attach");
+          }
+        } else if (claimPhase === "claimed") {
+          sizeClaimPhase = "done";
+        }
+        // A peer's autofit (or manual resize) just reshaped the shared terminal —
+        // say who and to what, so the new shape isn't a surprise.
+        if (claimPhase === "done" && message.clientId && message.clientId !== clientId &&
+            (message.cols !== prevCols || message.rows !== prevRows)) {
+          const who = presence.find((c) => c.id === message.clientId)?.name || "another client";
+          pushNotice(`${who} resized the terminal to ${message.cols}×${message.rows}`, "info");
+        }
+        scheduleRender();
         break;
+      }
       case "session_ended": {
         shouldReconnect = false;
         // Attribute the kill unless we requested it ourselves; surface a
@@ -2062,6 +2692,11 @@ const connect = () => {
 
   ws.on("close", () => {
     connected = false;
+    if (switchingRoom) {
+      switchingRoom = false;
+      connect(); // reconnect immediately to the newly-selected room
+      return;
+    }
     if (shouldReconnect) {
       setStatus("reconnecting");
       scheduleReconnect();
@@ -2097,13 +2732,13 @@ const cleanupAndExit = () => {
   process.stdin.pause();
   restoreUi();
   if (exitMessage) {
-    console.log(`[hay] ${exitMessage}`);
+    console.log(`[${BRAND}] ${exitMessage}`);
   } else if (exitCode === DETACH_EXIT_CODE) {
-    console.log(`[hay] Detached — session continues in background. Reattach with: hay -r ${config.room}`);
+    console.log(`[${BRAND}] Detached — session continues in background. Reattach with: ${reattachHint(config.room)}`);
   } else if (exitCode === KILL_EXIT_CODE) {
-    console.log("[hay] Session terminated.");
+    console.log(`[${BRAND}] Session terminated.`);
   } else {
-    console.log("[hay] Disconnected");
+    console.log(`[${BRAND}] Disconnected`);
   }
   process.exit(exitCode);
 };
@@ -2162,7 +2797,7 @@ const handleLocalShortcut = (input: string) => {
     } else {
       // Nothing was killed — don't claim the session ended.
       exitCode = KILL_UNREACHABLE_EXIT_CODE;
-      exitMessage = `Could not reach server — the session may still be running. Reattach with: hay -r ${config.room}`;
+      exitMessage = `Could not reach server — the session may still be running. Reattach with: ${reattachHint(config.room)}`;
       try { ws?.close(); } catch (e) { /* connecting socket */ }
       cleanupAndExit();
     }
@@ -2232,9 +2867,10 @@ const handleLocalShortcut = (input: string) => {
     return true;
   }
   if (altKey("b") || altKey("B") || optionChar("∫")) {
+    // Session-only: don't persist, so an in-session toggle never becomes the
+    // default. The default comes from .hop.json (showStatusBar, default true).
     showStatusBar = !showStatusBar;
-    persistConfig({ showStatusBar });
-    pushNotice(`Status bar ${showStatusBar ? "on" : "off"}`, "ok");
+    pushNotice(`Status bar ${showStatusBar ? "on" : "off"} (this session)`, "ok");
     scheduleRender();
     return true;
   }
@@ -2245,9 +2881,10 @@ const handleLocalShortcut = (input: string) => {
     return true;
   }
   if (altKey("t") || altKey("T") || optionChar("†")) {
+    // Session-only (see Opt+B): the default stays whatever .hop.json says
+    // (showHints, default true); toggling here doesn't rewrite it.
     showHints = !showHints;
-    persistConfig({ showHints });
-    pushNotice(`Hints ${showHints ? "on" : "off"}`, "ok");
+    pushNotice(`Hints ${showHints ? "on" : "off"} (this session)`, "ok");
     scheduleRender();
     return true;
   }
@@ -2261,6 +2898,18 @@ const handleLocalShortcut = (input: string) => {
     enterSearch();
     return true;
   }
+  if (altKey("s") || altKey("S") || optionChar("ß")) {
+    void openSessionPanel();
+    return true;
+  }
+  if (isHelpKey(input)) {
+    openHelp();
+    return true;
+  }
+  if (altKey("r") || altKey("R") || optionChar("®")) {
+    enterRename();
+    return true;
+  }
   if (altKey("c") || altKey("C") || optionChar("ç")) {
     // Toggle exclusive control, mirroring the web Take/Release controls so a CLI
     // user on a locked shared session isn't stuck.
@@ -2389,6 +3038,24 @@ process.stdin.on("data", (data) => {
   input = mouseResult.cleaned;
   if (!input) return;
 
+  // While renaming, keys edit the name (never forwarded).
+  if (renameMode) {
+    handleRenameInput(input);
+    return;
+  }
+
+  // While the help overlay is open, keys drive it (never forwarded).
+  if (helpMode) {
+    handleHelpInput(input);
+    return;
+  }
+
+  // While the session panel is open, keys drive the panel (never forwarded).
+  if (sessionPanelMode) {
+    handlePanelInput(input);
+    return;
+  }
+
   // While searching, all keys edit the query / navigate matches (never forwarded).
   if (searchMode) {
     handleSearchInput(input);
@@ -2408,6 +3075,14 @@ process.stdin.on("data", (data) => {
     // shortcut keys handled locally while the rest is forwarded to the shell.
     const tokens = tokenizeInput(input);
     for (const token of tokens) {
+      // With enhanced keyboard reporting on, hop's shortcut keys arrive re-encoded;
+      // translate just those back so they still trigger locally.
+      const legacy = normalizeReservedKey(token);
+      if (legacy !== null) {
+        if (handleLocalShortcut(legacy)) continue;
+        remote += token; // reserved-looking but not a live shortcut → forward the real key
+        continue;
+      }
       if (handleLocalShortcut(token)) continue;
       remote += token;
     }
@@ -2417,13 +3092,15 @@ process.stdin.on("data", (data) => {
   const sanitized = filterFocusSequences(remote);
   if (!sanitized) return;
 
-  if (syncSize) {
-    applySyncSize();
-  }
-
   followOutput = true;
   releaseScrollAnchor();
   sendMessage({ type: "input", data: sanitized });
+  // Autofit AFTER the input: the server elects the resize winner by typing
+  // recency, so the keystroke we just sent is what makes this claim win on
+  // the first key instead of silently losing to a stale election.
+  if (syncSize) {
+    applySyncSize();
+  }
   handleTyping();
 });