hop2 0.11.69 → 0.11.71

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

@@ -0,0 +1,133 @@
+// OSC 8 hyperlinks survive the serialized attach snapshot.
+//
+// A room's attach replay is the headless grid serialized by xterm's
+// serialize addon, which carries colours and styles but not hyperlinks: a
+// cell's link id (OSC 8) is dropped. Codex prints its markdown links as a
+// TITLE with the URL riding underneath, so once a client attached — the
+// usual way of reading a session — every link already on screen was plain
+// text: "codex tile links are not clickable". Live output after the attach
+// still carried them, which is why it looked intermittent.
+//
+// Rather than fork the addon, the serialized string is walked in step with
+// the buffer it came from. The addon's emission is regular: per row, each
+// cell of width > 0 either appends its characters or, when empty, is counted
+// and later skipped with `ESC[nC` (after an optional `ESC[nX`); rows end
+// with `\r\n`, or nothing when the next row is a wrap; width-0 cells (the
+// second half of a wide char) are not emitted. So printable text maps onto
+// cells one by one, and a link run can be wrapped where its first cell is
+// consumed and closed where it ends. Any desync (a cell whose characters are
+// not what the string says next) returns the original string unchanged — a
+// snapshot without links beats a corrupted one.
+
+export type LinkCell = { chars: string; width: number; urlId: number };
+
+export type InjectOptions = {
+  /** Cell at (buffer row, col) — null past the end. */
+  getCell: (row: number, col: number) => LinkCell | null;
+  cols: number;
+  /** First buffer row the serialized string covers. */
+  startRow: number;
+  /** Number of buffer rows it covers. */
+  rowCount: number;
+  /** The link target for a cell's link id, if any. */
+  uriOf: (urlId: number) => string | undefined;
+};
+
+const ESC = "\x1b";
+const BEL = "\x07";
+
+/** Length of the escape sequence starting at `i` (which is ESC). */
+const escapeLength = (s: string, i: number): number => {
+  const next = s[i + 1];
+  if (next === "[") {
+    let j = i + 2;
+    while (j < s.length) {
+      const c = s.charCodeAt(j);
+      if (c >= 0x40 && c <= 0x7e) return j + 1 - i;
+      j++;
+    }
+    return s.length - i;
+  }
+  if (next === "]") {
+    const bel = s.indexOf(BEL, i + 2);
+    const st = s.indexOf(ESC + "\\", i + 2);
+    const end = bel === -1 ? st : st === -1 ? bel : Math.min(bel, st);
+    if (end === -1) return s.length - i;
+    return end + (s[end] === BEL ? 1 : 2) - i;
+  }
+  return Math.min(2, s.length - i);
+};
+
+/** `ESC[nC` → n, else 0. */
+const cursorForward = (seq: string): number => {
+  const m = /^\x1b\[(\d*)C$/.exec(seq);
+  return m ? Math.max(1, Number(m[1] || 1)) : 0;
+};
+
+export const injectHyperlinks = (serialized: string, o: InjectOptions): string => {
+  const endRow = o.startRow + o.rowCount; // exclusive
+  let row = o.startRow;
+  let col = 0;
+  let out = "";
+  let openId = 0;
+  const open = (id: number): boolean => {
+    const uri = o.uriOf(id);
+    if (!uri) return false;
+    out += `${ESC}]8;id=hop${id};${uri}${ESC}\\`;
+    openId = id;
+    return true;
+  };
+  const close = () => {
+    if (openId) out += `${ESC}]8;;${ESC}\\`;
+    openId = 0;
+  };
+  // The content cell at the cursor, skipping the placeholders a wide char
+  // leaves behind. Null past the row's end.
+  const contentCell = (): LinkCell | null => {
+    while (col < o.cols) {
+      const cell = o.getCell(row, col);
+      if (!cell) return null;
+      if (cell.width > 0) return cell;
+      col++;
+    }
+    return null;
+  };
+  let i = 0;
+  while (i < serialized.length) {
+    const ch = serialized[i];
+    if (ch === ESC) {
+      const n = escapeLength(serialized, i);
+      const seq = serialized.slice(i, i + n);
+      // A link is a property of the characters written while it is open;
+      // cursor moves and erases must not carry it, so close across them.
+      // Styling (SGR) inside a run is fine: the id keeps the run one link.
+      if (!/m$/.test(seq)) close();
+      const fwd = cursorForward(seq);
+      if (fwd && row < endRow) col = Math.min(o.cols, col + fwd);
+      out += seq;
+      i += n;
+      continue;
+    }
+    if (ch === "\r" || ch === "\n") {
+      close();
+      out += ch;
+      if (ch === "\n") { row++; col = 0; }
+      i++;
+      continue;
+    }
+    // Printable: the next content cell.
+    if (row >= endRow) { close(); out += serialized.slice(i); return out; }
+    if (col >= o.cols) { row++; col = 0; } // a wrapped row ran straight on
+    const cell = contentCell();
+    if (!cell || !cell.chars || !serialized.startsWith(cell.chars, i)) return serialized;
+    if (cell.urlId !== openId) {
+      close();
+      if (cell.urlId) open(cell.urlId);
+    }
+    out += cell.chars;
+    i += cell.chars.length;
+    col += cell.width;
+  }
+  close();
+  return out;
+};

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

@@ -1,7 +1,7 @@
 // Termshare Server Library
 // Export everything needed for embedding into other apps
 
-export { Room, RoomManager, type SocketAdapter, type ClientInfo, type RoomSummary } from "./rooms";
+export { Room, RoomManager, setDefaultViewerColors, getDefaultViewerColors, type SocketAdapter, type ClientInfo, type RoomSummary } from "./rooms";
 export { createPty, type PtyFactory } from "./pty";
 export { sanitizeName, sanitizeRoom } from "./utils";
 

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

@@ -87,6 +87,27 @@ export type ClientInfo = {
   nudge?: boolean;
 };
 
+// The colors of the LAST viewer anyone had, host-wide. A room usually
+// starts headless — the daemon creates it, the app launches and asks "what's
+// your background?" within milliseconds, and the browser attaches only
+// after — so a per-room memory of "its own last viewer" is empty exactly
+// when it is needed. Codex and Claude pick light vs dark from this answer
+// ONCE, at startup: told the dark default, Codex drew a charcoal composer
+// box on the user's white theme for the rest of the session. The newest
+// viewer's colors are what the user is looking at; every new room answers
+// with them until a viewer of its own says otherwise. Persisted by the host
+// so a restart (restore, keeper re-adoption) keeps the answer.
+const viewerColors = { bg: "0d1117", fg: "e6edf3" };
+const HEX6 = /^[0-9a-f]{6}$/i;
+/** Remember the viewer's colors for every room created from now on. Returns true when they changed. */
+export function setDefaultViewerColors(bg?: string | null, fg?: string | null): boolean {
+  let changed = false;
+  if (bg && HEX6.test(bg) && bg.toLowerCase() !== viewerColors.bg) { viewerColors.bg = bg.toLowerCase(); changed = true; }
+  if (fg && HEX6.test(fg) && fg.toLowerCase() !== viewerColors.fg) { viewerColors.fg = fg.toLowerCase(); changed = true; }
+  return changed;
+}
+export const getDefaultViewerColors = () => ({ ...viewerColors });
+
 export type RoomCreateOptions = {
   cwd: string;
   env?: Record<string, string>;
@@ -286,9 +307,9 @@ export class Room extends EventEmitter {
   // 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";
+  // while headless. Starts as the host-wide last viewer's (see viewerColors).
+  private clientBg = viewerColors.bg;
+  private clientFg = viewerColors.fg;
   private alternateScreen = false;
   // Enhanced keyboard reporting requested by the remote app (kitty keyboard protocol
   // or xterm modifyOtherKeys). Tracked like alternateScreen so a reattaching client
@@ -1364,8 +1385,9 @@ export class Room extends EventEmitter {
    */
   /** 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();
+    if (bg && HEX6.test(bg)) this.clientBg = bg.toLowerCase();
+    if (fg && HEX6.test(fg)) this.clientFg = fg.toLowerCase();
+    setDefaultViewerColors(bg, fg);
   }
 
   getOutputSince(

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

@@ -16,7 +16,15 @@
 // room silently falls back to the raw-tail snapshot (+ wiggle), so a broken
 // dependency degrades to the old behavior instead of breaking attach.
 
+import { injectHyperlinks } from "./hyperlinks";
+
+type HeadlessCell = { getChars(): string; getWidth(): number; extended?: { urlId?: number } };
 type HeadlessTerminal = {
+  rows?: number;
+  cols?: number;
+  buffer?: { active: { length: number; getLine(y: number): { getCell(x: number): HeadlessCell | undefined } | undefined } };
+  // Internals the serialize addon drops (OSC 8 targets); read guardedly.
+  _core?: { _oscLinkService?: { getLinkData(id: number): { uri?: string } | undefined; _dataByLinkId?: Map<number, unknown> } };
   write(data: string, callback?: () => void): void;
   resize(cols: number, rows: number): void;
   loadAddon(addon: unknown): void;
@@ -96,6 +104,26 @@ export type ScreenGrid = {
   dispose(): void;
 };
 
+// The serialize addon drops OSC 8 hyperlinks; put them back from the
+// buffer's own link ids (see hyperlinks.ts). Skipped outright when the grid
+// has registered no link at all — the common case, at no cost.
+const withHyperlinks = (term: HeadlessTerminal, serialized: string, scrollback: number): string => {
+  try {
+    const svc = term._core?._oscLinkService;
+    const buf = term.buffer?.active;
+    if (!svc || !buf || !term.rows) return serialized;
+    if (svc._dataByLinkId && svc._dataByLinkId.size === 0) return serialized;
+    const rowCount = Math.min(buf.length, scrollback + term.rows);
+    return injectHyperlinks(serialized, {
+      cols: term.cols ?? 0, startRow: buf.length - rowCount, rowCount,
+      getCell: (y, x) => { const c = buf.getLine(y)?.getCell(x); return c ? { chars: c.getChars(), width: c.getWidth(), urlId: c.extended?.urlId || 0 } : null; },
+      uriOf: (id) => svc.getLinkData(id)?.uri
+    });
+  } catch {
+    return serialized;
+  }
+};
+
 export const createScreenGrid = (cols: number, rows: number): ScreenGrid | null => {
   if (!deps) return null;
   let term: HeadlessTerminal;
@@ -165,7 +193,8 @@ export const createScreenGrid = (cols: number, rows: number): ScreenGrid | null
         term.write("", () => {
           if (disposed) { callback(null); return; }
           try {
-            callback(addon.serialize({ scrollback: Math.max(0, Math.min(scrollback, GRID_SCROLLBACK)) }));
+            const sb = Math.max(0, Math.min(scrollback, GRID_SCROLLBACK));
+            callback(withHyperlinks(term, addon.serialize({ scrollback: sb }), sb));
           } catch {
             callback(null);
           }

package/hay/apps/server/test/hyperlinks.test.ts

@@ -0,0 +1,99 @@
+// OSC 8 links survive a serialize → inject → replay round trip through real
+// xterm: the replayed terminal's cells carry the same targets, and its text
+// is the serialized terminal's text.
+import { describe, expect, it } from "vitest";
+import { injectHyperlinks } from "../src/hyperlinks";
+
+type Cell = { getChars(): string; getWidth(): number; extended?: { urlId?: number } };
+type Term = {
+  rows: number; cols: number;
+  buffer: { active: { length: number; getLine(y: number): { getCell(x: number): Cell | undefined; translateToString(trim?: boolean): string } | undefined } };
+  write(d: string, cb?: () => void): void;
+  loadAddon(a: unknown): void;
+  _core: { _oscLinkService: { getLinkData(id: number): { uri: string } | undefined } };
+};
+
+const g = globalThis as Record<string, unknown>;
+if (!g.window) g.window = g;
+if (!g.self) g.self = g;
+
+const make = async (cols = 40, rows = 6, scrollback = 100) => {
+  // UMD/CJS under ESM interop: the named exports may live on `default`
+  // (screenGrid.ts resolves them the same way).
+  const h = await import("@xterm/headless") as { Terminal?: unknown; default?: { Terminal?: unknown } };
+  const sz = await import("@xterm/addon-serialize") as { SerializeAddon?: unknown; default?: { SerializeAddon?: unknown } };
+  const Terminal = (h.Terminal ?? h.default?.Terminal) as new (o: Record<string, unknown>) => Term;
+  const SerializeAddon = (sz.SerializeAddon ?? sz.default?.SerializeAddon) as new () => { serialize(o: { scrollback?: number }): string };
+  const term = new Terminal({ cols, rows, scrollback, allowProposedApi: true });
+  const addon = new SerializeAddon();
+  term.loadAddon(addon);
+  const write = (d: string) => new Promise<void>((r) => term.write(d, r));
+  const serialize = (sb = scrollback) => {
+    const s = addon.serialize({ scrollback: sb });
+    const buf = term.buffer.active;
+    const rowCount = Math.min(buf.length, sb + term.rows);
+    return injectHyperlinks(s, {
+      cols: term.cols, startRow: buf.length - rowCount, rowCount,
+      getCell: (y, x) => { const c = buf.getLine(y)?.getCell(x); return c ? { chars: c.getChars(), width: c.getWidth(), urlId: c.extended?.urlId || 0 } : null; },
+      uriOf: (id) => term._core._oscLinkService.getLinkData(id)?.uri
+    });
+  };
+  return { term, write, serialize };
+};
+
+const linksOf = (term: Term) => {
+  const buf = term.buffer.active;
+  const out: { row: number; text: string; uri: string }[] = [];
+  for (let y = 0; y < buf.length; y++) {
+    const line = buf.getLine(y)!;
+    let cur: { row: number; text: string; uri: string } | null = null;
+    for (let x = 0; x < term.cols; x++) {
+      const c = line.getCell(x)!;
+      const uri = c.extended?.urlId ? term._core._oscLinkService.getLinkData(c.extended.urlId)?.uri || "" : "";
+      if (uri && cur && cur.uri === uri) cur.text += c.getChars();
+      else if (uri) { cur = { row: y, text: c.getChars(), uri }; out.push(cur); }
+      else cur = null;
+    }
+  }
+  return out;
+};
+const textOf = (term: Term) => Array.from({ length: term.buffer.active.length }, (_, y) => term.buffer.active.getLine(y)!.translateToString(true)).join("\n").replace(/\n+$/, "");
+
+const L = (uri: string, text: string) => `\x1b]8;;${uri}\x07${text}\x1b]8;;\x07`;
+
+describe("injectHyperlinks — OSC 8 links ride the serialized snapshot", () => {
+  it("a titled link (Codex's markdown link) comes back as a link, text intact", async () => {
+    const a = await make(80);
+    await a.write(`• Wrote the plan: ${L("https://hop.zhoulab.io/view/s_1/plan.html/inline", "proposed next experiments")}.\r\nnext line\r\n`);
+    const b = await make(80);
+    await b.write(a.serialize());
+    expect(textOf(b.term)).toBe(textOf(a.term));
+    expect(linksOf(b.term)).toEqual([{ row: 0, text: "proposed next experiments", uri: "https://hop.zhoulab.io/view/s_1/plan.html/inline" }]);
+  });
+
+  it("colours inside a link, empty gaps, wide characters and a wrapped row all keep their places", async () => {
+    const a = await make(20, 5);
+    await a.write(`\x1b[31mred\x1b[0m   ${L("https://x.test/a", "li\x1b[1mnk\x1b[22m 漢字")}  tail\r\n`);
+    await a.write(`${L("https://x.test/b", "0123456789abcdefghijKLMNOP")}\r\n`); // wraps at 20
+    await a.write(`gap ${L("https://x.test/c", "c")}\x1b[5C${L("https://x.test/d", "d")}\r\n`);
+    const b = await make(20, 5);
+    await b.write(a.serialize());
+    expect(textOf(b.term)).toBe(textOf(a.term));
+    expect(linksOf(b.term)).toEqual(linksOf(a.term));
+    expect(linksOf(b.term).map((l) => l.text)).toEqual(["link 漢字", "0123456789abcdefghij", "KLMNOP", "c", "d"]);
+  });
+
+  it("a snapshot with scrollback trimmed off keeps the links of the rows it covers", async () => {
+    const a = await make(30, 3, 50);
+    for (let i = 0; i < 8; i++) await a.write(`${L(`https://x.test/${i}`, `line ${i}`)}\r\n`);
+    const b = await make(30, 3, 50);
+    await b.write(a.serialize(2)); // 2 rows of history + 3 of screen
+    expect(linksOf(b.term).map((l) => l.uri)).toEqual(["https://x.test/4", "https://x.test/5", "https://x.test/6", "https://x.test/7"]);
+  });
+
+  it("a desync returns the string untouched rather than a corrupted screen", () => {
+    const s = "\x1b[31mhello\x1b[0m";
+    const out = injectHyperlinks(s, { cols: 10, startRow: 0, rowCount: 1, getCell: () => ({ chars: "x", width: 1, urlId: 1 }), uriOf: () => "https://x" });
+    expect(out).toBe(s);
+  });
+});

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

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { RoomManager } from "../src/rooms";
+import { RoomManager, getDefaultViewerColors, setDefaultViewerColors } from "../src/rooms";
 import type { PtyFactory } from "../src/pty";
 
 type Message = { type: string; [key: string]: unknown };
@@ -766,6 +766,28 @@ describe("Room", () => {
       const factory: PtyFactory = () => {
         ptyInstance = new FakePty() as unknown as FakePty;
         return ptyInstance as any;
+
+    it("a NEW headless room answers with the colors the last viewer (of any room) had — a light theme stays light", () => {
+      const ptys: FakePty[] = [];
+      const factory: PtyFactory = () => { const p = new FakePty(); ptys.push(p); return p as any; };
+      const manager = new RoomManager(factory);
+      const first = manager.getRoom("seen", { cols: 80, rows: 24 }, "/tmp");
+      // The browser attached on a white theme (its bg/fg ride on the attach URL).
+      first.setClientColors("ffffff", "1f2328");
+      expect(getDefaultViewerColors()).toEqual({ bg: "ffffff", fg: "1f2328" });
+
+      // The next room is created by the daemon and probed by Codex before any
+      // browser attaches: it is told white, not the dark default.
+      manager.getRoom("fresh", { cols: 80, rows: 24 }, "/tmp");
+      ptys[1].emit("\x1b]10;?\x07\x1b]11;?\x1b\\");
+      const answered = ptys[1].writes.join("");
+      expect(answered).toContain("]11;rgb:ffff/ffff/ffff");
+      expect(answered).toContain("]10;rgb:1f1f/2323/2828");
+
+      // Garbage never replaces a good answer; the dark default is restorable.
+      expect(setDefaultViewerColors("#fff", "nope")).toBe(false);
+      expect(setDefaultViewerColors("0d1117", "e6edf3")).toBe(true);
+    });
       };
       const manager = new RoomManager(factory);
       const room = manager.getRoom(roomId, initialSize, "/tmp");

package/hay/apps/web/src/App.tsx

@@ -16,7 +16,7 @@ import { collectTerminalMatches, selectTerminalMatch } from "./utils/terminalSea
 import { createVoiceHold, speechRecognitionCtor } from "./utils/voiceHold";
 import { tabTitle } from "./utils/tabTitle";
 import { remoteAppOwnsScreen } from "./utils/echoGuard";
-import { urlAtCell, cellAtPoint } from "./utils/urlAtCell";
+import { urlAtCell, cellAtPoint, oscUrlAtCell } from "./utils/urlAtCell";
 import { enableMathHover } from "./utils/mathLinkProvider";
 import { getMathTip } from "./utils/mathTooltip";
 import { scanKeyboardProtocol } from "./utils/keyboardProtocol";
@@ -2147,6 +2147,15 @@ const App = () => {
       scrollSensitivity: 4,
       fastScrollSensitivity: 12,
       minimumContrastRatio: contrastFloorFor(themeMode),
+      // OSC 8 hyperlinks — Codex prints a markdown link as its title with the
+      // URL underneath. xterm's default for these is a confirm() dialog;
+      // open them like the addon's links instead.
+      linkHandler: {
+        activate: (event, uri) => {
+          event.preventDefault();
+          window.open(uri, "_blank", "noopener");
+        }
+      },
       theme: resolveTerminalTheme(themeMode)
     });
     const fitAddon = new FitAddon();
@@ -3866,7 +3875,7 @@ const App = () => {
     return urlAtCell(
       (i) => { const l = buf.getLine(i); return l ? { text: l.translateToString(false), wrapped: l.isWrapped } : null; },
       buf.length, term.cols, bufferRow, col
-    );
+    ) || oscUrlAtCell(term, bufferRow, col);
   }, []);
 
   // Enroll this device's platform authenticator (Touch ID / Face ID) as a

package/hay/apps/web/src/components/SessionSwitcher.tsx

@@ -19,7 +19,7 @@ import { claimOnTileFocus, sizeIsForeign } from "../utils/sizeClaim";
 import { cardPhase, phaseLabel, phaseTitle } from "../utils/agentPhase";
 import { installDragSelect } from "../utils/dragSelect";
 import { enableViewBlocks } from "../utils/viewBlocks";
-import { urlAtCell, cellAtPoint } from "../utils/urlAtCell";
+import { urlAtCell, cellAtPoint, oscUrlAtCell } from "../utils/urlAtCell";
 import { attachScrollFlywheel } from "../utils/scrollFlywheel";
 import { ContextMenu, type MenuRequest } from "./ContextMenu";
 import { CwdField } from "./CwdField";
@@ -396,10 +396,12 @@ const LiveTile = ({ wsBase, room, userName, theme, live, deliberate, claudeApp,
     const rowsEl = boxRef.current?.querySelector(".xterm-rows") as HTMLElement | null;
     const cell = cellAtPoint(screen, rowsEl, term.cols, term.rows, clientX, clientY);
     const buf = term.buffer.active;
-    const url = cell ? urlAtCell(
+    // A URL in the text, reassembled across rows — or the OSC 8 target a
+    // TUI hung on a title (Codex's markdown links), which has no URL text.
+    const url = cell ? (urlAtCell(
       (i) => { const l = buf.getLine(i); return l ? { text: l.translateToString(false), wrapped: l.isWrapped } : null; },
       buf.length, term.cols, buf.viewportY + cell.row, cell.col
-    ) : null;
+    ) || oscUrlAtCell(term, buf.viewportY + cell.row, cell.col)) : null;
     // Diagnostics for "clicking a link in a tile does nothing" reports:
     // localStorage.hay_debug_links=1 prints what the click resolved to.
     try {
@@ -525,6 +527,16 @@ const LiveTile = ({ wsBase, room, userName, theme, live, deliberate, claudeApp,
       fontFamily: monoStack,
       cursorBlink: false,
       disableStdin: true,
+      // OSC 8 hyperlinks (Codex's markdown links show a title, the URL rides
+      // underneath): without a handler xterm throws up a confirm() dialog,
+      // which read as "the link does nothing". Open it like any other link.
+      linkHandler: {
+        activate: (event, uri) => {
+          event.preventDefault();
+          lastLinkOpenAtRef.current = Date.now();
+          window.open(uri, "_blank", "noopener");
+        }
+      },
       theme: theme as never
     });
     const fit = new FitAddon();

package/hay/apps/web/src/utils/urlAtCell.ts

@@ -12,6 +12,32 @@
 
 export type CellLine = { text: string; wrapped: boolean };
 
+/**
+ * The OSC 8 hyperlink under a cell, if the app printed one. Codex renders a
+ * markdown link as its TITLE text carrying the URL as an OSC 8 target —
+ * "proposed next experiments" on screen, the hop view URL underneath — so
+ * there is no URL text for the regex-based addon or urlAtCell to find.
+ * xterm keeps the target on the cell (its link id) and in its link service;
+ * neither is public API, so this reads them guardedly and returns null on
+ * any other xterm. http(s) only: a file:// or custom-scheme target is not
+ * something a click in a browser can open.
+ */
+export const oscUrlAtCell = (term: unknown, bufferRow: number, col: number): string | null => {
+  try {
+    const t = term as {
+      buffer: { active: { getLine: (r: number) => { getCell: (c: number) => unknown } | undefined } };
+      _core?: { _oscLinkService?: { getLinkData: (id: number) => { uri?: string } | undefined } };
+    };
+    const cell = t.buffer.active.getLine(bufferRow)?.getCell(col) as { extended?: { urlId?: number } } | undefined;
+    const id = cell?.extended?.urlId;
+    if (!id) return null;
+    const uri = t._core?._oscLinkService?.getLinkData(id)?.uri;
+    return uri && /^https?:\/\//i.test(uri) ? uri : null;
+  } catch {
+    return null;
+  }
+};
+
 /**
  * The (row, col) under a viewport point. With the DOM renderer each row is
  * an element, so the row comes from whichever one contains the point —

package/hay/apps/web/test/urlAtCell.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { urlAtCell } from "../src/utils/urlAtCell";
+import { oscUrlAtCell, urlAtCell } from "../src/utils/urlAtCell";
 
 const COLS = 42;
 const pad = (s: string) => s.padEnd(COLS, " ");
@@ -48,3 +48,20 @@ describe("urlAtCell", () => {
     expect(urlAtCell(b.get, b.length, COLS, 0, 3)).toBeNull();
   });
 });
+
+describe("oscUrlAtCell — the OSC 8 target under a title (Codex's markdown links)", () => {
+  const fakeTerm = (urlId: number | undefined, uri: string | undefined) => ({
+    buffer: { active: { getLine: (r: number) => (r === 3 ? { getCell: (c: number) => (c === 5 ? { extended: { urlId } } : {}) } : undefined) } },
+    _core: { _oscLinkService: { getLinkData: (id: number) => (id === 7 ? { uri } : undefined) } }
+  });
+  it("resolves the link's URL from the cell's link id", () => {
+    expect(oscUrlAtCell(fakeTerm(7, "https://hop.zhoulab.io/view/s_1/plan.html/inline"), 3, 5)).toBe("https://hop.zhoulab.io/view/s_1/plan.html/inline");
+  });
+  it("nothing for a plain cell, another row, a non-http target, or an xterm without the internals", () => {
+    expect(oscUrlAtCell(fakeTerm(7, "https://x.test/"), 3, 6)).toBeNull();
+    expect(oscUrlAtCell(fakeTerm(7, "https://x.test/"), 2, 5)).toBeNull();
+    expect(oscUrlAtCell(fakeTerm(undefined, "https://x.test/"), 3, 5)).toBeNull();
+    expect(oscUrlAtCell(fakeTerm(7, "file:///etc/hosts"), 3, 5)).toBeNull();
+    expect(oscUrlAtCell({ buffer: { active: { getLine: () => ({ getCell: () => ({ extended: { urlId: 7 } }) }) } } }, 3, 5)).toBeNull();
+  });
+});

package/hop

@@ -21,6 +21,7 @@ const { AuthSessionStore, isSessionToken: isAuthSessionToken } = require('./lib/
 const { agentPhase, screenSaysWorking } = require('./lib/agent-phase');
 const { snapshotFromMetas, planRefiles, pruneList, snapshotFileName } = require('./lib/identity-snapshot');
 const { withCodexIdentity } = require('./lib/codex-identity');
+const { resolveCallerSession, sessionFromEnvLine } = require('./lib/session-identity');
 const checkbacks = require('./lib/checkbacks');
 const digestReads = require('./lib/digest-reads');
 const { rotateAuditFile, sweepStaleAuditDirs } = require('./lib/audit-rotation');
@@ -4787,7 +4788,7 @@ function buildSessionEntries(haySessions, opts = {}) {
             createdAt: config?.createdAt,
             createdBy: effective?.createdBy || 'user',
             agentPermitted: config?.agentPermitted === true,
-            agent: sessionAgentKind(s.name),
+            agent: sessionAgentKind(name),
             localCliCount: clientSummary.localCliCount,
             hasLocalCli: clientSummary.hasLocalCli,
             ...getSessionSeenInfo(name)
@@ -5101,6 +5102,7 @@ if (DAEMON_FLAG && TERMINAL_API_IDLE_TTL_MS > 0) {
 }
 
 function closeTerminalApiEntry(terminalId) {
+    const entry = terminalApiSessions.get(terminalId);
     terminalApiSessions.delete(terminalId);
     const streams = terminalApiStreams.get(terminalId);
     if (streams) {
@@ -5110,6 +5112,12 @@ function closeTerminalApiEntry(terminalId) {
         terminalApiStreams.delete(terminalId);
     }
     clearTerminalEventBuffer(terminalId);
+    // Detach the room client too. This only dropped the daemon's record and
+    // left the socket open, so every check-back delivery and reconcile
+    // redrive left a ghost "checkback"/"reconcile" client on the session
+    // (57 on one room) — idle presence chips across the top bar. The
+    // adapter's close() calls back here with the entry already gone.
+    if (entry?.adapter?.close) { try { entry.adapter.close(); } catch (e) { /* already closing */ } }
 }
 
 function handleTerminalApiServerMessage(terminalId, parsed) {
@@ -8101,6 +8109,56 @@ function isProcessAlive(pid) {
     }
 }
 
+// WHICH session this CLI process is in — by the process tree (its shell's
+// place under the host), not by the inherited HOP_SESSION alone; see
+// lib/session-identity.js. Cached: the tree does not change mid-command.
+let callerSessionMemo = null;
+function readProcForIdentity(pid) {
+    try {
+        if (process.platform === 'linux') {
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+            const after = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const ppid = Number(after[1]) || 0;
+            let command = '';
+            try { command = fs.readFileSync(`/proc/${pid}/cmdline`).toString('utf8').replace(/\0/g, ' ').trim(); } catch (e) { /* gone */ }
+            let session = null;
+            try { const env = fs.readFileSync(`/proc/${pid}/environ`).toString('utf8'); const m = /(?:^|\0)HOP_SESSION=([A-Za-z0-9_-]+)/.exec(env); session = m ? m[1] : null; } catch (e) { /* not ours */ }
+            return { ppid, command, session };
+        }
+        const line = execFileSync('ps', ['-ww', '-o', 'ppid=,command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim();
+        if (!line) return null;
+        const m = /^\s*(\d+)\s+(.*)$/s.exec(line);
+        if (!m) return null;
+        let session = null;
+        try { session = sessionFromEnvLine(execFileSync('ps', ['-Eww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }), m[2]); } catch (e) { /* no env access */ }
+        return { ppid: Number(m[1]) || 0, command: m[2], session };
+    } catch (e) { return null; }
+}
+function callerSession() {
+    if (callerSessionMemo) return callerSessionMemo;
+    const host = readHayHostStateFile();
+    callerSessionMemo = resolveCallerSession({
+        pid: process.pid,
+        hostPid: host && Number.isInteger(host.pid) ? host.pid : null,
+        envSession: process.env.HOP_SESSION || null,
+        readProc: readProcForIdentity
+    });
+    if (process.env.HOP_IDENTITY_DEBUG) {
+        process.stderr.write(`[identity] host=${host?.pid} env=${process.env.HOP_SESSION || ''} → ${JSON.stringify({ ok: callerSessionMemo.ok, session: callerSessionMemo.session, via: callerSessionMemo.via, reason: callerSessionMemo.reason })}\n`);
+        for (const c of callerSessionMemo.chain) process.stderr.write(`[identity]   ${c.pid} ${c.command.slice(0, 90)}\n`);
+    }
+    return callerSessionMemo;
+}
+// The session a CLI command acts on when none was named: the verified one,
+// or nothing — with the reason printed — never an inherited guess.
+function callerSessionOrExplain(what) {
+    const r = callerSession();
+    if (r.ok) { if (r.note) log(r.note, DIM); return r.session; }
+    log(r.note || 'Not inside a hop session.', YELLOW);
+    log(`${what} needs an explicit target: ${CYAN}--session <name>${RESET}`, DIM);
+    return null;
+}
+
 function readHayHostStateFile() {
     if (!fs.existsSync(HAY_HOST_STATE_FILE)) return null;
     try {
@@ -16950,7 +17008,7 @@ async function main() {
         const args = process.argv.slice(3);
         const dryRun = args.includes('--dry-run') || args.includes('-n');
         const named = args.find((a) => !a.startsWith('-')) || null;
-        const here = process.env.HOP_SESSION || null;
+        const here = callerSession().ok ? callerSession().session : null;
         if (!named && !here) {
             log(`Run ${CYAN}hop recover${RESET} inside a hop session, or name one: ${CYAN}hop recover <session>${RESET}`, YELLOW);
             process.exit(1);
@@ -17524,11 +17582,13 @@ async function main() {
     // INTERNAL name, invisible in any UI once the session is renamed, so
     // this resolves the display name humans actually see. --json for agents.
     if (process.argv[2] === 'whoami') {
-        const internal = process.env.HOP_SESSION || '';
+        const who = callerSession();
+        const internal = who.ok ? who.session : '';
         const asJson = process.argv.includes('--json');
+        if (who.ok && who.note && !asJson) log(who.note, DIM);
         if (!internal) {
-            if (asJson) { console.log(JSON.stringify({ insideHopSession: false })); process.exit(1); }
-            log('Not inside a hop session (HOP_SESSION is unset).', YELLOW);
+            if (asJson) { console.log(JSON.stringify({ insideHopSession: false, reason: who.reason || null, note: who.note || null, envSession: process.env.HOP_SESSION || null })); process.exit(1); }
+            log(who.note || 'Not inside a hop session (HOP_SESSION is unset).', YELLOW);
             log(`Publishing from here needs an explicit target: ${CYAN}hop view --session <name> …${RESET}`, DIM);
             process.exit(1);
         }
@@ -17577,7 +17637,7 @@ async function main() {
             process.exit(0);
         }
         if (has('--cancel') || has('--cancel-all')) {
-            const body = has('--cancel') ? { id: flagValue('--cancel') } : { session: flagValue('--session') || process.env.HOP_SESSION || null };
+            const body = has('--cancel') ? { id: flagValue('--cancel') } : { session: flagValue('--session') || callerSessionOrExplain('hop checkback --cancel-all') };
             if (has('--cancel-all') && !body.session) { log('--cancel-all needs --session <name> (or run it inside the session).', RED); process.exit(1); }
             const r = await callLocalApi(state, '/api/checkbacks/cancel', 'POST', body);
             if (!r?.data?.ok) { log(r?.data?.error || 'Cancel failed', RED); process.exit(1); }
@@ -17592,8 +17652,8 @@ async function main() {
             positional.push(argv[i]);
         }
         const message = positional.join(' ').trim();
-        const session = flagValue('--session') || process.env.HOP_SESSION || '';
-        if (!message || !session) { usage(); if (!session) log('No session: pass --session <name> or run inside a hop session.', RED); process.exit(1); }
+        const session = flagValue('--session') || callerSessionOrExplain('hop checkback') || '';
+        if (!message || !session) { usage(); process.exit(1); }
         const body = {
             session, message, force: has('--force'),
             in: flagValue('--in') || undefined, at: flagValue('--at') || undefined,
@@ -17616,7 +17676,7 @@ async function main() {
         }
         // The message rides the ASK record too, so the phone can say WHAT is
         // needed instead of a bare "wants you" (see readAsk / attentionReason).
-        const hs = process.env.HOP_SESSION;
+        const hs = callerSession().ok ? callerSession().session : null;
         if (hs && /^[A-Za-z0-9_-]+$/.test(hs)) {
             try {
                 const file = path.join(CLAUDE_SESSIONS_DIR, `${hs}.ask`);
@@ -17681,7 +17741,12 @@ async function main() {
         // So: explicit --session wins, the environment is the convenience
         // default, and having neither is an ERROR that says how to fix it —
         // never a quiet write into the void.
-        const session = wantSession || process.env.HOP_SESSION || '';
+        // Explicit --session wins; otherwise the VERIFIED caller session (by
+        // the process tree), and with neither this is an error that says why
+        // — never a quiet write into another session's views.
+        const session = wantSession || (callerSession().ok ? callerSession().session : '') || '';
+        if (!wantSession && !session && !wantList) { callerSessionOrExplain('hop view'); process.exit(1); }
+        if (!wantSession && callerSession().note && callerSession().ok) log(callerSession().note, DIM);
         const destDir = path.join(VIEWS_DIR, session);
 
         if (wantList) {
@@ -17804,7 +17869,7 @@ async function main() {
             // three requests past its purpose because nothing in the output
             // ever said "not the session you are in" — the human asked where
             // their files were, and they were in the other room.
-            const here = process.env.HOP_SESSION || '';
+            const here = callerSession().ok ? callerSession().session : '';
             if (here && here === session) {
                 log(`Session: ${session} (this terminal)`, DIM);
             } else if (here) {
@@ -17845,7 +17910,8 @@ async function main() {
         }
         const state = isServerRunning();
         if (!state) { printNotRunningError(); process.exit(1); }
-        const caller = process.env.HOP_SESSION || null;
+        const caller = callerSession().ok ? callerSession().session : null;
+        if (!caller && !flags.has('--standalone') && callerSession().reason === 'shared-daemon') log(callerSession().note, YELLOW);
         const standalone = flags.has('--standalone') || !caller;
         const label = positional[1] || `port-${port}`;
         const name = standalone ? label : `${caller}-${label}`;
@@ -17901,7 +17967,7 @@ async function main() {
         }
         // Name the session it was filed under, so a wrong one is visible at
         // once (an inherited HOP_SESSION can belong to another session).
-        console.log(`Filed under ${getSessionDisplayName(session) || session}${wantSession ? '' : ' (from HOP_SESSION; pass --session <name> to file elsewhere)'}.`);
+        console.log(`Filed under ${getSessionDisplayName(caller) || caller}.`);
         // Same one-bell convention as `hop view` — the human is usually
         // waiting on this, and the link scrolls away unannounced otherwise.
         process.stdout.write('\x07');

package/lib/session-identity.js

@@ -0,0 +1,99 @@
+'use strict';
+// WHICH hop session is this process in? The honest answer comes from the
+// process tree, not from an inherited variable.
+//
+// HOP_SESSION is set on each session's shell by the host, and children
+// inherit it — which is right until something re-parents the work: Codex's
+// shared app-server daemon ran every session's commands and MCP servers
+// under the FIRST session's environment, so `hop view`, `hop checkback` and
+// the MCP tools all defaulted to that one session. An arbitrary default is
+// worse than none.
+//
+// So: walk the parents. The terminal host spawns one shell per session; the
+// ancestor that is a direct child of the host IS the session's shell, and its
+// HOP_SESSION is the truth. If the walk passes through a known multiplexer
+// (Codex's app-server daemon or its code-mode host) the answer is ambiguous
+// — the caller may belong to any session that daemon serves — and the
+// verdict says so instead of guessing. With no host in the chain at all
+// (a plain terminal, a cron), the environment is all there is, and the
+// verdict says that too.
+
+const MAX_HOPS = 24;
+// A multiplexer is recognised by WHAT RUNS, the program and its first word,
+// never by text anywhere in the arguments — a shell whose command line
+// merely mentions "codex app-server" (a test, a grep) is not one.
+const isMultiplexer = (command) => {
+    const words = String(command || '').trim().split(/\s+/);
+    const program = (words[0] || '').split('/').pop();
+    return program === 'codex-code-mode-host' || (program === 'codex' && words[1] === 'app-server');
+};
+
+/**
+ * @param {object} o
+ * @param {number} o.pid                 the calling process
+ * @param {number|null} o.hostPid        the terminal host's pid (null = unknown)
+ * @param {string|null} o.envSession     process.env.HOP_SESSION as inherited
+ * @param {(pid:number)=>{ppid:number, command:string, session?:string|null}|null} o.readProc
+ *        one process: its parent, command line, and the HOP_SESSION in its environment
+ * @returns {{ ok: boolean, session: string|null, via: 'ancestry'|'env'|null, reason?: string, note?: string, chain: Array<{pid:number, command:string}> }}
+ */
+function resolveCallerSession(o) {
+    const chain = [];
+    const env = o.envSession && /^[A-Za-z0-9_-]+$/.test(o.envSession) ? o.envSession : null;
+    let pid = Number(o.pid);
+    let viaDaemon = null;
+    let shellSession = null;
+    // The nearest ancestor whose environment could be read. The session
+    // shell itself is a login zsh whose environment macOS will not show
+    // (`ps -E` prints nothing for it); everything under it inherited the
+    // shell's HOP_SESSION, so the nearest readable one carries the truth —
+    // unless a multiplexer sits in between, which is caught separately.
+    let nearestSession = null;
+    for (let hops = 0; hops < MAX_HOPS && pid && pid > 1; hops++) {
+        const info = o.readProc(pid);
+        if (!info) break;
+        chain.push({ pid, command: String(info.command || '').slice(0, 120) });
+        if (isMultiplexer(info.command)) viaDaemon = viaDaemon || { pid, command: String(info.command || '').slice(0, 80) };
+        // The calling process's own variable is what we are checking, so it
+        // does not count as evidence; its ancestors' do.
+        if (hops > 0 && !nearestSession && info.session) nearestSession = info.session;
+        if (o.hostPid && info.ppid === o.hostPid) {
+            // This process is the session's own shell.
+            shellSession = info.session || nearestSession || null;
+            break;
+        }
+        if (!info.ppid || info.ppid === pid) break;
+        pid = info.ppid;
+    }
+    if (viaDaemon) {
+        return {
+            ok: false, session: null, via: null, chain,
+            reason: 'shared-daemon',
+            note: `This process runs under a shared agent daemon (${viaDaemon.command.trim()}), which serves several sessions — the inherited HOP_SESSION${env ? ` ("${env}")` : ''} may belong to another one. Pass the session explicitly.`
+        };
+    }
+    if (shellSession) {
+        const note = env && env !== shellSession
+            ? `HOP_SESSION says "${env}" but this process lives in session "${shellSession}" (by its shell); using the latter.`
+            : undefined;
+        return { ok: true, session: shellSession, via: 'ancestry', chain, note };
+    }
+    if (env) return { ok: true, session: env, via: 'env', chain, note: o.hostPid ? 'Not under a hop session shell; trusting HOP_SESSION as inherited.' : undefined };
+    return { ok: false, session: null, via: null, chain, reason: 'no-session', note: 'Not inside a hop session (no session shell above this process, and HOP_SESSION is unset).' };
+}
+
+/**
+ * Parse `HOP_SESSION=…` out of a `ps -E` line (macOS): the command line
+ * followed by the environment. Given the plain command line too, only the
+ * ENVIRONMENT part is read — a shell whose arguments contain
+ * "HOP_SESSION=x" (a test, a script) is not thereby in session x.
+ */
+function sessionFromEnvLine(line, plainCommand) {
+    let text = String(line || '');
+    const plain = String(plainCommand || '').trim();
+    if (plain && text.startsWith(plain)) text = text.slice(plain.length);
+    const m = /(?:^|\s)HOP_SESSION=([A-Za-z0-9_-]+)/.exec(text);
+    return m ? m[1] : null;
+}
+
+module.exports = { resolveCallerSession, sessionFromEnvLine, isMultiplexer };

package/mcp/hop-mcp.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const fs = require('fs');
+const { resolveCallerSession: resolveCallerSessionLib, sessionFromEnvLine: sessionFromEnvLineLib } = require(require('path').join(__dirname, '..', 'lib', 'session-identity'));
 const os = require('os');
 const path = require('path');
 const http = require('http');
@@ -2951,6 +2952,43 @@ class TerminalStreamManager {
   }
 }
 
+// WHICH session this MCP server serves — by the process tree, not the
+// inherited HOP_SESSION alone (lib/session-identity.js). Under Codex's
+// shared app-server daemon the inherited value belonged to the first
+// session; the verdict is then "ambiguous", and tools that default to the
+// caller's session ask for it explicitly instead of guessing.
+let callerSessionMemo = null;
+function readProcForIdentity(pid) {
+  const fs = require('fs');
+  const { execFileSync } = require('child_process');
+  try {
+    if (process.platform === 'linux') {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const after = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+      let command = ''; try { command = fs.readFileSync(`/proc/${pid}/cmdline`).toString('utf8').replace(/\0/g, ' ').trim(); } catch { /* gone */ }
+      let session = null; try { const env = fs.readFileSync(`/proc/${pid}/environ`).toString('utf8'); const mm = /(?:^|\0)HOP_SESSION=([A-Za-z0-9_-]+)/.exec(env); session = mm ? mm[1] : null; } catch { /* not ours */ }
+      return { ppid: Number(after[1]) || 0, command, session };
+    }
+    const line = execFileSync('ps', ['-ww', '-o', 'ppid=,command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim();
+    const mm = /^\s*(\d+)\s+(.*)$/s.exec(line);
+    if (!mm) return null;
+    let session = null;
+    try { session = sessionFromEnvLineLib(execFileSync('ps', ['-Eww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }), mm[2]); } catch { /* no env access */ }
+    return { ppid: Number(mm[1]) || 0, command: mm[2], session };
+  } catch { return null; }
+}
+function callerSession() {
+  if (callerSessionMemo) return callerSessionMemo;
+  let hostPid = null;
+  try {
+    const fs = require('fs'); const os = require('os'); const path = require('path');
+    const st = JSON.parse(fs.readFileSync(path.join(process.env.HOP_HOME || path.join(os.homedir(), '.hop2'), '.hay-host-state'), 'utf8'));
+    hostPid = Number.isInteger(st.pid) ? st.pid : null;
+  } catch { /* no host state: env is all there is */ }
+  callerSessionMemo = resolveCallerSessionLib({ pid: process.pid, hostPid, envSession: process.env.HOP_SESSION || null, readProc: readProcForIdentity });
+  return callerSessionMemo;
+}
+
 class HopMCPServer {
   constructor() {
     this.agentId = randomUUID();
@@ -3755,7 +3793,11 @@ class HopMCPServer {
     if (name === 'hop_current_session') {
       // Answerable WITHOUT a daemon: the env fact stands on its own, and an
       // agent asking "where am I" mid-outage still deserves the truth.
-      const internal = process.env.HOP_SESSION || null;
+      const who = callerSession();
+      const internal = who.ok ? who.session : null;
+      if (!internal && who.reason === 'shared-daemon') {
+        return this.wrapApiResult({ insideHopSession: false, ambiguous: true, reason: who.reason, note: who.note, envSession: process.env.HOP_SESSION || null }, { endpoint: 'local' });
+      }
       const payload = {
         insideHopSession: !!internal,
         internalName: internal,
@@ -3785,8 +3827,9 @@ class HopMCPServer {
         return this.wrapApiResult(await this.callApi('GET', '/api/sessions'), { endpoint: '/api/sessions' });
       case 'hop_checkback': {
         const a = args || {};
-        const session = a.session || process.env.HOP_SESSION || null;
-        if (!session) return this.wrapApiResult({ error: 'No session: pass `session` (this MCP is not running inside a hop session).' }, { endpoint: '/api/checkbacks' });
+        const who = callerSession();
+        const session = a.session || (who.ok ? who.session : null);
+        if (!session) return this.wrapApiResult({ error: `No session: pass \`session\`. ${who.note || ''}`.trim() }, { endpoint: '/api/checkbacks' });
         const body = {
           session, message: a.message, force: a.force === true,
           in: a.in, at: a.at, every: a.every, until: a.until,
@@ -3804,7 +3847,7 @@ class HopMCPServer {
         return this.wrapApiResult({ items }, { endpoint: '/api/checkbacks' });
       }
       case 'hop_cancel_checkback':
-        return this.wrapApiResult(await this.callApi('POST', '/api/checkbacks/cancel', { id: (args || {}).id, session: (args || {}).session || (!(args || {}).id ? process.env.HOP_SESSION : undefined) }), { endpoint: '/api/checkbacks/cancel' });
+        return this.wrapApiResult(await this.callApi('POST', '/api/checkbacks/cancel', { id: (args || {}).id, session: (args || {}).session || (!(args || {}).id && callerSession().ok ? callerSession().session : undefined) }), { endpoint: '/api/checkbacks/cancel' });
       case 'hop_list_terminals': {
         const listed = await this.callApi('GET', '/api/terminals');
         if (!this.isApiFailurePayload(listed) && Array.isArray(listed.terminals)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hop2",
-  "version": "0.11.69",
+  "version": "0.11.71",
   "description": "🐰 Hop into your terminal from anywhere. Secure remote shell access with 2FA via Cloudflare Tunnel. Next-gen rewrite with native terminal sharing.",
   "main": "hop",
   "bin": {

package/scripts/hay-host.js

@@ -80,6 +80,21 @@ if (HOP_HOME.startsWith(os.tmpdir())) {
   }, 30000).unref();
 }
 const BUFFER_DIR = path.join(HOP_HOME, 'session-buffers');
+// The last viewer's terminal colors, kept across host restarts: a room that
+// starts headless answers an app's "what's your background?" (OSC 10/11)
+// with these, so Codex/Claude theme themselves light or dark to match what
+// the user actually looks at — restored rooms included.
+const VIEWER_COLORS_FILE = path.join(HOP_HOME, '.hay-viewer-colors');
+function loadViewerColors(hay) {
+    try {
+        const saved = JSON.parse(fs.readFileSync(VIEWER_COLORS_FILE, 'utf8'));
+        if (typeof hay.setDefaultViewerColors === 'function') hay.setDefaultViewerColors(saved.bg, saved.fg);
+    } catch (e) { /* none yet: the dark default */ }
+}
+function rememberViewerColors(hay, bg, fg) {
+    if (typeof hay.setDefaultViewerColors !== 'function') return;
+    if (!hay.setDefaultViewerColors(bg, fg)) return;
+    try { fs.writeFileSync(VIEWER_COLORS_FILE, JSON.stringify(hay.getDefaultViewerColors())); } catch (e) { /* best effort */ }
 const CLAUDE_SESSIONS_DIR = path.join(HOP_HOME, 'claude-sessions');
 
 // Scrub Claude Code SESSION markers from our environment before any PTY is
@@ -220,6 +235,7 @@ function normalizeEnv(rawEnv) {
 async function main() {
     const libPath = path.join(__dirname, '..', 'hay', 'apps', 'server', 'dist', 'lib.js');
     const hay = await import(pathToFileURL(libPath));
+    loadViewerColors(hay);
     const rooms = new hay.RoomManager(hay.createPty);
     const server = http.createServer(async (req, res) => {
         const reqUrl = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
@@ -439,6 +455,7 @@ async function main() {
         const clientFg = hex(wsUrl.searchParams.get('fg'));
         if (clientBg && typeof room.setClientColors === 'function') {
             room.setClientColors(clientBg, clientFg);
+            rememberViewerColors(hay, clientBg, clientFg);
         }
         // Tab identity forwarded by the daemon: the room evicts a same-key
         // predecessor on attach, so a phone's reconnect replaces its own

package/tests/session-identity.unit.test.cjs

@@ -0,0 +1,79 @@
+// Which session a process is in: by its shell's place under the host, never
+// by an inherited variable when a multiplexer sits in between.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { resolveCallerSession, sessionFromEnvLine, isMultiplexer } = require('../lib/session-identity');
+
+const HOST = 1428;
+const table = (rows) => (pid) => rows[pid] || null;
+
+test('a command under claude under the session shell resolves by ancestry', () => {
+  const readProc = table({
+    900: { ppid: 800, command: 'hop view report.html' },
+    800: { ppid: 700, command: 'claude --resume abc' },
+    700: { ppid: HOST, command: '/bin/zsh -lc env -u CLAUDE_CONFIG_DIR claude --resume abc', session: 's_room1' }
+  });
+  const r = resolveCallerSession({ pid: 900, hostPid: HOST, envSession: 's_room1', readProc });
+  assert.equal(r.ok, true); assert.equal(r.session, 's_room1'); assert.equal(r.via, 'ancestry'); assert.equal(r.note, undefined);
+});
+
+test('the shell wins over a lying environment, and says so', () => {
+  const readProc = table({
+    900: { ppid: 700, command: 'hop checkback --in 5m x' },
+    700: { ppid: HOST, command: '/bin/zsh', session: 's_room1' }
+  });
+  const r = resolveCallerSession({ pid: 900, hostPid: HOST, envSession: 's_other', readProc });
+  assert.equal(r.session, 's_room1'); assert.equal(r.via, 'ancestry'); assert.match(r.note, /HOP_SESSION says "s_other"/);
+});
+
+test("the session shell's environment is unreadable on macOS: the nearest readable ancestor below it speaks for it", () => {
+  const readProc = table({
+    900: { ppid: 850, command: 'hop whoami', session: 's_lie' },        // the caller's own variable is not evidence
+    850: { ppid: 800, command: '/bin/zsh -c snapshot', session: 's_room1' },
+    800: { ppid: 700, command: 'claude --resume abc', session: 's_room1' },
+    700: { ppid: HOST, command: '/bin/zsh -lc env -u CLAUDE_CONFIG_DIR claude', session: null }
+  });
+  const r = resolveCallerSession({ pid: 900, hostPid: HOST, envSession: 's_lie', readProc });
+  assert.equal(r.session, 's_room1'); assert.equal(r.via, 'ancestry'); assert.match(r.note, /says "s_lie"/);
+});
+
+test("under Codex's shared app-server daemon the answer is AMBIGUOUS, not the daemon owner's", () => {
+  const readProc = table({
+    950: { ppid: 940, command: 'node /x/hop-mcp.js' },
+    940: { ppid: 930, command: '/x/bin/codex app-server --listen unix:// --managed-daemon' },
+    930: { ppid: 920, command: '/x/bin/codex app-server daemon pid-update-loop' },
+    920: { ppid: 910, command: '/x/bin/codex resume 01a0' },
+    910: { ppid: HOST, command: '/bin/zsh', session: 'Accessibility-fork-codex' }
+  });
+  const r = resolveCallerSession({ pid: 950, hostPid: HOST, envSession: 'Accessibility-fork-codex', readProc });
+  assert.equal(r.ok, false); assert.equal(r.session, null); assert.equal(r.reason, 'shared-daemon');
+  assert.match(r.note, /shared agent daemon/); assert.match(r.note, /Pass the session explicitly/);
+});
+
+test('no session shell above and no variable: not inside hop; with the variable: trusted as inherited', () => {
+  const readProc = table({ 300: { ppid: 200, command: 'bash' }, 200: { ppid: 1, command: 'login' } });
+  const none = resolveCallerSession({ pid: 300, hostPid: HOST, envSession: null, readProc });
+  assert.equal(none.ok, false); assert.equal(none.reason, 'no-session');
+  const env = resolveCallerSession({ pid: 300, hostPid: HOST, envSession: 's_cron', readProc });
+  assert.equal(env.ok, true); assert.equal(env.session, 's_cron'); assert.equal(env.via, 'env');
+});
+
+test('a process the table cannot read stops the walk gracefully', () => {
+  const r = resolveCallerSession({ pid: 5, hostPid: HOST, envSession: 's_x', readProc: () => null });
+  assert.equal(r.session, 's_x'); assert.equal(r.via, 'env');
+});
+
+test('HOP_SESSION is read out of the ENVIRONMENT part of a ps -E line, never out of the arguments', () => {
+  assert.equal(sessionFromEnvLine('/bin/zsh -lc claude HOP_SESSION=s_abc PATH=/usr/bin TERM=xterm', '/bin/zsh -lc claude'), 's_abc');
+  assert.equal(sessionFromEnvLine('/bin/zsh PATH=/usr/bin', '/bin/zsh'), null);
+  // The shell's own command text mentions a session; its environment says another.
+  assert.equal(sessionFromEnvLine('/bin/zsh -c HOP_SESSION=s_lie ./hop whoami HOME=/u HOP_SESSION=s_true', '/bin/zsh -c HOP_SESSION=s_lie ./hop whoami'), 's_true');
+  assert.equal(sessionFromEnvLine('/bin/zsh -c HOP_SESSION=s_lie ./hop whoami HOME=/u', '/bin/zsh -c HOP_SESSION=s_lie ./hop whoami'), null);
+});
+
+test('a multiplexer is the program that runs, not a mention in some argument list', () => {
+  assert.equal(isMultiplexer('/x/releases/0.159/bin/codex app-server --listen unix:// --managed-daemon'), true);
+  assert.equal(isMultiplexer('/x/bin/codex-code-mode-host'), true);
+  assert.equal(isMultiplexer('/opt/homebrew/bin/codex --no-daemon resume 01a0'), false);
+  assert.equal(isMultiplexer('/bin/zsh -c "echo codex app-server is a string"'), false);
+});